shape-review-comments

Files (3)

• SKILL.md
• triage-rules.md · references/
• voice-guide.md · references/

SKILL.md (first lines)

Takes raw review findings and produces postable comments: triage what to skip, frame what survives in Mihai's voice at the right file:line, verify line numbers, then present for approval.

Reference files (load both before writing a single comment):
- [references/triage-rules.md](references/triage-rules.md) — what to drop, what to keep, severity labels
- [references/voice-guide.md](references/voice-guide.md) — sentence structure, hedges, closers, worked examples

If either reference file cannot be read, stop and report it — do not attempt to triage or write comments from memory.

If the findings list is empty, tell the user and stop.

## Step 1 — Load the references

Read both reference files completely before proceeding.

## Step 2 — Triage

For every finding, assign one of:
- **Post** — survives, worth saying
- **Drop** — not worth saying; note the reason briefly so it isn't reconsidered
- **Merge** — combine with a closely related finding on the same line or function

Apply triage rules before writing any comment text. Do not let wording decisions influence whether a finding survives.

Produce a visible triage log (one line per finding: decision + brief reason) before moving to Step 3. This lets the user catch wrong drops before comments are written.

## Step 3 — Write the comments

For each surviving finding, write the comment following the voice guide (anchor line selection, hedges, closers, severity labeling are covered there).

Two hard rules apply to every comment before you move on:

1. **No em-dashes.** Do not write them. A comma or a new sentence always works.
2. **Maximum 2 sentences.** If a third sentence feels necessary, cut it. If that loses the finding, rewrite from the observation, not the explanation.

Output format:

```
`path/to/file.ts:LINE` — severity: comment text
```

## Step 4 — Verify line numbers

Before presenting to the user, confirm each line number at current HEAD. Run `grep -n` for the anchoring expression in the file. If the file has changed since the review and a finding was already fixed, drop that comment and note it.

While here, verify any cross-file references inside comment bodies too, and convert them to GitHub links at the PR's head commit (see the voice guide's Precedent links section for the URL format).

If a line number cannot be confirmed (file deleted, path changed), drop the comment and tell the user.

## Step 5 — Present for approval

Present the shaped comments to the user. Walk through them one at a time if there are many, or offer to batch them if they are straightforward.

If the user rejects all comments, ask whether to re-triage from scratch with different criteria or to close. Do not loop silently.

From MihaiOnSoftware/.ai, MIT.

More from MihaiOnSoftware/.ai