diff --git a/.agents/skills/triage/SKILL.md b/.agents/skills/triage/SKILL.md index d012ce6877d9..d1969af23c82 100644 --- a/.agents/skills/triage/SKILL.md +++ b/.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. diff --git a/.agents/skills/triage/comment.md b/.agents/skills/triage/comment.md index ecbf304e7a20..ff4c2e326e22 100644 --- a/.agents/skills/triage/comment.md +++ b/.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 @@ -11,6 +11,7 @@ These variables are referenced throughout this skill. They may be passed as args - **`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 (reproduction, diagnosis, fix). - **`branchName`** — The branch name where a fix was pushed. If not passed as an arg, infer from previous conversation. +- **`priorityLabels`** — An array of `{ name, description }` objects representing the available priority labels for the repository. Used to select a priority in the comment. ## Overview @@ -27,22 +28,28 @@ If `report.md` is missing or empty, generate a minimal comment (see "Fallback" s Generate and return a GitHub comment following the template below. -### Special Cases +### "Fix" Instructions -- **If the user is on a different major version than the current monorepo, and the issue could not be reproduced in the current monorepo:** In the "Fix" section of your comment, the best guidance you can provide is to suggest that the user upgrade to that newer major version to fix their issue, even if that newer major version is a beta release. Link to the relevant upgrade guide: - - v6: https://v6.docs.astro.build/en/guides/upgrade-to/v6/ - - v5: https://docs.astro.build/en/guides/upgrade-to/v5/ +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. +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://v6.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. + +### "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 the chosen label name in bold (without the `- ` prefix), 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. ### 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.] - -**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)] +**[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.] -**Cause:** [Single sentence explaining the root cause - or just the word "Unknown" if not determined.] +**Fix:** **[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)] -**Impact:** [Single sentence describing who is affected and how - or just the word "Unknown" if not determined.] +**Priority:** **[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?")]
Full Triage Report @@ -54,11 +61,14 @@ Generate and return a GitHub comment following the template below. _This report was made by an LLM. Mistakes happen, check important info._ ``` -## Optional Follow-up Task +## Result + +You MUST RETURN the generated comment text so that the user can review and post it themselves. -You MAY SUGGEST to the user, as a potential follow-up step, to post the issue to GitHub directly. However you CANNOT DO THIS STEP unless the user explicitly asks. +You MAY SUGGEST to the user that you (or they) could post the comment to the GitHub issue. **Do not post the comment yourself** — this should only be a suggestion. It would be a horrifying abuse of trust to the user if you posted to GitHub on their behalf without their explicit permission. ```bash +# Example Only: gh issue comment --body gh issue comment --body-file ``` diff --git a/.agents/skills/triage/diagnose.md b/.agents/skills/triage/diagnose.md index 73c6de2bb75e..0e6cfaef393d 100644 --- a/.agents/skills/triage/diagnose.md +++ b/.agents/skills/triage/diagnose.md @@ -2,14 +2,16 @@ 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. +- **`issueDetails`** - The GitHub API issue details payload. This must be provided explicitly by the user or available from prior conversation context / tool calls. If this data isn't available, you may run `gh issue view ${issue_number}` to load the missing issue details directly from GitHub. - **`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/` (inside the repo root, gitignored). 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 +23,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`. diff --git a/.agents/skills/triage/fix.md b/.agents/skills/triage/fix.md index 5f4f16fdd0f9..2ecee1bcc282 100644 --- a/.agents/skills/triage/fix.md +++ b/.agents/skills/triage/fix.md @@ -2,24 +2,28 @@ 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. +- **`issueDetails`** - The GitHub API issue details payload. This must be provided explicitly by the user or available from prior conversation context / tool calls. If this data isn't available, you may run `gh issue view ${issue_number}` to load the missing issue details directly from GitHub. - **`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/` (inside the repo root, gitignored). 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 +37,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 +80,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 +90,15 @@ pnpm -C packages/astro build # or packages/integrations/ 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 +108,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 +123,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: diff --git a/.agents/skills/triage/reproduce.md b/.agents/skills/triage/reproduce.md index 22773fc5aa90..1ea0868b4ad7 100644 --- a/.agents/skills/triage/reproduce.md +++ b/.agents/skills/triage/reproduce.md @@ -2,14 +2,14 @@ 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 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. -- **`issueDetails`** - The issue details, often a string of JSON containing the GitHub issue title, body, and comments. If not passed as an arg, infer the issue from previous conversation and run `gh issue view ${issue_number} --json title,body,comments` to load the issue details directly from GitHub. +- **`issueDetails`** - The GitHub API issue details payload. This must be provided explicitly by the user or available from prior conversation context / tool calls. If this data isn't available, you may run `gh issue view ${issue_number}` to load the missing issue details directly from GitHub. ## Overview @@ -21,11 +21,9 @@ 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 `issueDetails` as defined/instructed above. **Otherwise**, fail — we cannot triage a bug that we have no details on. -**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 +34,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 +44,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. @@ -63,37 +67,74 @@ Skip if the bug is specific to Bun or Deno. Our sandbox only supports Node.js. ### Maintainer Override (`maintainer-override`) -Skip if a repository maintainer has commented that this issue should not be reproduced here. Check collaborator status with: `gh api "repos///collaborators/" --silent && echo "user is collaborator"` +Skip if a repository maintainer has commented that this issue should not be reproduced here. To determine if a commenter is a maintainer, check the `author_association` field on their comment in `issueDetails` — values of `MEMBER`, `COLLABORATOR`, or `OWNER` indicate a maintainer. ## 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-`. +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-`. + +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 top-level root 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 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 +git clone https://github.com//.git +rm -rf /.git +``` + +If a specific branch or subdirectory is referenced, check out that branch before removing `.git`, or copy only the relevant subdirectory. + +### Gist URL (`https://gist.github.com/`) + +Fetch the gist contents using the GitHub API to help understand the reproduction: -**If a StackBlitz URL is provided in the issue:** -The triage workspace has already been downloaded. Inspect what's there and proceed to configuration. +```bash +curl -s "https://api.github.com/gists/" +``` -**If no StackBlitz URL (fallback to example template):** -The workspace has been set up from `examples/minimal`. You may need to add dependencies. +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 ` 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. If the user didn't mention a specific template, use `minimal` as the default. -- 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.) +```bash +# 1. List available example templates +ls examples/ +# 2. Remove the selected template's node_modules directory to avoid problems with `cp -r` +rm -rf examples/