peer-review-brief

Precondition (REFUSE if not met)

1. Identify the investigation id. If unclear, list findings/* and use AskUserQuestion to ask.
2. Read findings/<id>/brief.md.
3. If brief.md does not exist OR its status is approved (already passed user review) OR something other than draft / reviewed: stop and exit. Tell the user the brief isn't in a reviewable state.

What you do

You audit the brief, close gaps, and produce a tighter brief. You are not the user's review — the user will review what you hand back. Your job is to catch what the brief writer missed so the user's review can be about judgment, not gap-spotting.

Gap categories to check

Walk the brief section by section. For each, mark clean or gap.

Driver

• gap if: generic ("clean up tech debt"), no concrete trigger, no tie to a system change
• clean if: names a specific incident / deadline / decision

Decision this feeds

• gap if: vague ("we'll know what to do"), no concrete action
• clean if: names what the user will do differently when the investigation returns

In scope / Out of scope

• gap if: scope items are categories ("the API layer") rather than paths; out-of-scope is empty
• clean if: concrete paths or service names; at least one explicit non-goal

Methodology

• gap if: "review the code" with no depth or evidence type
• clean if: names depth, evidence type, expected effort shape

Severity rubric

• gap if: Critical and High definitions could swap without anyone noticing; levels don't tie to the driver
• clean if: each level has a specific, driver-linked definition

Deliverables

• gap if: no audience or decision named per file
• clean if: each deliverable names file + audience + decision it feeds

Definition of done

• gap if: "complete and accurate" or anything that can't be checked
• clean if: falsifiable observable property

How to close each gap

For every gap, try in this order:

1. Re-read findings/<id>/grilling.md. Maybe the answer is there and the brief writer didn't carry it across.
2. Read the codebase. If the gap is "what counts as the API layer", grep first — don't ask the user what they can see from their own filesystem.
3. Grill the user. Only when 1 and 2 can't close the gap. Use AskUserQuestion with 3–4 multi-choice options and a recommended one. Same shape as grill-the-investigation.

When a gap is closed, edit brief.md in place. Do not append a "review notes" appendix — the brief is a one-page artifact, not a changelog.

When you grill the user, append the Q&A to grilling.md under a ## Follow-up answers (from peer-review-brief) section. This keeps the grilling record complete.

Iteration

Loop, max 3 iterations:

1. Identify gaps.
2. Close what you can autonomously.
3. Aggregate the user-bound gaps into an AskUserQuestion round.
4. Apply the answers.
5. Re-check.

If gaps remain after 3 iterations, surface them to the user via AskUserQuestion:

"I couldn't close these N gaps without more info. Do you want to answer them now, or accept the brief with the gaps noted?"

• Answer them now
• Accept the brief with gaps flagged (the brief will get an explicit "Open questions" section)

Do not loop indefinitely.

When you're done

Set brief.md frontmatter to status: reviewed. Hand back to the orchestrator. The orchestrator presents the brief to the user, who picks Approve / Edit / Redo.

Failure modes

• Inventing content. If the source doesn't have the answer, ask. Never make it up.
• Becoming a second grilling phase. Most gaps should close from re-reading the grilling and the codebase. Grilling the user is a fallback, not the default.
• Treating cosmetic issues as gaps. Punctuation, prose flow — not your job. Let the user fix those during their own review.
• Looping forever. Cap at 3.
• Skipping the user grill when a gap genuinely needs them. "The user will see it when reviewing" is wrong. Closing the gap before review is the entire point of this skill.