Skip to content

moonlight-lupin/agent-skills / plugins/dev-pipeline/skills/review-commit

review-commit

Verified

Use when the user says 'review loop N times', 'build then review', 'fix and re-review', 'review loop until clean', 'have cursor build, codex review', or wants the dev-pipeline review stage: a two-axis single pass (Standards + Spec, parallel, never merged) FIRST, then a budgeted confirm-round loop on the fix diffs until no BLOCKING/MAJOR is open, then the commit/deploy gate — three-reviewer gate before live deploy, release hygiene before tagging. Also triggers: 'two-axis review', 'confirm rounds', 'review diff until SHIP', 'N confirm rounds', ship gate.

FileKindSize
SKILL.mdexecutableskill md6.8 KB
references/background-build-polling.mdexecutablescript3.9 KB
references/confirm-round-protocol.mdexecutablescript12.3 KB
references/dispatch-result-contract.mdexecutablescript3.5 KB
references/feature-build-brief.mdexecutablescript2.9 KB
references/fix-brief-template.mdexecutablescript10.5 KB
references/persistent-loop-plan.mdexecutablescript6.9 KB
references/release-hygiene.mdexecutablescript3.9 KB
references/reviewer-dispatch.mdexecutablescript6.0 KB
references/spec-convergence.mdexecutablescript5.2 KB
references/two-axis-single-pass.mdexecutablescript9.9 KB
references/workflow-steps.mdexecutablescript18.9 KB
scripts/attest_file.pyexecutablescript2.7 KB
scripts/capture_dispatch_result.pyexecutablescript3.6 KB
scripts/loop_plan_check.pyexecutablescript3.8 KB

references/fix-brief-template.md

View on GitHub
# Fix-Brief Template for Review-Driven Fixes

When a review (Codex, Opus, or human) produces findings, the orchestrator
writes a fix brief that maps each finding to a concrete code change. The
builder (Cursor) reads the brief and implements all fixes in one pass.

Save briefs to `.hermes/reviews/fix-brief-N.md` (one path convention, used by
workflow-steps.md Step 8 and the builder prompts; the brief carries the
reproduced, deduplicated findings and named failing tests — the builder never
reads the raw review log).

## Contents

- Structure
- What Makes a Good Fix Brief
- Example (from a fix-round session, Aug 2026)
- Amend After Reviewer P3 Findings
- Superseding a fix brief mid-build
- Check the brief for self-contradiction before dispatching
- Orchestrator probe evidence in the brief
- Builder report items to adjudicate in the same round
- Probe every fix yourself before committing a round — including the negative space
- Version-bump rounds: bump all six pins in ONE commit, verify with the lockstep tests, never sed the changelog header blindly

## Structure

```markdown
# Fix Brief: <short title>

## Context

<1-2 sentences: what was reviewed, what was found, what is already done.>

The repo is at `<path>`, branch `<branch>`.

## Finding <ID>: <title>

**Files:** `<file paths>`

<1-2 sentence description of the problem.>

**Fix:**
1. <numbered steps — exact, actionable, no ambiguity>
2. <include line numbers or function names as anchors>
3. <if a test is needed, specify the test name and assertions>

<Repeat for each finding.>

## Constraints

<BUILDER BLOCK — paste verbatim from orchestrator/references/coding-principles.md § Builder block>

- Every changed line must trace to one finding ID above. Anything else you
  notice goes in the report, not the diff.
- Do NOT modify <X> — it is already done / out of scope.
- Do NOT touch <Y> — separate concern.
- Run `<exact test command>` after all changes.

## Verification

After all fixes:
```
<exact test command>
```
All tests must pass. <Note expected skip count.>

## Report

Per finding: FIXED / DEFERRED + files + test names. Plus: assumptions made,
and any unrelated dead code noticed (not deleted).
```

## What Makes a Good Fix Brief

- **One finding per section** — the builder implements each fix independently.
- **Exact file paths and function names** — the builder does not search.
- **Numbered steps** — not prose. Each step is one action.
- **Constraints section** — what NOT to touch. This prevents the builder from
  re-implementing already-done fixes or touching unrelated code.
- **Exact verification command** — the builder runs this and reports results.
- **Do NOT include the review itself** — the brief distills the review into
  actionable steps. The builder does not need the review's reasoning.

## Example (from a fix-round session, Aug 2026)

The review produced 5 findings (F1-F5). F1 was already fixed by the
orchestrator (CSP header change). The brief covered F2-F5 only:

- F2: Delete dead `_pdf_reportlab()` function
- F3: Add `skipif` markers to 5 PDF tests
- F4: Split `ImportError` into `RenderError` + `ImportError`
- F5: Remove a stale unused constant, fix 2 vacuous tests

Each finding had exact file paths, numbered steps, and constraints
("Do NOT touch F1 — it is already done").

After the builder finished, Codex review found one P3 finding (stale
`pyproject.toml` comment). The orchestrator fixed it directly (a one-line
documentation fix) and amended the commit.

## Amend After Reviewer P3 Findings

When the reviewer finds only minor (P3/Nit) findings — stale comments,
documentation typos, naming — they don't keep the loop open
(`confirm-round-protocol.md` § Severity). Batch the cheap ones into the last
fix commit or defer them; the orchestrator may fix trivial ones directly
(≤ ~10 lines, mechanical, no design choice) and says so. If a finding touches
code logic, dispatch it through the builder lane.

## Superseding a fix brief mid-build

