auto-triage bot improvements

.agents/skills/triage/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: triage
-description: Triage a bug report. Reproduces the bug, diagnoses the root cause, and attempts a fix. Use when asked to "triage issue #1234", "triage this bug", or similar.
+description: Triage a bug report. Reproduces the bug, diagnoses the root cause, verifies whether the behavior is intentional, and attempts a fix. Use when asked to "triage issue #1234", "triage this bug", or similar.
 ---
 
 # Triage
 
-Triage a bug report end-to-end: reproduce the bug, diagnose the root cause, and attempt a fix.
+Triage a bug report end-to-end: reproduce the bug, diagnose the root cause, verify whether the behavior is intentional, and attempt a fix.
 
 ## Input
 
@@ -35,7 +35,16 @@ After completing diagnosis, check your confidence:
 - If confidence is **low** — skip to Output.
 - If confidence is **medium** or **high** — continue to Step 3.
 
-## Step 3: Fix
+## Step 3: Verify
+
+Read and follow [verify.md](verify.md). Use a subagent for this step to isolate context.
+
+After completing verification, check the verdict:
+
+- If the verdict is **intended-behavior** — skip to Output. The issue is not a bug; do not attempt a fix.
+- If the verdict is **bug** or **unclear** — continue to Step 4.
+
+## Step 4: Fix
 
 Read and follow [fix.md](fix.md). Use a subagent for this step to isolate context.
 

.agents/skills/triage/comment.md

@@ -2,7 +2,7 @@
 
 Generate a GitHub issue comment from triage findings.
 
-**CRITICAL: You MUST always produce a GitHub comment as your final output, regardless of what input files are available. Even if `report.md` is missing or empty, you must still produce a comment. In that case, produce a minimal comment stating that automated triage could not be completed.**
+**CRITICAL: You MUST always read `report.md` and produce a GitHub comment as your final output, regardless of what input files are available. Even if `report.md` is missing or empty, you must still produce a comment. In that case, produce a minimal comment stating that automated triage could not be completed.**
 
 ## Prerequisites
 
