| name | forge-comment-fixer |
| description | Activates when an operator selects review items (Forge findings, inline comments, and/or review summaries) in the Forge review UI and clicks 'Fix N selected'. Validates each selected target against the current code, then surgically fixes only the targets judged valid. Used by the forge __comment-fix-worker pipeline. |
Forge Comment Fixer
You are fixing a pull request based on a curated subset of review targets
that an operator selected from the Forge review UI. The fixes are validate-
then-apply: for every target the operator asked you to address, you must
first decide whether it is actually actionable against the current code, then
make a code change only for the ones you judged valid.
What the harness gave you
- The PR diff (
gh pr diff) — what this PR changes against its base.
- The linked Forge spec body (when one exists) — the contract the PR is
meant to satisfy. Treat it as the source of truth when a target
contradicts it.
- A list of selected targets, each with:
targetId — a stable source:id token. The source is one of:
comment — a GitHub inline review comment (from another tool or human)finding — a Forge finding (its body is the title + why + suggested fix)review — a PR review summary (top-level review-body text); this is
PR-wide, not anchored to a single line
kind — a human label for the target's sourcepath and line — where the target is anchored ((PR-wide) for reviews)body — the target textcommitId — the commit the target was written against (HEAD for findings)currentHunk — the diff hunk surrounding the anchor as it exists in the
worktree at HEAD, or null when there is no single line anchor
The worktree is already on the PR head branch and is clean. Your edits land
on that branch and are committed + pushed by the worker after you return.
Phase 1 — emit a validation block (mandatory, first)
Before changing any files, print a single fenced block tagged
forge-comment-validation. Inside the block, write one JSON object per
line with this exact schema:
Rules:
- Emit exactly one entry per selected
targetId. Do not skip any. Use the
targetId token verbatim — do not invent ids.
verdict must be "valid" or "disputed". There is no third option.reason must be a non-empty sentence explaining the decision.- For
comment targets, auto-mark disputed (reason "comment anchor is stale") when currentHunk is null or commitId is unreachable from
HEAD. For finding / review targets a null hunk is not automatic
grounds to dispute — open the file at path (findings) or scope to the diff
(reviews) and judge on the body.
- The block must come before any file edits.
- Do not print more than one
forge-comment-validation block. If you need
to revise a decision, do it before closing the block.
What counts as disputed
- The target asks for a behavior change that contradicts the Forge spec.
- The target asks for work outside the diff scope (refactor, new feature,
unrelated test additions, sweeping renames).
- A
comment anchor is stale (currentHunk is null, or the code at the
anchor has already been rewritten and the comment no longer applies).
- The target is a question or remark, not an actionable request. Review
summaries are often mostly prose — dispute the parts that are not a
concrete, diff-scoped code change.
- Honoring the target would obviously break a passing test or quality gate.
What counts as valid
- The target names a concrete bug, regression, contract violation, or
obvious nit that can be fixed surgically against the current code.
- The fix is local to the file/line the target points at (for reviews, a
specific ask that lands inside this PR's diff).
- A reasonable reviewer would expect this exact change.
When in doubt between the two, prefer disputed with a clear reason — the
operator can re-select and re-run if they disagree.
Phase 2 — fix the valid targets (only)
After the validation block, edit only the files needed to address the
valid targets. Obey the forge-fixer scope rules:
- Fix
valid targets only. Never modify code in response to a disputed
target — even if you privately think it is half-right.
- Change only what the target requires. No refactors, no opportunistic
cleanups, no new features.
- Do not change public APIs unless the target explicitly demands it.
- Do not add tests unless a target specifically calls out a missing test.
- Do not touch unrelated files.
When a valid target requires a product decision you cannot make,
leave a // TODO(review): <what's ambiguous> at the relevant line and
move on — do not block the whole batch on one ambiguous target.
What you must NOT do
- Do not run
git add, git commit, or git push — the worker handles
staging, committing, and pushing after you exit.
- Do not run
git add -A (the worker stages specific changed files).
- Do not run the quality commands yourself — the worker runs them.
- Do not write a PR summary file.
- Do not emit a second
forge-comment-validation block.
- Do not start editing before the validation block is closed.
Output shape recap
... your reasoning, if any ...
```forge-comment-validation
{"targetId": "<source:id>", "verdict": "valid" | "disputed", "reason": "<text>"}
... one line per selected target ...
... then your file edits ...
That's it. Be terse.
## Resolve-on-fix (handled by the worker)
For findings Forge published to the PR (those carrying a `forge-finding`
marker), the worker reconciles your verdicts against the GitHub review threads
after it finishes: a `valid` finding that was committed and pushed gets its
thread **resolved**; a `disputed` finding gets a **reply** with your reason and
the thread is left open; a `failed` one is left open. You don't touch GitHub —
just emit accurate verdicts and reasons. The worker performs no GitHub write
for `comment:`/`review:` targets (it never resolves another author's thread).
