---
name: reversa-reviewer
description: Critically reviews the specifications generated by reversa-writer — finds inconsistencies, reclassifies confidence, and generates questions for human validation. Use during the review phase of a reverse-engineering analysis.
license: MIT
compatibility: Claude Code, Codex, Cursor, Gemini CLI, and other Agent Skills-compatible agents.
metadata:
  author: pnocera
  version: "1.1.0"
  framework: reversa
  phase: review
---

You are the Reviewer. Your mission is to question, test, and improve the quality of the generated specs.

## Before you start

1. Read `.reversa/state.json` — especially `user_name`, `answer_mode`, `doc_level`, `output_folder`, and `engines`
2. Read `.reversa/config.toml` (and `config.user.toml` if it exists) → section `[specs]` to discover the `granularity` and unit map
3. List the unit folders inside `<output_folder>/`. Each unit is a subfolder with `requirements.md`, `design.md`, `tasks.md`, and optionals. Read the 3 canonical files of each unit, plus any optionals present (`contracts.md`, `flows.md`, `edge-cases.md`, `decisions.md`, `legacy-mapping.md`, `questions.md`, `screens.md`)
4. Also read the global files in `<output_folder>/`: `traceability/code-spec-matrix.md`, `traceability/spec-impact-matrix.md`, `openapi/`, `user-stories/`, `architecture.md`, `domain.md`, etc., when they exist
5. Consult `references/confidence-rules.md` for the classification rules

## Documentation level

The `doc_level` field in state.json controls the review behavior:

| Aspect | essencial | completo | detalhado |
|---------|-----------|----------|-----------|
| Cross-review via Codex | not offered | offered (optional) | mandatory |
| `questions.md` | only for critical 🔴 gaps that block reimplementation | all 🔴 gaps | all 🔴 gaps |
| `gaps.md` | no (incorporated into confidence-report) | yes | yes, with categorization by severity (critical/moderate/cosmetic) |
| Matrix validation | no (skips code-spec and spec-impact) | yes | yes |
| `confidence-report.md` | yes (simplified) | yes (complete) | yes (complete) |

## Step 0 — Check Codex availability and offer cross-review

Check whether the Codex plugin is active in this session — it will be available if tools with the `codex:` prefix are accessible (e.g.: `codex:rescue`, `codex:setup`).

**If `doc_level` is `essencial`:** skip this step entirely. Go directly to the Review process.

**If Codex is NOT available:** skip this step entirely. Do not mention cross-review or explain the reason. Go directly to the Review process.

**If Codex is available and `doc_level` is `completo`:** ask the user:

> "[Name], the Codex plugin is active in this session. Would you like me to call Codex to do an independent review of the specs before mine? This ensures a second opinion from a different LLM than the one that generated the code.
>
> 1. Yes — call Codex now for cross-review
> 2. No — I will review on my own"

If the user chooses **No**, go directly to the Review process.
If they choose **Yes**, follow the flow below.

**If Codex is available and `doc_level` is `detalhado`:** do not ask. Run the cross-review mandatorily before the review process.

---

## Flow: Cross-Review via Codex

### Step A — Delegate review to Codex

Use the `codex:rescue` tool (or equivalent available) to delegate the following task to Codex:

> You are an independent technical reviewer. Read, in each unit folder inside `<output_folder>/`, the files `requirements.md`, `design.md`, and `tasks.md` (and any optionals present), along with the global artifacts in `<output_folder>/`. Find:
> 1. Internal inconsistencies — rules that contradict each other within the same unit
> 2. Cross-unit contradictions — units that conflict with each other
> 3. Critical gaps — obvious behaviors not specified
> 4. Fragile statements — items marked as 🟢 CONFIRMED that appear to be inferences
>
> For each problem: indicate the affected unit, file, exact excerpt, type of problem, and a suggested fix.
> Save the result to `_reversa_sdd/cross-review-result.md`.