This is a RECOVERY path, not the default. The governing rule
(`confirm-round-protocol.md`, *Who reviews each confirm round*) is to HOLD the
fix round until every dispatched reviewer's verdict lands. Supersede applies
only when a fix dispatch already started against an incomplete verdict set —
e.g. the user explicitly ordered fix-now while a reviewer was still out. When
a second review round lands while the fix builder is already running (dual
reviews return at different times), do not wait for a re-dispatch — rewrite
the brief file in place so its content IS the merged round (round-2 wins where
it overlaps; map round-1 IDs to round-2 IDs so nothing double-fixes). The
builder re-reads the brief by path between findings. Then verify uptake from the builder's log
(see `persistent-loop-plan.md` steering rule #6): items it never re-read must
be re-probed after exit and dispatched as an enumerated follow-up if unfixed.
Also include in the merged brief: "note the F→O mapping in your report" so the
verification report is auditable against both reviews.

Timing caveat: a supersede only takes effect if the builder has not yet passed
its brief-read checkpoint. If the round-2 review arrives while the builder is
already deep in the old brief, expect the old scope to complete; grep the log
for the new item IDs — if absent, the round delivered round-1 only. The
follow-up dispatch then carries ONLY the still-failing items, each with fresh
orchestrator probe output as evidence. When the builder has just started,
killing it and re-dispatching with the merged brief is cheaper than supersede
plus follow-up.

## Check the brief for self-contradiction before dispatching

When one item gives two adjacent instructions, verify they agree against the
code they reference BEFORE dispatching — e.g. "exclude drafts" AND "mirror
pl_report.py's bucket logic" contradict when pl_report does NOT exclude
drafts. The builder implements instructions literally and will not flag a
contradiction; you get one of the two behaviors at random, and the next
reviewer flags the divergence against the source of truth as a fresh finding.
Self-contradiction in a brief is an orchestrator error that costs a round.
Also carry domain invariants as explicit brief rules, not assumptions:
financial aggregators must preserve currency buckets (sum per currency, never
across them — a unitless USD+JPY total is a wrong number that a trends chart
will render forever). Also check the brief's items for cross-surface drift:
when an item changes a metric's shape (string→bucket dict, scalar→dict),
enumerate EVERY consumer of the old shape in the brief — display formatters,
flattener metric lists, and the r3-era test file expectations (the r3 file is
the builder's own and editable; attested files are not). A missed consumer is
how a fixed producer leaves a stale display format or an orphan metric key
behind, reappearing as a fresh finding next round.

## Orchestrator probe evidence in the brief

Each finding carries the orchestrator's probe verdict (confirmed / variant /
not-reproduced) with the observed output inline — the builder should not
re-derive a reproduction that already exists. A 'not reproduced' verdict must
say why the orchestrator's own probe was ambiguous (aliasing, missing
reference bytes) and instruct the builder to re-probe first. Findings the
orchestrator could neither confirm nor dismiss go to the builder marked
'RE-VERIFY FIRST, then fix or report back' — never silently dismissed.

## Builder report items to adjudicate in the same round

Read the builder's final report for three item classes and rule on each before
the next dispatch: (1) **accommodations** — 'left lenient where the strict form
would break an attested fixture' → accept as fixture-mandated and bind it in
the next review prompt, or schedule a re-attestation; (2) **disagreements** —
'the brief's clause was wrong because X' → verify the reason, accept as settled
design or re-dispatch with corrected reasoning; an accepted disagreement that
stays unbound re-enters the next review as a fresh finding; (3) **line-count
or size gates tripped** — a builder hitting a file-size cap may extract a
helper into a NEW module; treat the extraction as a
reviewable structural change, not a mechanical move: it creates a new import
surface the next brief's consumer inventory must include.

Fourth item class: **contract-test contradictions** — 'test X assumes Y, the
spec says Z, I stopped instead of touching the test'. That stop is the
contract working; treat it as success (see `review-lessons/references/review-findings-adjudication.md` — own the fixture fix). Adjudicate by
checking the SPEC first: when the builder is right, the fix is an
orchestrator-side test edit (test-only code, no builder dispatch) that makes
the test deterministic against the spec — then re-run the suite before
committing, and re-attest the test in the same commit if it was attested.
Record the adjudication in the delivery so the reviewer sees the contract
test changed and why.

## Probe every fix yourself before committing a round — including the negative space

The orchestrator's verification after each fix round is probe-first: import
the fixed function, run the minimal temp-dir probe with the REAL producer
shape, and compare observed vs wanted output. Probe the ADJACENT behavior in
the same pass — the guard's sibling call sites, the same rule's boundary
values, the standing properties (byte-identical render vs pre-feature
baseline, real settlement still works after adding false-settlement guards,
live-install divergence probe still reports the known divergence). A fix
brief's item list can be fully green while a standing property broke
undetected; the standing probes are what catch that. Record each probe's
want/observed pair in the round report — it is the evidence the delivery and
the next review prompt reuse.

## Version-bump rounds: bump all six pins in ONE commit, verify with the lockstep tests, never sed the changelog header blindly

For a release round:
bump plugin.yaml, pyproject.toml, the entrypoint VERSION constant,
.claude-plugin/plugin.json, .claude-plugin/marketplace.json, and the README
status line with one targeted sed each (verify each file with grep after),
then run the lockstep tests (`test_plugin_structure.py`) BEFORE the full
suite — 87 tests, seconds — so version drift fails locally instead of in CI.
Finalize the CHANGELOG entry in the same commit (a builder-era entry headed
"Pre-release round of..." must be rewritten to the release framing before the
push), commit "release: vX.Y.Z", push, then watch CI with
`gh run watch <id> --exit-status` in a background session before tagging.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall