Review

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

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

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 —

  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