Review

---
name: review
description: >
  Review spec-forge generated documents (tech-design + feature specs) for quality, completeness,
  and internal consistency. Finds issues like incomplete sections, contradictions, missing
  traceability, and vague specs, then optionally auto-fixes them. Supports iterative
  review-fix cycles with a maximum of 2 iterations.
instructions: >
  Follow the workflow below exactly. This skill reviews specification documents generated by
  spec-forge (tech-design, feature specs, overview). It does NOT review code or non-spec documents.
  Every finding must cite a specific file and section. Do NOT fabricate issues — only report what
  you actually find. Auto-fix only modifies cited sections, never restructures entire documents.
---

# Review — Specification Quality & Consistency Review

Systematically review spec-forge generated documents for quality, completeness, and internal consistency. Optionally auto-fix issues found.

## Core Principles

1. **Evidence-based**: Every finding must cite a specific file and section — no vague complaints
2. **Spec-focused**: Review specification documents only (tech-design, feature specs, overview) — not code, not upstream idea drafts
3. **Upstream-aware**: Use idea drafts and project manifests as reference context to validate spec accuracy, but do not review them
4. **Prioritized**: Findings classified by severity so the user can act on what matters first
5. **Conservative fixes**: Auto-fix only touches cited sections; when domain knowledge is missing, leave a `<!-- REVIEW: {question} -->` comment instead of guessing
6. **Honest**: Report real issues, don't inflate findings to look thorough

## Severity Levels

| Severity | Meaning | Example |
|----------|---------|---------|
| **Critical** | Wrong, contradictory, or misleading content | Feature spec API signature contradicts tech-design, component boundary mismatch |
| **Major** | Significant gap that would block or confuse implementation | Empty required section, missing error handling spec, undefined edge cases |
| **Minor** | Quality issue that degrades usefulness but isn't blocking | Vague description, missing cross-reference, inconsistent terminology |

## Workflow

### Step 1: Determine Review Scope

Parse the arguments to determine what to review:

1. If a `feature_name` argument is provided, look for:
   - `docs/{feature_name}/tech-design.md`
   - All feature specs in `docs/features/` (glob for `docs/features/*.md`)
   - Upstream reference: `ideas/{feature_name}/draft.md` (if exists)
   - Project manifest: `docs/project-{feature_name}.md` (if exists, for multi-split context)
2. If no argument, scan `docs/` for the most recent tech-design and all feature specs in `docs/features/`
3. If no spec documents found, inform the user and stop

Use `AskUserQuestion` to ask:
- **Review scope**: Review all generated specs, or focus on specific documents? (Options: All / Tech design only / Feature specs only / Specific files)
- **Auto-fix**: Should I auto-fix issues found? (Options: Yes — fix Critical+Major automatically / Yes — fix all / No — report only)

### Step 2: Document Inventory

Build the list of documents to review:

1. **Review targets** (will be reviewed):
   - `docs/{feature_name}/tech-design.md`
   - `docs/features/overview.md`
   - `docs/features/{component-1}.md`, `docs/features/{component-2}.md`, etc.
   - For multi-split: tech-designs for all sub-features

2. **Reference context** (read for context, NOT reviewed):
   - `ideas/{feature_name}/draft.md` — upstream requirements
   - `docs/project-{feature_name}.md` — project manifest with sub-feature scope

3. Read each review target document fully

Display the inventory:

```
Review scope: {feature_name}
  Review targets: {N} documents
    - docs/{feature_name}/tech-design.md
    - docs/features/overview.md
    - docs/features/{component-1}.md
    - docs/features/{component-2}.md
    ...
  Reference context: {N} documents
    - ideas/{feature_name}/draft.md
```

### Step 3: Review

Check each review target document against the following checklist:

#### 3.1 Completeness
- Any empty sections, TBD/TODO markers, placeholder text, or `{placeholder}` template variables?
- Missing required sections per document type?
  - Tech design: Goals, Non-goals, Scope, Architecture, API Design, Data Model, Component Overview
  - Feature spec: Purpose, API/Interface, Logic/Behavior, Error Handling, Dependencies
  - Overview: Feature index listing all generated specs, dependency graph

#### 3.2 Internal Consistency
- **Component name matching**: For every feature spec file (`docs/features/{name}.md`), verify there is a corresponding row in the tech-design's §8.1 Component Overview with an identical slug. Raise a Critical finding if a feature spec exists with no matching component or vice versa — this breaks the traceability chain and confuses downstream consumers like code-forge.
- Do feature spec API signatures match the tech-design's API Design section?
- Do component boundaries in feature specs align with tech-design's Component Overview?
- Are data models consistent across documents? (field names, types, relationships)
- Do feature specs reference the same architectural patterns described in the tech-design?
- For multi-split: are cross-sub-feature interfaces consistent?

#### 3.3 Specificity
- Vague descriptions that should be concrete (e.g., "handles errors appropriately" → specific error codes/behaviors)
- Ambiguous quantifiers (e.g., "fast", "large", "many" without concrete thresholds)
- Undefined behavior for edge cases or boundary conditions

#### 3.4 Traceability
- Do feature specs reference back to tech-design sections they implement?
- Does overview.md list ALL generated feature specs? (no missing entries)
- Are dependency relationships between feature specs documented and consistent?

#### 3.5 Actionability
- Could a developer implement from these specs without guessing?
- Are input/output formats fully specified?
- Are error scenarios and recovery behaviors defined?
- Are configuration options and defaults documented?

### Step 4: Generate Findings

For each issue found, produce a structured finding:

```
- [{severity}] {file_path} § {section}: {description of issue} → FIX: {concrete fix instruction}
```

Compile the full review result:

```
REVIEW_RESULT: {PASS | ISSUES_FOUND}
CRITICAL_COUNT: {N}
MAJOR_COUNT: {N}
MINOR_COUNT: {N}

FINDINGS:
- [{severity}] {file_path} § {section}: {description} → FIX: {fix instruction}
...
```

### Step 5: Present Results

Display summary:

```
spec-forge review: {feature_name}

  Documents reviewed: {N}
  Result: {PASS | ISSUES_FOUND}
  Findings: {critical} critical, {major} major, {minor} minor

  {If ISSUES_FOUND, list top findings}
```

If `REVIEW_RESULT: PASS`, inform the user and stop.

If `REVIEW_RESULT: ISSUES_FOUND`, proceed based on user's auto-fix preference from Step 1:
- **Report only**: Display all findings and stop
- **Auto-fix**: Proceed to Step 6

If auto-fix was not pre-selected, ask now via `AskUserQuestion`:
- **Fix Critical+Major** — auto-fix significant issues
- **Fix all** — auto-fix everything
- **Skip** — just the report

### Step 6: Auto-Fix (Iterative)

**Maximum iterations**: 2 (one fix + one re-review). If issues persist after 2 iterations, report remaining issues and stop.

#### 6.1 Apply Fixes

For each finding to fix:

1. Read the target file
2. Apply the concrete fix described in the finding
3. Rules:
   - Only modify the specific section cited in the finding
   - Do NOT restructure or rewrite entire documents
   - Do NOT add new documents — only fix existing ones
   - If a fix requires information you don't have (e.g., specific domain logic), add a `<!-- REVIEW: {question} -->` comment instead of guessing
   - Do NOT change content unrelated to the findings

#### 6.2 Re-Review

After all fixes are applied, re-run the review (Step 3-4) on the same documents.

- **If `REVIEW_RESULT: PASS`**: Display success
  ```
  spec-forge review: PASS after fixes — {N} issues resolved
  ```

- **If `REVIEW_RESULT: ISSUES_FOUND`** (iteration 2): Display remaining issues and stop
  ```
  spec-forge review: {N} issues remain after auto-fix

  Remaining issues:
    - [{severity}] {file} § {section}: {description}
    ...

  These may require manual attention or domain-specific decisions.
  ```

### Step 7: Summary

Display final status:

```
spec-forge review complete: {feature_name}

  Documents reviewed: {N}
  Issues found: {total}
  Issues fixed: {fixed}
  Issues remaining: {remaining}

Next steps:
  /code-forge:plan @docs/features/{component-name}.md   → Generate implementation plan
  /spec-forge:review {feature_name}                      → Re-run review after manual fixes
```