design-review

Plan Cascade - Review Design Document

Review the current design_doc.json and make interactive edits to components, patterns, architectural decisions, and story mappings.

Path Storage Modes

Design documents are user-visible files and remain in the working directory in both modes:

• design_doc.json: Located in current working directory (project root or worktree)
• PRD references may be in different locations based on storage mode

This command primarily works with design_doc.json in the current directory.

Tool Usage Policy (CRITICAL)

To avoid command confirmation prompts:

1. Use Read tool for file reading - NEVER use cat via Bash

   • ✅ Read("design_doc.json"), Read("prd.json")
   • ❌ Bash("cat design_doc.json")

2. Use Write tool for file updates

   • ✅ Write("design_doc.json", content)
   • ❌ Bash("echo '...' > design_doc.json")

Step 1: Load Design Document

Read design_doc.json:

If design_doc.json does not exist:
    ERROR: No design document found.

    Generate one with:
      /plan-cascade:design-generate    (from PRD)
      /plan-cascade:design-import <file>  (from external doc)
    EXIT

Step 2: Validate Document

Check for structural issues:

• Missing required sections
• Empty overview title
• Invalid ADR references
• Orphaned story mappings

Report any validation errors before proceeding.

Step 3: Display Design Document

Format and display the design document:

════════════════════════════════════════════════════════════════
                    DESIGN DOCUMENT REVIEW
════════════════════════════════════════════════════════════════

📋 OVERVIEW
────────────────────────────────────────────────────────────────
Title:   <overview.title>
Summary: <overview.summary>

Goals:
  • <goal 1>
  • <goal 2>
  ...

Non-Goals:
  • <non-goal 1>
  ...

🏗️ ARCHITECTURE
────────────────────────────────────────────────────────────────
Components (N total):

  [1] ComponentName
      Description: <description>
      Responsibilities:
        • <responsibility 1>
        • <responsibility 2>
      Dependencies: <dep1>, <dep2>
      Files: <file1>, <file2>

  [2] AnotherComponent
      ...

Data Flow:
  <data_flow description>

Patterns (M total):

  [1] PatternName
      Description: <description>
      Rationale: <rationale>

  [2] AnotherPattern
      ...

📝 ARCHITECTURAL DECISIONS
────────────────────────────────────────────────────────────────
  [ADR-001] <title>
            Status: <status>
            Context: <context>
            Decision: <decision>
            Rationale: <rationale>
            Alternatives: <alt1>, <alt2>

  [ADR-002] <title>
            ...

🔌 INTERFACES
────────────────────────────────────────────────────────────────
APIs (P endpoints):

  [API-001] <METHOD> <path>
            Description: <description>
            Request: <request_body summary>
            Response: <response summary>

  [API-002] ...

Data Models (Q models):

  [1] ModelName
      Description: <description>
      Fields:
        • field_name: <type>
        • field_name: <type>

  [2] AnotherModel
      ...

🔗 STORY MAPPINGS
────────────────────────────────────────────────────────────────
  story-001: Components=[A, B], Decisions=[ADR-001], Interfaces=[API-001]
  story-002: Components=[C], Decisions=[], Interfaces=[Model1]
  ...

════════════════════════════════════════════════════════════════