Task: triage and plan GitHub issue #{{ISSUE}} in {{REPO}}

Issue title: {{TITLE}} Provisional severity: category {{CATEGORY}} ({{CATEGORY_NAME}}) — assigned from a title/body skim only. You investigate the real code, so you may correct it.

Your worktree

Work in {{WORKTREE}} and nowhere else. cd there first. It is a persistent git worktree, currently detached at origin/{{DEFAULT_BRANCH}}, reserved for this issue for the whole pipeline — the implementer and reviewer will inherit it, so any build cache you warm up is reused rather than thrown away.

Never modify the primary repo checkout. It must stay clean on {{DEFAULT_BRANCH}}; the loop halts if it is dirty. Do not push anything and do not open a PR — you produce a plan, not a change.

Your plan is the accuracy anchor for everything downstream: a cheaper model implements it without asking questions, so anything you leave implicit gets guessed at. Be exhaustive.

1. Investigate

• gh issue view {{ISSUE}} --comments — read the whole thread, including comments.
• Read the repo’s own guidance before touching code: CLAUDE.md, CONTRIBUTING.md, README.md, and the CI workflows under .github/workflows/. Extract from them the build/test/lint commands including any required wrapper (for example a nix develop --command or container prefix), the test conventions, and any documented constraint the fix must respect.
• Investigate the codebase and confirm or refute the issue’s claim by reproducing it in your worktree. An unreproduced claim is not a confirmed bug.

{{#DOCS_DEFERRED}}

Agent-guidance docs are deferred

Read them freely — never plan a change to them: {{DEFERRED_DOCS}}. Every issue PR is tempted to touch these, they conflict with sibling PRs and with the maintainer’s own branches, and clearing such a conflict costs a stopped reviewer and a restarted implementer. If your investigation turns up something one of them should say, append it to {{DOCNOTE_FILE}} — which file, the wording you want, and why — and carry on. A single end-of-loop PR applies every note together.

The one exception is an issue whose subject is one of those files; then the change belongs in its own PR, and you must say DOCS_EXEMPT: yes in your final message. {{/DOCS_DEFERRED}}

2. Return exactly one verdict

Write your deliverable to a file under {{BLOB_DIR}}/ and name that path in your final message. Your final message must begin with the verdict word on its own line.

VALID — the issue is real and you know how to fix it

Write the plan to {{BLOB_DIR}}/plan.md. It must contain:

• Root cause and current behavior, with exact file:line references.
• The intended change, file by file, with the approach spelled out concretely — not “handle the escaping properly” but which function, what it should do instead.
• Edge cases and constraints to respect. Anything the repo’s docs call out as deliberate, load-bearing, or part of a public contract: serialization schemas, intentional graceful-degradation behavior, ordering guarantees, MSRV, and so on. Say explicitly what must not change.
• A test plan following the repo’s existing test conventions (find them and copy them — do not invent a new harness), naming which tests to add and what each must assert. Note for each new test whether it guards against the bug or against a plausible wrong fix.
• The exact verification commands — build, test, lint, format — verbatim with any required wrapper prefix, and which of them CI treats as hard failures.

The plan must be self-contained. The implementer will not have your context and must never have to rediscover repo conventions.

INVALID / ALREADY-FIXED / WONT-FIX

Write a draft closing comment to {{BLOB_DIR}}/close-comment.md, addressed to the issue reporter. It must concretely state what you checked (with file:line), what you ran, and why the issue does not apply or will not be fixed. “Could not reproduce” with no evidence is not acceptable. Also give a one-line summary for the maintainer’s approval prompt.

NEEDS-HUMAN — real, but the path forward is a judgment call

Use this when there are competing approaches with genuine trade-offs, when the decision is about intended behavior or design that only the maintainer can make, or when you cannot bound the blast radius of a fix. Do not use it to avoid hard work.

Write to {{BLOB_DIR}}/needs-human.md a write-up that will be posted verbatim as a comment on the issue, so address it to the maintainer and format it as markdown:

• The research you did — what you read, ran, and reproduced, with file:line.
• The candidate approaches, each with its trade-offs.
• Your recommendation if you lean one way — or an explicit statement that you have none, and precisely what is unresolved.
• The specific decision you need a human to make, phrased as a question.

3. Final message format

Keep it short; the files are the deliverable.

VALID
CATEGORY: <1-5>
PLAN_FILE: {{BLOB_DIR}}/plan.md
SUMMARY: <one line>

or

WONT-FIX
CATEGORY: <1-5>
COMMENT_FILE: {{BLOB_DIR}}/close-comment.md
SUMMARY: <one line, used verbatim in the maintainer's approval prompt>

or

NEEDS-HUMAN
CATEGORY: <1-5>
WRITEUP_FILE: {{BLOB_DIR}}/needs-human.md
SUMMARY: <one line naming the decision needed>

CATEGORY is your corrected severity after reading the code (1 security, 2 crash/hang, 3 correctness, 4 CI/tooling, 5 docs/metadata). State it even if it matches the provisional value — it decides how rigorously the fix gets reviewed.

Add a DOCS_EXEMPT: yes line only if this issue is about one of the deferred agent-guidance files. Omit it otherwise.