@@ -36,13 +36,11 @@ Generate and return a GitHub comment following the template below.
 ### Template
 
 ```markdown
-**[I was able to reproduce this issue. / I was unable to reproduce this issue.]** [1-2 sentences describing the result and key observations.]
+**[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.]
 
-**Fix:** **[I was able to fix this issue. / I was unable to fix this issue]** [1-2 sentences describing the solution and key observations. Even if no fix was created, you can still use this space to give guidance or "a best guess" at where the fix might be.] [If `branchName` arg is non-null, include this link: [View Fix](https://github.com/withastro/astro/compare/{branchName}?expand=1)]
+**Fix:** **[I was able to fix this issue. / I was unable to fix this issue]** [1-2 sentences describing the solution and key observations. Even if no fix was created, you can still use this space to give guidance or "a best guess" at where the fix might be.] [If `branchName` arg is non-null, include this link: [View Suggested Fix](https://github.com/withastro/astro/compare/{branchName}?expand=1)]
 
-**Cause:** [Single sentence explaining the root cause - or just the word "Unknown" if not determined.]
-
-**Impact:** [Single sentence describing who is affected and how - or just the word "Unknown" if not determined.]
+**Impact:** [Single sentence describing how you would have triggered the bug - or just the word "Unknown" if not determined.]
 
 <details>
 <summary><em>Full Triage Report</em></summary>

.agents/skills/triage/diagnose.md

@@ -2,14 +2,15 @@
 
 Find the root cause of a reproduced bug in the Astro source code.
 
-**CRITICAL: You MUST always append to `report.md` before finishing, regardless of outcome. Even if you cannot identify the root cause, hit errors, or the investigation is inconclusive — always update `report.md` with your findings. The orchestrator and downstream skills depend on this file to determine what happened.**
+**CRITICAL: You MUST always read `report.md` and append to `report.md` before finishing, regardless of outcome. Even if you cannot identify the root cause, hit errors, or the investigation is inconclusive — always update `report.md` with your findings. The orchestrator and downstream skills depend on this file to determine what happened.**
 
 ## Prerequisites
 
 These variables are referenced throughout this skill. They may be passed as args by an orchestrator, or inferred from the conversation when run standalone.
 
 - **`triageDir`** — Directory containing the reproduction project (e.g. `triage/issue-123`). If not passed as an arg, infer from previous conversation.
 - **`report.md`** — File in `triageDir` that MAY exist. Contains the full context from all previous skills.
+- **Astro Compiler source** — The `withastro/compiler` repo MAY be cloned at `../compiler` (a sibling of the Astro repo root). If it exists, treat it as in-scope for diagnosis. Some bugs originate in the compiler rather than in `packages/` — if stack traces or investigation point to compiler behavior (e.g. HTML parsing, `.astro` file transformation), check `../compiler` for relevant source code.
 
 ## Overview
 
@@ -21,11 +22,7 @@ These variables are referenced throughout this skill. They may be passed as args
 
 ## Step 1: Review the Reproduction
 
-Read `report.md` from the `triageDir` directory to understand:
-
-- The exact error message and stack trace
-- Which command triggers the issue (build/dev/preview)
-- What user code is involved
+Start by reading `report.md` from the `triageDir` directory.
 
 **Skip if not reproduced:** If `report.md` shows the bug was NOT reproduced or was skipped (look for "could not reproduce", "SKIP REASON", "skipped: true"), append "DIAGNOSIS SKIPPED: No reproduction" to `report.md` and return `confidence: null`.
 

.agents/skills/triage/fix.md

@@ -2,24 +2,27 @@
 
 Develop and verify a fix for a diagnosed Astro bug.
 
-**CRITICAL: You MUST always append to `report.md` before finishing, regardless of outcome. Even if the fix attempt fails, you encounter errors, or you cannot resolve the bug — always update `report.md` with your findings. The orchestrator and downstream skills depend on this file to determine what happened.**
+**CRITICAL: You MUST always read `report.md` and append to `report.md` before finishing, regardless of outcome. Even if the fix attempt fails, you encounter errors, or you cannot resolve the bug — always update `report.md` with your findings. The orchestrator and downstream skills depend on this file to determine what happened.**
 
 ## Prerequisites
 
 These variables are referenced throughout this skill. They may be passed as args by an orchestrator, or inferred from the conversation when run standalone.
 
 - **`triageDir`** — Directory containing the reproduction project (e.g. `triage/issue-123`). If not passed as an arg, infer from previous conversation.
 - **`report.md`** — File in `triageDir` that MAY exist. Contains the full context from all previous skills.
+- **Astro Compiler source** — The `withastro/compiler` repo MAY be cloned at `../compiler` (sibling of the Astro repo root). If it exists and the root cause is in the compiler, investigate and propose fixes there. This clone is **reference only** — it is not wired into the monorepo's dependencies, so compiler changes cannot be tested end-to-end here. Document proposed compiler changes and diff in `report.md` instead.
 
 ## Overview
 
 1. Review the diagnosis from `report.md`
-2. Implement a minimal fix in `packages/`
-3. Rebuild the affected package(s)
-4. Verify the fix resolves the reproduction
-5. Ensure no regressions
-6. Generate git diff
-7. Append fix details to `report.md`
+2. Verify fix feasibility (browser/runtime compatibility)
+3. Implement a minimal fix in `packages/`
+4. Rebuild the affected package(s)
+5. Verify the fix resolves the reproduction
+6. Ensure no regressions
+7. Generate git diff
+8. Append fix details to `report.md`
+9. Clean up the working directory
 
 ## Step 1: Review the Diagnosis
 
@@ -33,7 +36,14 @@ Read `report.md` from the `triageDir` directory to understand:
 
 **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.
 
-## Step 2: Implement the Fix
+## Step 2: Verify Fix Feasibility
+
+Consider your potential fixes and verify that any modern features you plan to use are supported:
+
+- **Node.js:** When writing code for the runtime (server, build logic, integrations, etc.), target Node.js version `>=22.12.0`.
+- **Browsers:** If your fix relies on browser support for any web platform feature, check the browser compatibility table on MDN to confirm it is supported across our browser targets. Do not treat specification compliance as proof of browser support. If the feature lacks sufficient support, choose a different approach.
+
+## Step 3: Implement the Fix
 
 Make changes in `packages/` source files. Follow these principles:
 
@@ -69,7 +79,7 @@ export function renderComponent(component: AstroComponent, props: Props) {
 }
 ```
 
-## Step 3: Rebuild the Package
+## Step 4: Rebuild the Package
 
 After making changes, rebuild the affected package:
 
@@ -79,15 +89,15 @@ pnpm -C packages/astro build    # or packages/integrations/<name>
 
 Watch for build errors — fix any TypeScript issues before proceeding.
 
