Skip to content

Reviewer

Command: /reversa-reviewer Phase: 5 - Review

⚖️ The spec reviewer

The Reviewer takes the Writer's contracts and tries to punch holes in them: "This is a contradiction. This point has no proof. This rule disappears if the user does X." Not to destroy, but to ensure what's left standing is solid.

What it does

The Reviewer takes the contracts generated by the Writer and tries to punch holes in them. Not to destroy, but to ensure what's left standing is solid.

It looks for: internal contradictions within the same spec, conflicts between different specs, statements marked as 🟢 that are actually inferences, obvious behaviors nobody documented. When it finds them, it points them out, corrects, and reclassifies.

Bonus: cross-review via Codex

If the Codex plugin is active in the session, the Reviewer offers a special option: ask Codex to do an independent review before its own analysis.

The advantage is getting a second opinion from a different LLM than the one that generated the specs. Different models make different mistakes, and cross-review catches things a single review might miss.

If Codex is not available, the Reviewer proceeds normally without mentioning it.

The review process

Per-unit review

For each unit folder under <output_folder>/:

  • Are the 3 canonical files present (requirements.md, design.md, tasks.md)? If not, that's a gap.
  • Do the rules in requirements.md make sense together? Are there internal contradictions?
  • Does design.md cover what requirements.md promises? Does tasks.md cover both?
  • Are there obvious unspecified behaviors?
  • Statements marked as 🟢: the Reviewer goes back to the original code to check. Reclassifies if necessary.

Cross-unit review

  • Units that conflict with each other
  • Declared dependencies that don't match the real ones in the code
  • Units that should exist but weren't generated (compare with Scout's surface.json)

Matrix validation

  • code-spec-matrix.md: is it complete? Are there files without a corresponding spec?
  • spec-impact-matrix.md: does it reflect the real dependencies?

Questions for you

For each 🔴 gap that only a human who knows the business can resolve, the Reviewer creates a formatted question. Depending on the answer_mode configured:

chat (default): questions appear directly in the chat, one by one. You answer in the conversation and it updates the specs in real time.

file: the Reviewer creates _reversa_sdd/questions.md with all questions. You fill it in at your own pace and notify when done.

What it produces

File Content
_reversa_sdd/questions.md Human validation questions
_reversa_sdd/confidence-report.md Count of 🟢/🟡/🔴 per spec and overall percentage
_reversa_sdd/gaps.md Gaps that remained unanswered
_reversa_sdd/cross-review-result.md Codex findings (if cross-review was requested)

Specs in each unit folder under <output_folder>/ are updated in-place with the reclassifications. The Reviewer's own outputs (questions.md, confidence-report.md, gaps.md, cross-review-result.md) stay at the root, outside the unit folders.