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 reproduction
6. Write a unit test
7. Ensure no regressions
8. Generate git diff
9. 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:

// Before (in packages/astro/src/core/render/component.ts)
export function renderComponent(component: AstroComponent, props: Props) {
  const html = renderToString(component, props);
  return html;
}

// After
export 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:

pnpm -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 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:

pnpm -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:

git 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:

   ---
   '<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 files
2. Revert any changes that are NOT part of the fix:
   • Debug code, console.logs, or temporary test files
   • Changes outside packages/ that were only needed for diagnosis/reproduction
   • Build artifacts that shouldn't be committed
3. Use git checkout -- <file> to discard unwanted changes
4. 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.