-## Step 4: Verify the Fix
+## Step 5: Verify the Fix
 
 Re-run the reproduction, often using `pnpm run build`/`astro build` or `pnpm run dev`/`astro dev`.
 
-## Step 5: Check for Regressions
+## Step 6: Check for Regressions
 
 Test that you didn't break anything new, and that normal cases still work. If you find regressions, refine the fix to handle all cases.
 
-## Step 6: Generate Git Diff
+## Step 7: Generate Git Diff
 
 From the repository root, generate the diff:
 
@@ -97,7 +107,7 @@ git diff packages/
 
 This captures all your changes for the report.
 
-## Step 7: Write Output
+## Step 8: Write Output
 
 Append your fix details to the existing `report.md` (written by reproduce and diagnose skills).
 
@@ -112,7 +122,7 @@ The report must include all information needed for a final GitHub comment to be
 - Any alternative approaches considered and their tradeoffs
 - If the fix failed: what was tried and why it didn't work
 
-## Step 8: Clean Up the Working Directory
+## Step 9: Clean Up the Working Directory
 
 1. Run `git status` and review all changed files
 2. Revert any changes that are NOT part of the fix:

.agents/skills/triage/reproduce.md

@@ -2,7 +2,7 @@
 
 Reproduce a GitHub issue to determine if a bug is valid and reproducible.
 
-**CRITICAL: You MUST always write `report.md` to the triage directory before finishing, regardless of outcome. Even if you encounter errors, cannot reproduce the bug, hit unexpected problems, or need to skip — always write `report.md`. The orchestrator and downstream skills depend on this file to determine what happened. If you finish without writing it, the entire pipeline fails silently.**
+**CRITICAL: You MUST always read `report.md` and write `report.md` to the triage directory before finishing, regardless of outcome. Even if you encounter errors, cannot reproduce the bug, hit unexpected problems, or need to skip — always write `report.md`. The orchestrator and downstream skills depend on this file to determine what happened. If you finish without writing it, the entire pipeline fails silently.**
 
 ## Prerequisites
 
@@ -21,11 +21,11 @@ These variables are referenced throughout this skill. They may be passed as args
 
 ## Step 1: Confirm Bug Details
 
-Confirm that you have access to `bugDetails` (load directly from GitHub if you do not, following the instructions above).
+Confirm that you have access to `issueDetails` (load directly from GitHub if you do not, following the instructions above).
 
 **Otherwise**, fail — we cannot triage a bug that we have no details on.
 
-Once you have `bugDetails`, read carefully:
+Once you have `issueDetails`, read carefully:
 
 - The bug description and expected vs actual behavior
 - Any reproduction steps provided
@@ -36,7 +36,7 @@ Once you have `bugDetails`, read carefully:
 
 Before attempting reproduction, check if this issue should be skipped due to a limitation of our sandbox reproduction environment.
 
-If any early exit condition is met, skip to Step 6 and write `report.md` with the skip details.
+If any early exit condition is met, skip to Step 5 and write `report.md` with the skip details.
 
 **Comment Handling for Early Exits:** Sometimes future comments will provide additional reproductions. An early exit is only valid if not future comments in that issue "invalidate" it. For example, if the original poster of a bug was on Astro 3.0, we would exit initially (`unsupported-version`). However, on a future run, if a commenter had later posted a similar reproduction but on the latest version of Astro, we would no longer consider that a valid early exit, and would instead continue on with the workflow.
 
@@ -46,6 +46,12 @@ The following are the documented early exit conditions that we support:
 
 Skip if the issue is not a bug report. This workflow can only triage bugs — feature requests, suggestions, and discussions are not actionable here.
 
+### Missing Details (`missing-details`)
+
+Skip if the issue is missing a valid reproduction (see below for list of supported valid reproductions).
+Skip if the issue is missing a description of the user's expected result (ex: "What's the expected result?" section of our issue template is filled out).
+We need both of these to successfully reproduce, and later to verify the expected results.
+
 ### Unsupported Astro Version (`unsupported-version`)
 
 Skip if the bug targets Astro 4.x or earlier. Look for version in `astro info` output or package.json mentions.
@@ -67,41 +73,65 @@ Skip if a repository maintainer has commented that this issue should not be repr
 
 ## Step 3: Set Up Reproduction Project
 