Wait for Codex to finish.

### Step B — Incorporate the result

After Codex finishes:

1. Read `_reversa_sdd/cross-review-result.md`
2. For each valid finding:
   - Update the corresponding spec
   - Reclassify as needed
   - Record the origin: `[Codex Review]`
3. For contestable findings, mark as 🟡 and include a note explaining the conflict
4. Proceed to the normal Review process for your own complementary analysis

---

## Review process

### 1. Per-unit review
For each unit in `<output_folder>/`:
- Are the 3 canonical files (`requirements.md`, `design.md`, `tasks.md`) present? If any are missing, record as a gap.
- Are they internally consistent? Does `requirements.md` define what is expected, `design.md` show how it is structured, and `tasks.md` cover what was promised?
- Do the business rules in `requirements.md` make sense together? Are there internal contradictions?
- Are there obvious behaviors not specified?
- Return to the original code to check 🟡 statements; reclassify according to `references/confidence-rules.md`.

### 2. Cross-unit review
- Contradictions between different units
- Declared dependencies that do not match the real ones in the code
- Units that should exist but were not generated (compare with `surface.json.modules` and `organization_suggestion.features`)

### 3. Matrix validation
- `code-spec-matrix.md` — is it complete? Are there files without a corresponding spec?
- `spec-impact-matrix.md` — does it reflect real dependencies?

### 4. Collecting gaps for the user
For each 🔴 gap that only the user can resolve, create an entry following `references/questions-template.md`.

Group all questions in `_reversa_sdd/questions.md`.

### 5. Interaction with the user

#### If `answer_mode = "chat"` (default)
Present the questions directly in the chat, one at a time or in thematic blocks:
> "[Name], I found [N] points that need your validation. May I begin?"

Process each response immediately, updating the spec and reclassifying.

#### If `answer_mode = "file"`
Create `_reversa_sdd/questions.md` with all questions formatted and say:
> "[Name], I created `_reversa_sdd/questions.md` with [N] questions that need your validation.
> Fill in the **Answer** field for each one and let me know when you are done — just type `reversa`."

Wait for the user to signal completion. Then read the file and process all responses according to `references/questions-template.md`.

### 6. Final confidence report

After processing all responses (or if there are no gaps), generate `_reversa_sdd/confidence-report.md` following `references/confidence-report-template.md`.

If a cross-review was conducted, include an additional section in the report:
```
## Cross-Review
- External engine consulted: [name]
- Findings received: [N]
- Accepted: [N] | Rejected: [N] | Pending: [N]
```

## Output

**Always:**
- `_reversa_sdd/confidence-report.md` — count of 🟢/🟡/🔴 per spec and overall percentage (simplified if `essencial`)
- `_reversa_sdd/questions.md` — if `essencial`: only critical 🔴 gaps that block reimplementation; if `completo`/`detalhado`: all 🔴 gaps

**Only if `doc_level` is `completo` or `detalhado`:**
- `_reversa_sdd/gaps.md` — gaps that remained unanswered (if `detalhado`: categorize by severity: critical/moderate/cosmetic)
- `_reversa_sdd/cross-review-result.md` — Codex findings (if cross-review was conducted)

Specs in the unit folders in `<output_folder>/` are updated in-place with the reclassifications (each unit has its own `requirements.md`, `design.md`, `tasks.md`).

## Output layout (transversal)

The Reviewer's own artifacts (`confidence-report.md`, `questions.md`, `gaps.md`, `cross-review-result.md`) are transversal to the organization chosen in `[specs]` and go in the root of `<output_folder>/`, outside the unit folders. Reclassifications of statements within each unit happen in-place in the unit's own files.

## Checkpoint

Report to Reversa:
- Number of specs reviewed
- Cross-review conducted: yes/no (engine consulted)
- Number of reclassifications (🔴→🟢, 🟡→🟢, etc.)
- Number of questions generated and answered
- Overall final confidence percentage