fix.md
2,373 tokens · o200k_base · 10,412 bytes
Source excerpt starting at line 1.# Fix Develop and verify a fix for a diagnosed Astro bug. **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.** **SCOPE: Do not spawn tasks/sub-agents.** ## 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. 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 reproduction6. Write a unit test7. Ensure no regressions8. Generate git diff9. Create a changeset (required for any fix that modifies a package)10. Append fix details to `report.md`11. Clean up the working directory ## Step 1: Review the Diagnosis Read `report.md` from the `triageDir` directory to understand: - The root cause and affected files- The suggested approach- Any edge cases to consider **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 unit test that demonstrates the expected behavior described in the issue. Place it in `test/units/` inside the affected package (see Step 6 for conventions and placement rules). A failing test is valuable even without a fix — it documents the bug and prevents it from being forgotten.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. ## 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: **Keep it minimal:** - 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:** - Will this break other use cases?- What happens with unusual input?- Are there null/undefined checks needed? Example fix: ```typescript// Before (in packages/astro/src/core/render/component.ts)export function renderComponent(component: AstroComponent, props: Props) { const html = renderToString(component, props); return html;} // Afterexport function renderComponent(component: AstroComponent, props: Props) { // Skip SSR for client:only components if (props['client:only']) { return `<astro-island client="only" component-url="${component.url}"></astro-island>`; } const html = renderToString(component, props); return html;}``` ## Step 4: Rebuild the Package After making changes, rebuild the affected package: ```bashpnpm -C packages/astro build # or packages/integrations/<name>``` Watch for build errors — fix any TypeScript issues before proceeding. ## Step 5: Verify the Fix Re-run the reproduction, often using `pnpm run build`/`astro build` or `pnpm run dev`/`astro dev`. ## Step 6: Write a Unit Test Write a unit test that covers the bug you just fixed. The test should fail without the fix and pass with it. This prevents regressions and documents the expected behavior for maintainers. Read [`reference/unit-testing.md`](../../reference/unit-testing.md) for conventions, file placement, shared test utilities, and mocks. Name your `it` block after the specific behavior being verified (e.g. `it('preserves query params in redirects')`). Run the test in isolation to confirm it passes: ```bashpnpm -C <package-dir> exec astro-scripts test "test/units/<path-to-your-test>.test.ts"``` If the test fails, fix either the test or the implementation until it passes. If you cannot write a meaningful unit test (e.g. the bug is in template compilation, requires a full dev server, or the affected code has no importable API), document why in `report.md` and move on — do not force a test that doesn't make sense. ## Step 7: 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. Run `pnpm run lint` and `pnpm run typecheck` to make sure the code follows the projects standards and there aren't errors. Address the errors until everything passes. ## Step 8: Generate Git Diff From the repository root, generate the diff: ```bashgit diff packages/``` This captures all your changes for the report. ## Step 9: Create a Changeset A changeset is **required** for every successful fix that modifies a package under `packages/`. This is not optional and does not scale with the size of the fix: one-line fixes, type-only fixes, and comment-only behavior changes all need a changeset. The only fixes that skip this step are ones that failed, were skipped, or touch nothing under `packages/` (e.g. `examples/*`-only changes). Create the changeset now: 1. Run `pnpm changeset --empty` from the repo root. This writes a randomly-named `.md` file to `.changeset/`.2. Edit that file to add the package bump and a user-facing message. The bump type for a bug fix is almost always `patch`: ```md --- '<package-name>': patch --- <one-line, user-facing description of the fix> ``` Load the `changeset` skill for the message conventions (present-tense verb, name the affected API, write for Astro users not reviewers) and the exact package name to use. ## Step 10: Write Output Append your fix details to the existing `report.md` (written by reproduce and diagnose skills). Include a new section with: what you changed, why, the full git diff, verification results, and any tradeoffs or alternative approaches considered. The report must include all information needed for a final GitHub comment to be generated later by the comment skill. Make sure to include: - What was changed and why- The full git diff (unless it is massive, if it is)- Whether the fix was successful or not- Verification results (did the fix resolve the original error?)- Unit test details: what test was added, where it lives, and what it verifies. If no test was added, explain why.- Changeset details: the name of the changeset file created in `.changeset/` and which packages it covers. A successful fix that modified a package must have a changeset — there is no "skipped because trivial" outcome. The only valid reason to have no changeset is that the fix failed/was skipped or touched nothing under `packages/`; state which.- Any alternative approaches considered and their tradeoffs- If the fix failed: what was tried and why it didn't work ## Step 11: Clean Up the Working Directory 1. Run `git status` and review all changed files2. Revert any changes that are NOT part of the fix: - Debug code, `console.log`s, or temporary test files - Changes outside `packages/` that were only needed for diagnosis/reproduction - Build artifacts that shouldn't be committed3. Use `git checkout -- <file>` to discard unwanted changes4. Confirm with a final `git status` that only the intended fix files remain, and that they include a new `.changeset/*.md` file. If the fix modified a package but no changeset is present, go back and create it before finishing.5. DO NOT commit or push anything yet! The user will handle that at a later step. The `triage/` directory is already gitignored, so it won't appear in `git status`.