triage

Source excerpt starting at line 1.

1# Diagnose2 3Find the root cause of a reproduced bug in the Astro source code.4 5**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.**6 7**SCOPE: Your job is diagnosis only. Finish your work once you've completed this workflow. Do NOT go further than this (no larger verification of the issue, no fixing of the issue, etc.). Do not spawn tasks/sub-agents.**8 9## Prerequisites10 11These variables are referenced throughout this skill. They may be passed as args by an orchestrator, or inferred from the conversation when run standalone.12 13- **`triageDir`** — Directory containing the reproduction project (e.g. `triage/issue-123`). If not passed as an arg, infer from previous conversation.14- **`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.15- **`report.md`** — File in `triageDir` that MAY exist. Contains the full context from all previous skills.16- **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.17 18## Overview19 201. Review the reproduction and error details from `report.md`212. Locate the relevant source files in `packages/`223. Add instrumentation to understand the code path234. Identify the root cause245. Append diagnosis findings to `report.md`25 26## Step 1: Review the Reproduction27 28Start by reading `report.md` from the `triageDir` directory.29 30**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`.31 32Re-run the reproduction if needed to see the error firsthand:33 34```bash35pnpm -C <triageDir> run build  # or dev/preview36```37 38## Step 2: Locate Relevant Source Files39 40Using the error messages, stack traces, and any other reproduction details from Step 1, identify the source files in `packages/` that are likely involved.41 42## Step 3: Investigate with Instrumentation43 44Add `console.log` statements to understand the code path:45 46```typescript47// In packages/astro/src/core/build/index.ts48console.log('[DEBUG] Building page:', pagePath);49console.log('[DEBUG] Props:', JSON.stringify(props, null, 2));50```51 52After adding logs:53 541. Rebuild the package (Example: `pnpm -C packages/astro build`)552. Re-run the reproduction (Example: `pnpm -C <triageDir> build|dev|preview`)563. Observe the debug output.57 58**Server management:** If re-running requires a dev server, always stop the existing project server first (`pnpm -C <triageDir> dev stop`). If the server fails to start twice, bail out — write your diagnosis with the data you have rather than looping on server restarts. Prefer `astro build` over dev/preview when possible. Never background servers with `&` — use `pnpm -C <triageDir> dev --background` for dev servers.59 60Iterate until you understand:61 62- What code path is executing63- What data is being passed64- Where the logic diverges from expected behavior65 66Once 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.67 68## Step 4: Identify Root Cause69 70Once you understand the issue, document:71 721. **Which file(s)** contain the bug732. **What the code does wrong** — the specific logic error743. **Why this causes the observed behavior** — how the error manifests754. **What the fix should be** — high-level approach76 77Consider:78 79- Is this a regression from a recent change?80- Does this affect other similar use cases?81- Are there edge cases to consider?82- 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.83 84**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.85 86## Step 5: Write Output87 88Append your diagnosis findings to the existing `report.md` (written by the reproduce skill).89 90Include a new section with everything you learned: the root cause, affected files with line numbers, detailed explanation of the code path, instrumentation results, and your suggested fix approach. This helps the fix skill work faster.91 92The report must include all information needed for a final GitHub comment to be generated later by the comment skill. Make sure to include:93 94- Root cause explanation (which files, what logic is wrong, why)95- Affected file paths with line numbers96- Suggested fix approach97- Confidence level (`high`, `medium`, or `low`) and any caveats98