Reviewing Changes

Use this skill when you need to verify that an implementation (after a ralph-tui loop, agentic session, or human work) correctly fulfills the requirements defined in the change's delta specs.

Behavior

1. •Study: Study the proposal.md, delta specs in specs/, and the current implementation code.
2. •Run Checks: Execute the project's verification suite (pnpm lint, pnpm test, pnpm build) and perform a thorough spec-to-code mapping. You MUST have objective data from tests or code analysis before proceeding to pre-review.
3. •Pre-review: Study docs/changes/<slug>/review.md if it exists.
   • •For each item in the Open Issues list, verify thoroughly that it has been addressed using the checks and tests run in step 2.
   • •If you cannot confirm an issue is resolved, do NOT mark it as resolved. Instead, require better checks or tests.
   • •Mark resolved issues as [x].
   • •Update text of existing issues if the nature of the failure has changed.
   • •Note regressed issues as [ ] <issue> (regressed).
4. •Append Review: Add a new ## Review N block to review.md.
   • •List new findings with IDs (R1, R2, etc.).
   • •State the Decision: pass | needs-fix | reject.
   • •When to Reject: Reject if the implementation is fundamentally flawed (e.g., incorrect architecture, massive spec drift, or poor code quality that is expensive to fix). Rejecting allows a clean retry with improved specs/proposal.
   • •When to Fix: Use needs-fix for correctable bugs, missing edge cases, or small spec gaps that don't require a full rewrite.
5. •No Code Edits: Do NOT modify application code during review.
6. •Stop for Review: After appending the review findings to review.md, present the findings and your decision to the user. Do NOT proceed to updating prd.json until the user acknowledges the findings and approves the needs-fix or reject path.
7. •Commit Change Artifacts: After the user approves the findings and any updates to prd.json, proposal.md, or specs, commit ONLY the files in docs/changes/<slug>/. This ensures the worktree is clean for the fix loop.
8. •If needs-fix:
   • •Update docs/changes/<slug>/prd.json to act as a fix queue.
   • •Reopen stories that failed: set passes: false and update acceptanceCriteria to include the missing/failed behavior.
   • •Add new stories for gaps: Title Fix: <summary>, use spec-derived criteria, and note the issue ID (e.g., Issue: R1).
   • •Ask the user to review the updated prd.json.
9. •If reject:
   • •Use the rejecting-changes skill to analyze failure, extract learnings, update artifacts, and clean up for retry.
10. •If pass:
    • •Suggest syncing specs and archiving the change.

review.md Format

# Review Log: <slug>

## Open Issues
- [ ] R1: <summary> (since Review 1)
- [x] R2: <summary> (resolved in Review 2)

## Review 1 - <date> - <mode>
**Checks**: lint, test, build, spec-scan
**Findings**:
- R1: ...
- R2: ...
**Decision**: needs-fix

## Review 2 - <date> - <mode>
**Checks**: ...
**Findings**:
- R3: ...
**Decision**: needs-fix

Note on IDs

Use sequential IDs (R1, R2, ...) across the entire review log to keep tracking simple.