Merge remote-tracking branch 'origin/main' into feat/erika-rust-mdx

Author: Princesseuh

.agents/skills/astro-developer/SKILL.md

@@ -125,8 +125,8 @@ See [testing.md](testing.md) for complete patterns and examples.
 
 ## Related Documentation
 
-- Root: [/AGENTS.md](/Users/ema/www/withastro/astro/AGENTS.md)
-- Root: [/CONTRIBUTING.md](/Users/ema/www/withastro/astro/CONTRIBUTING.md)
+- Root: [/AGENTS.md](../../../AGENTS.md)
+- Root: [/CONTRIBUTING.md](../../../CONTRIBUTING.md)
 - Astro docs: https://docs.astro.build/llms.txt
 - Package: packages/astro/src/core/README.md
 - Build plugins: packages/astro/src/core/build/plugins/README.md

.agents/skills/triage/comment.md

@@ -35,24 +35,38 @@ Generate and return a GitHub comment following the template below.
 
 The **Fix** line in the template has three possible forms. Choose the one that matches the triage outcome:
 
-1. **You created a fix:** Use `I was able to fix this issue.` and include the suggested fix link.
+1. **You created a fix:** Use `I found a potential fix for this issue.` and include the suggested fix link. Avoid claiming certainty, even if the fix passes tests, frame it as a suggestion that needs human review.
 2. **The issue is already fixed on main** (e.g. the user is on an older major version and the bug doesn't reproduce on current main): Use `This issue has already been fixed.` and tell the user how to get the fix (e.g. upgrade). Link the relevant upgrade guide if applicable: [v6](https://docs.astro.build/en/guides/upgrade-to/v6/), [v5](https://docs.astro.build/en/guides/upgrade-to/v5/).
-3. **You could not find or create a fix:** Use `I was unable to find a fix for this issue.` and give guidance or a best guess at where the fix might be.
+3. **Low-confidence or no fix:** Use `I wasn't able to find a fix, but I identified some areas that may be relevant.` and list the files/code paths that seem related. Frame this as a jumping-off point for a human, not a diagnosis. If a failing test was added, mention it.
+4. **No leads at all:** Use `I was unable to determine the cause of this issue.` This should be rare, only use it when you genuinely have nothing useful to point to.
 
 ### "Priority" Instructions
 
 The **Priority** line communicates the severity of this issue to maintainers. Its goal is to answer the question: **"How bad is it?"**
 
-Select exactly ONE priority label from the `priorityLabels` arg. Use the label descriptions to guide your decision, combined with the triage report's root cause and impact analysis. Render it in bold, with the `- ` prefix removed, like this: `**Priorty P2: Has Workaround.** Then, follow it with 1-2 sentences explaining _why_ you chose that priority. Answer: "who is likely to be affected and under what conditions?". If you are unsure, use your best judgment based on the label descriptions and the triage findings.
+Select exactly ONE priority label from the `priorityLabels` arg. Use the label descriptions to guide your decision, combined with the triage report's root cause and impact analysis. Render it in bold, with the `- ` prefix removed, like this: `**Priority P2: Has Workaround.**` Then, follow it with 1-2 sentences explaining _why_ you chose that priority. Answer: "who is likely to be affected and under what conditions?". If you are unsure, use your best judgment based on the label descriptions and the triage findings.
+
+**Priority calibration — err on the side of lower priority:**
+
+- **Experimental/unstable features** should almost never be higher than P3. Users of experimental features accept instability. (e.g. a broken option in `experimental.fonts`)
+- **Niche adapter/integration combos** (e.g. MDX + Svelte + Cloudflare) are typically P3 or lower unless they affect a core workflow.
+- **P4 vs P5** — the key question is breadth: how many typical Astro users would hit this in a standard workflow? (e.g. P4: wrong output for a common routing pattern; P5: `astro build` crashes for most projects)
+- **P2: Has Workaround vs P2: Nice to Have** — pick based on whether something behaves unexpectedly (but circumventable) vs. simply a convenience gap (e.g. Has Workaround: unexpected behavior with a way to restructure around it; Nice to Have: cosmetic issue in an error message). If there is no workaround at all, consider P3 or higher instead.
+- **When selecting between similar labels**, always refer to their descriptions in `priorityLabels` to make the final call.
+- **When in doubt, go lower.** A P3 that gets bumped up by a maintainer is much better than a P5 that causes false alarm.
 
 ### Template
 
+The comment must start with an at-a-glance summary, followed by short explanations, then the full report in a collapsible section. Keep the top section scannable, a maintainer should understand the status in under 5 seconds and be able to quickly jump into fixing the issue.
+
 ```markdown
-**[I was able to reproduce this issue. / I was unable to reproduce this issue.]** [2-3 sentences describing the root cause, result, and key observations.]
+- **Reproduced:** [Yes / No / Skipped — reason]
+- **Exploration:** [Yes / No / Partial / Already fixed on main] [If `branchName` is non-null: — [View branch](https://github.com/withastro/astro/compare/{branchName}?expand=1)]
+- **Priority:** [See "Priority" Instructions above. Keep to one line explaining why this priority was chosen, who is likely to be affected, and under what conditions (this section should answer the question: "how bad is it?")]
 
-**[See "Fix" Instructions above.]** [1-2 sentences describing the solution, where/when it was already fixed, or guidance on where a fix might be.] [If `branchName` is non-null: [View Suggested Fix](https://github.com/withastro/astro/compare/{branchName}?expand=1)]
+[2-3 sentences describing the root cause or key observations, or where/when it was already fixed. Be specific about what's happening and where in the codebase.]
 
-**[See "Priority" Instructions above.]** [1-2 sentences explaining why this priority was chosen, who is likely to be affected, and under what conditions (this section should answer the question: "how bad is it?")]
+**[See "Fix" Instructions above.]** [1-2 sentences describing the fix in more detail: what was changed, guidance on where a fix might be, or relevant code areas.]
 
 <details>
 <summary><em>Full Triage Report</em></summary>
@@ -61,7 +75,7 @@ Select exactly ONE priority label from the `priorityLabels` arg. Use the label d
 
 </details>
 
-_This report was made by an LLM. Mistakes happen, check important info._
+_This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue._
 ```
 
 ## Result

.agents/skills/triage/diagnose.md

@@ -61,6 +61,8 @@ Iterate until you understand:
 - What data is being passed
 - Where the logic diverges from expected behavior
 
+Once done, **revert all instrumentation** before moving on. Use `git checkout -- <file>` to remove your `console.log` additions from `packages/`. Debug logs must not leak into downstream steps.
+
 ## Step 4: Identify Root Cause
 
 Once you understand the issue, document:
@@ -75,6 +77,9 @@ Consider:
 - Is this a regression from a recent change?
 - Does this affect other similar use cases?
 - Are there edge cases to consider?
+- Never suggest removing a user's dependency (adapters, framework integrations, features like MDX or DB) as a fix, those are things the user needs. The fix must work within the user's existing stack and expected feature-set.
+
+**Tone calibration:** Describe the root cause factually, not dramatically. Avoid language that overstates impact ("critical flaw", "fundamentally broken", "severe vulnerability") unless the evidence genuinely supports it. A missing null check is a missing null check, not a "critical oversight in the rendering pipeline." The diagnosis should help a maintainer understand what's wrong, guiding them towards a fix, not alarm them.
 
 ## Step 5: Write Output
 

.agents/skills/triage/fix.md

@@ -35,7 +35,19 @@ Read `report.md` from the `triageDir` directory to understand:
 - The suggested approach
 - Any edge cases to consider
 
-**Skip if prerequisites unmet:** Check `report.md`: If bug not reproduced/skipped OR diagnosis confidence is `low`/`null` OR no root cause found → append "FIX SKIPPED: [reason]" to `report.md` and return `fixed: false`.
+**Skip if prerequisites unmet:** Check `report.md`: If bug was not reproduced or was skipped → append "FIX SKIPPED: Not reproduced" to `report.md` and return `fixed: false`. Do NOT attempt a fix based on guesswork when you cannot reproduce or diagnose the issue.
+
+**Low-confidence path:** If diagnosis confidence is `low` or `null`, or no clear root cause was found → do NOT attempt a code fix. Instead:
+
+1. Identify the most likely area(s) of the codebase related to the issue (files, functions, code paths).
+2. If possible, write a failing test that demonstrates the expected behavior described in the issue. Place it alongside existing tests for that area.
+3. If you identified specific code paths, add brief inline comments (prefixed `// TRIAGE:`) near the most relevant lines in `packages/` to help the implementor orient quickly. Keep to 2-3 comments max — these are signposts, not a diagnosis.
+4. Append to `report.md`: the areas you identified, why they seem relevant, and any failing test or comments you added.
+5. Return `fixed: false`.
+
+This "breadcrumb" approach is more useful to maintainers than a wrong fix.
+
+**High-confidence path:** If diagnosis confidence is `medium` or `high` and a clear root cause was identified → proceed with implementing a fix as described in the steps below.
 
 **Note:** The repo may be messy from previous steps. Check `git status` and either work from the current state or `git reset --hard` to start clean.
 
@@ -55,6 +67,7 @@ Make changes in `packages/` source files. Follow these principles:
 - Only change what's necessary to fix the bug
 - Don't refactor unrelated code
 - Don't add new features
+- **Never "fix" an issue by removing a user's dependency.** Removing an adapter (Cloudflare, Netlify, Vercel, etc.), framework integration (Svelte, React, Vue, etc.), or feature (MDX, DB, etc.) is not a fix, these are things the user needs. The fix must work within the user's existing stack or expected feature set.
 
 **Consider edge cases:**