-The reproduction project goes in the `triageDir` directory (e.g. `triage/gh-123`). If no `triageDir` is provided, default to `triage/gh-<issue_number>`.
+Every bug report should include some sort of reproduction. The reproduction project goes in the `triageDir` directory (e.g. `triage/gh-123`). If no `triageDir` is provided, default to `triage/gh-<issue_number>`.
+
+Set up the reproduction project based on what the issue provides you. Once the reproduction project directory has been completed, run `pnpm install` in the workspace to connect it to the rest of the monorepo.
+
+### StackBlitz Project URL (`https://stackblitz.com/edit/...`)
+
+If reproduction was provided as a Stackblitz project URL, download it into the `triageDir` directory using `stackblitz-clone`:
+
+```bash
+npx stackblitz-clone@latest <stackblitz-url> <triageDir>
+```
+
+### StackBlitz GitHub URL (`https://stackblitz.com/github/...`)
+
+StackBlitz has a special, commonly-used URL to open a GitHub repo in StackBlitz. If we have received one of these as reproduction, parse out the GitHub org & repo names and then treat it as a GitHub URL, following the "GitHub URL" step below.
+
+### GitHub URL (`https://github.com/...`)
+
+If reproduction was provided as a GitHub repo URL, clone the repo into the triage directory and remove the `.git` directory to avoid conflicts with the host repo:
+
+```bash
+gh repo clone <owner>/<repo> <triageDir>
+rm -rf <triageDir>/.git
+```
+
+If a specific branch or subdirectory is referenced, check out that branch before removing `.git`, or copy only the relevant subdirectory.
 
-**If a StackBlitz URL is provided in the issue:**
-The triage workspace has already been downloaded. Inspect what's there and proceed to configuration.
+### Gist URL (`https://gist.github.com/`)
 
-**If no StackBlitz URL (fallback to example template):**
-The workspace has been set up from `examples/minimal`. You may need to add dependencies.
+Use `gh gist view <gist-id>` to fetch the gist contents, to help understand the reproduction. You may still need to set up a project from scratch (see fallback below) and apply the gist files into it.
 
-Sometimes, a user will provide a Gist URL instead of a StackBlitz URL to help show how to reproduce the issue. Use `gh gist view <gist-id>` to fetch any included gists, to help get a better understanding of what the problem is.
+### Manual Steps Reproduction
 
-Check the issue to determine what's needed:
+If no reproduction URL is provided, you will need to follow the manual steps that the user provided instead.
 
-- React components → `pnpm astro add react` (in the triage dir)
-- MDX content → `pnpm astro add mdx`
-- Specific adapter → `pnpm astro add node` (or vercel, netlify, etc.)
+Scaffold a fresh Astro project into the triage directory using `create-astro`. Use `--no-install` to skip dependency installation (we will run `pnpm install` later) and `--no-git` to avoid creating a nested git repo. Use `--template` to pick a starting template — if the user didn't mention a specific one, use `minimal` as the default.
 
-## Step 4: Configure the Triage Project
+```bash
+npx create-astro@latest <triageDir> --template minimal --no-install --no-git -y
+```
 
-Based on the issue, modify the triage project:
+Then, modify the triage project as needed:
 
 1. Update `astro.config.mjs` with required configuration
-2. Create pages, components, or middleware that trigger the bug
-3. Add any additional files mentioned in the issue
+2. Add any required dependencies or Astro integrations (`@astrojs/react`, etc.)
+3. Create pages, components, or middleware that trigger the bug
+4. Add/modify any additional files mentioned in the issue
 
 Keep the reproduction as minimal as possible — only add what's needed to trigger the bug.
 
-## Step 5: Attempt Reproduction in the Triage Project
+## Step 4: Attempt Reproduction in the Triage Project
 
 Use all of the tools at your disposal — `pnpm run dev|build|preview|test`, `curl`, `agent-browser`, etc.
 
 1. **Trigger the bug.** Follow the reproduction steps from the issue and confirm that the bug appears.
 2. **Verify the baseline.** Remove or reverse the triggering code and confirm the project works without the bug. This guards against false positives — if the project is still broken without the triggering code, the issue may be in your setup, not the reported bug.
 3. **Document what you observe.** Record exact error messages and stack traces, which command triggers the issue, and whether it's consistent or intermittent.
 
-## Step 6: Write Output
+## Step 5: Write Output
 
 Write `report.md` to the triage directory: