git:20260719.c80ca98 to git:20260916.268f496

---

name: review

description: >

and internal consistency. Finds issues like incomplete sections, contradictions, missing

traceability, and vague specs, then optionally auto-fixes them. Supports iterative

review-fix cycles that run until the review converges — passing, or a round with no

net reduction in findings — typically 1–2 rounds.

instructions: >

Follow the workflow below exactly. This skill reviews specification documents generated by

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

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`)

- Project manifest: `docs/project-{feature_name}.md` (if exists, for multi-split context)

3. If no spec documents found, inform the user and stop

Use `AskUserQuestion` to ask:

- **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):

- `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

**Fast path (preferred):** resolve `<sf_scripts>` (see `@../shared/scripts.md`) and run the structural gate per document —

```bash

python3 "<sf_scripts>/sf-verify-doc.py" "<file>" --strict

```

for each review target. This deterministically confirms the document is non-empty and titled, has the recommended sections for its type, has well-formed/unique IDs, and carries no leftover template placeholders or `{placeholder}` variables; use its findings as the completeness result and fix everything it flags. The script does structure, IDs, and placeholders — you still do the semantic checks (§3.3 specificity, API-signature-matching in §3.2). **Fallback:** if `python3` is unavailable or the script is not found, check by hand:

- 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**: verify the feature-spec files and the tech-design's §8.1 Component Overview describe the same component set.

**Fast path (preferred):** resolve `<sf_scripts>` (see `@../shared/scripts.md`) and run the membership check —

```bash

python3 "<sf_scripts>/sf-trace.py" chain --tech-design "<tech-design.md>" --features-dir "docs/features" --overview "docs/features/overview.md"

```

Read its fields: `slugs_without_feature_file` (a §8.1 component with no matching feature spec), `features_not_mentioned_in_tech_design` (a feature spec with no matching component), and `overview_missing_features` (used in §3.4). **Fallback:** if `python3` is unavailable or the script is not found, compare the `docs/features/{name}.md` slugs against the §8.1 rows by hand.

The script detects the mismatch; **you classify the severity** by whether it would actually break a downstream consumer like code-forge — do not hardcode Critical. A feature spec deliberately written ahead of the tech-design during iterative authoring is a Minor issue, not Critical; a genuine slug divergence that severs the traceability chain a consumer depends on is Critical.

- 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) — the `sf-trace.py chain` run in §3.2 reports this as `overview_missing_features` (feature specs absent from `overview.md`); fall back to scanning the feature index by hand if the script is unavailable.

- 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 the user's auto-fix preference already collected in Step 1 (there is a single decision point — do not re-ask here):

- **Report only**: Display all findings and stop

- **Fix Critical+Major**: auto-fix significant issues — proceed to Step 6

- **Fix all**: auto-fix everything — proceed to Step 6

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

**Convergence, not a fixed count**: iterate fix → re-review until the review passes or a round yields no net reduction in findings (typically 1–2 rounds). Stop and report the remaining issues as soon as a round makes no progress — do not keep looping on findings the fixer cannot resolve.

#### 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`** (a re-review round yielded no net reduction in findings): 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

```