| name | reviewing-gromit-runs |
| description | Use when reviewing a gromit-next run output to decide whether to accept, reject and start fresh, or resume with targeted implementation guidance. Triggered by "review the run", "should I accept this", "what did the run produce", or any gromit-next run evaluation task. |
Reviewing Gromit-Next Runs
Walk the user through a structured review of a gromit-next run and execute the chosen outcome via gromit-next review guided.
Step 1: Locate the Run
If the user provides a run ID (format: run-<8hex>): use it directly.
If the user says "the last run" or doesn't specify:
gromit-next exec list
Pick the most recent. If multiple ready_for_review runs appear, confirm with user which one.
To preview what the run produced before entering guided review:
gromit-next review show [run-id]
gromit-next review show [run-id] --details
Step 2: Read the Run and Form a Recommendation
Before entering the interactive review, read the artifacts so you can guide the user intelligently:
.gromit-next/runs/<run-id>/evidence/review.json # ReviewPacket: findings, outcome
.gromit-next/runs/<run-id>/evidence/acceptance.json # AcceptanceResults: per-criterion pass/fail
Form a recommendation:
| Situation | Recommendation |
|---|
| All acceptance criteria pass, no critical/high review findings | Accept |
| Specific criteria failed with a clear bounded gap | Resume (rework_implementation_gap) |
| Fundamental misalignment, wrong approach, or multiple unrelated failures | Fresh run (rework_vision_change) |
STOP HERE and present your recommendation to the user. Include:
- Your recommended outcome and why (cite acceptance counts, trust level, key findings)
- Any notable warnings or caveats from the review findings
- A summary of what the run produced
Then ask: "How would you like to proceed — accept, rework (implementation gap), or fresh run?"
Wait for the user's explicit answer before continuing to Step 3. Do not enter guided review autonomously.
Step 3: Run the Guided Review
gromit-next review guided [run-id]
This interactive command:
- Displays the product review
- Steps through each manual checklist item — enter
pass, fail, unsure, or skipped plus optional notes
- Prompts for outcome:
accepted, rework_implementation_gap, or rework_vision_change
- Asks for a summary — this is where the gap description goes for rework outcomes
- Writes
evidence/review-outcome.json and triggers automatic distillation
Enter the outcome the user chose in Step 2. For the outcome prompt, type exactly what the user said (e.g., accepted). For checklist items with no instructions, enter pass. For the summary, write a factual description of the result.
Step 4: Writing the Gap Description (for rework outcomes)
The summary field in review guided is how you communicate the implementation gap to the next run. Vague summaries produce another failed cycle.
For rework_implementation_gap — the summary must include:
- Which acceptance criteria failed (quote the criterion text)
- What was implemented — cite specific files and functions
- What is missing or wrong — observable behavior vs expected behavior
- Where to make changes — specific files, functions, or packages
- Verification signal — what test or output proves it's fixed
Bad summary (DO NOT use):
"The validation isn't working correctly. Please fix it."
Good summary:
"Acceptance criterion 'Stale fix detection terminates the retry loop early' failed.
internal/runner/validation/validation.go:runValidationLoop fires the stale-fix check at line 142 but never calls setTerminated() — it logs the detection and continues.
Fix: after isStale = true, set run.Terminated = true and break from the loop.
Verify: go test -run TestIntegration_StaleFixDetectionEarlyTermination ./internal/runner/validation/..."
For rework_vision_change — the summary should explain the directional misalignment: what the run produced, what was actually needed, and whether the spec needs to be updated before relaunching.
Step 5: Execute the Follow-Through
After accepted
gromit-next exec complete <run-id>
git add -p
git commit -m "..."
After rework_implementation_gap
gromit-next exec --resume <run-id>
The next cycle inherits prior review findings automatically. The summary you wrote in review guided is the gap instruction for the resumed session.
After rework_vision_change
Consider updating the spec or acceptance criteria first, then:
gromit-next exec --spec <spec-path> --project <project>
Quick Reference
| Action | Command |
|---|
| Find last run | gromit-next exec list |
| Preview run | gromit-next review show [run-id] |
| Run guided review | gromit-next review guided [run-id] |
| Accept (post-review) | gromit-next exec complete <run-id> |
| Resume (post-review) | gromit-next exec --resume <run-id> |
| Fresh run | gromit-next exec --spec <path> --project <name> |
