[pull] main from withastro:main

.agents/skills/triage/SKILL.md

@@ -0,0 +1,46 @@
+---
+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.
+---
+
+# Triage
+
+Triage a bug report end-to-end: reproduce the bug, diagnose the root cause, and attempt a fix.
+
+## Input
+
+You need either:
+
+- `issueTitle` and `issueBody` provided in args (preferred — use these directly as the bug report), OR
+- A GitHub issue number or URL mentioned in the conversation (use `gh issue view` to fetch details)
+
+If a `triageDir` is provided in args, use that as the working directory for the triage. Otherwise, default to `triage/gh-<issue_number>` (if you have an issue number) or `triage/current`.
+
+## Step 1: Reproduce
+
+Read and follow [reproduce.md](reproduce.md). Use a subagent for this step to isolate context.
+
+After completing reproduction, check the result:
+
+- If the issue was **skipped** (host-specific, unsupported version, etc.) — skip to Output.
+- If the issue was **not reproducible** — skip to Output.
+- If the issue was **reproduced** — continue to Step 2.
+
+## Step 2: Diagnose
+
+Read and follow [diagnose.md](diagnose.md). Use a subagent for this step to isolate context.
+
+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
+
+Read and follow [fix.md](fix.md). Use a subagent for this step to isolate context.
+
+Whether the fix succeeds or fails, continue to Output.
+
+## Output
+
+After completing the triage (or exiting early), you may suggest generating a GitHub comment using [comment.md](comment.md) if the user would find it useful.

.agents/skills/triage/comment.md

@@ -0,0 +1,74 @@
+# Comment
+
+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.**
+
+## 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 (reproduction, diagnosis, fix).
+- **`branchName`** — The branch name where a fix was pushed. If not passed as an arg, infer from previous conversation.
+
+## Overview
+
+1. Read `report.md` from the triage directory
+2. Generate a GitHub comment following the template below
+
+## Step 1: Read Triage Output
+
+Read `report.md` from the `triageDir` directory. This file is the shared context log — each previous skill (reproduce, diagnose, fix) appends its findings to it.
+
+If `report.md` is missing or empty, generate a minimal comment (see "Fallback" section below).
+
+## Step 2: Generate Comment
+
+Generate and return a GitHub comment following this template. Adapt it to fit the findings:
+
+- Include only the sections that are relevant to what was discovered
+- If the issue could NOT be reproduced, omit the fix-related sections
+- If no fix was developed, omit the "How to Fix" section or replace its content with a brief note explaining why
+- Add or remove subsections as needed to clearly communicate findings
+
+Keep it concise:
+
+- Summary section: One sentence per bold field
+- Use collapsible `<details>` sections for longer content
+- Include exact versions, commands, and file paths where relevant
+
+Format requirements:
+
+- Code blocks: Use appropriate language hints (bash, typescript, diff, patch, etc.)
+- Patches: Use ```diff for maintainer patches
+
+### 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:** [If `branchName` arg is non-null, include: [Create PR](https://github.com/withastro/astro/compare/{branchName}?expand=1)] **[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.]
+
+**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.]
+
+<details>
+<summary><em>Full Triage Report</em></summary>
+
+[Include the full contents of report.md here, formatted for readability]
+
+</details>
+
+_This report was made by an LLM. Mistakes happen, check important info._
+```
+
+## Optional Follow-up Task
+
+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.
+
+```bash
+gh issue comment <issue_number> --body <comment>
+gh issue comment <issue_number> --body-file <path-to-file>
+```

.agents/skills/triage/diagnose.md

@@ -0,0 +1,90 @@
+# Diagnose
+
+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.**
+
+## 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.
+
+## Overview
+
+1. Review the reproduction and error details from `report.md`
+2. Locate the relevant source files in `packages/`
+3. Add instrumentation to understand the code path
+4. Identify the root cause
+5. Append diagnosis findings to `report.md`
+
+## 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
+
+**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`.
+
+Re-run the reproduction if needed to see the error firsthand:
+
+```bash
+pnpm -C <triageDir> run build  # or dev/preview
+```
+
+## Step 2: Locate Relevant Source Files
+
+Using the error messages, stack traces, and any other reproduction details from Step 1, identify the source files in `packages/` that are likely involved.
+
+## Step 3: Investigate with Instrumentation
+
+Add `console.log` statements to understand the code path:
+
+```typescript
+// In packages/astro/src/core/build/index.ts
+console.log('[DEBUG] Building page:', pagePath);
+console.log('[DEBUG] Props:', JSON.stringify(props, null, 2));
+```
+
+After adding logs:
+
+1. Rebuild the package (Example: `pnpm -C packages/astro build`)
+2. Re-run the reproduction (Example: `pnpm -C <triageDir> build|dev|preview`)
+3. Observe the debug output.
+
+Iterate until you understand:
+
+- What code path is executing
+- What data is being passed
+- Where the logic diverges from expected behavior
+
+## Step 4: Identify Root Cause
+
+Once you understand the issue, document:
+
+1. **Which file(s)** contain the bug
+2. **What the code does wrong** — the specific logic error
+3. **Why this causes the observed behavior** — how the error manifests
+4. **What the fix should be** — high-level approach
+
+Consider:
+
+- Is this a regression from a recent change?
+- Does this affect other similar use cases?
+- Are there edge cases to consider?
+
+## Step 5: Write Output
+
+Append your diagnosis findings to the existing `report.md` (written by the reproduce skill).
+
+Include 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.
+
+The report must include all information needed for a final GitHub comment to be generated later by the comment skill. Make sure to include:
+
+- Root cause explanation (which files, what logic is wrong, why)
+- Affected file paths with line numbers
+- Suggested fix approach
+- Confidence level (`high`, `medium`, or `low`) and any caveats

.agents/skills/triage/fix.md

@@ -0,0 +1,126 @@
+# Fix
+
+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.**
+
+## 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.
+
+## 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`
+
+## 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 not reproduced/skipped OR diagnosis confidence is `low`/`null` OR no root cause found → append "FIX SKIPPED: [reason]" to `report.md` and return `fixed: false`.
+
+**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
+
+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
+
+**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;
+}
+
+// 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 3: Rebuild the Package
+
+After making changes, rebuild the affected package:
+
+```bash
+pnpm -C packages/astro build    # or packages/integrations/<name>
+```
+
+Watch for build errors — fix any TypeScript issues before proceeding.
+
+## Step 4: 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
+
+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
+
+From the repository root, generate the diff:
+
+```bash
+git diff packages/
+```
+
+This captures all your changes for the report.
+
+## Step 7: 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?)
+- 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
+
+1. Run `git status` and review all changed files
+2. 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 committed
+3. Use `git checkout -- <file>` to discard unwanted changes
+4. Confirm with a final `git status` that only the intended fix files remain
+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`.