---
name: docs-plan
description: Create an ordered documentation plan based on discovered modules
---

# Documentation Planning Workflow

**Goal:** Analyze discovered modules and create an ordered documentation plan that prioritizes core modules and identifies relationships.

**Your Role:** You are a documentation architect. You will analyze the knowledge base, identify dependencies, and create an optimal documentation order.

**Requires:** `docs/.knowledge/` from `/docs:discover`

---

## ARGUMENTS PARSING

Parse the arguments:
```
/docs:plan [--auto] [--show]
```

Examples:
```
/docs:plan                         # Create plan interactively
/docs:plan --auto                  # Auto-generate plan (no prompts)
/docs:plan --show                  # Show existing plan
```

---

## STEP 1: CHECK PREREQUISITES

### 1.1 Verify Discovery Completed

Check if `docs/.knowledge/` exists and has module data:

```
🔍 Checking knowledge base...

□ Discovery data    → Looking for docs/.knowledge/
```

If not found:
```
❌ No discovered modules found.

Run `/docs:discover` first to scan your codebase.
```

### 1.2 Load Module Index

Read `docs/.knowledge/_meta/modules-index.json`:

```
✓ Discovery data found

Modules discovered: 6
  • users
  • campaigns
  • orders
  • products
  • payments
  • notifications
```

---

## STEP 2: ANALYZE MODULES

### 2.1 Load Each Module's Data

For each module, read:
- `entity.json` - Fields, types, relationships
- `routes.json` - API endpoints
- `validation.json` - Validation rules

### 2.2 Build Dependency Graph

Analyze relationships to determine order:

```
📊 Analyzing module dependencies...

Dependency graph:
  users ────────────────────────────────┐
    │                                   │
    ├──→ campaigns (has many)          │
    │       │                           │
    │       └──→ orders (belongs to)    │
    │              │                    │
    │              └──→ payments        │
    │                                   │
    └──→ notifications (polymorphic) ──┘

  products (standalone)
    │
    └──→ orders (many to many)

Core modules (no dependencies): users, products
Dependent modules: campaigns, orders, payments, notifications
```

### 2.3 Calculate Priority

Determine documentation order:

```
📋 Suggested documentation order:

Priority 1 (Core - document first):
  [1] users        - 12 fields, 3 relationships, 5 routes
  [2] products     - 8 fields, 2 relationships, 4 routes

Priority 2 (Primary features):
  [3] campaigns    - 15 fields, 4 relationships, 6 routes
  [4] orders       - 10 fields, 5 relationships, 5 routes

Priority 3 (Supporting):
  [5] payments     - 6 fields, 2 relationships, 3 routes
  [6] notifications - 4 fields, 1 relationship, 2 routes
```

---

## STEP 3: INTERACTIVE PLANNING (unless --auto)

### 3.1 Confirm Modules to Include

```
📋 Module Selection

Include all discovered modules?

[1] Yes, include all 6 modules
[2] Let me select which to include
[3] Exclude some modules

Choice:
```

If user selects option 2 or 3:
```
Select modules to document:

[x] users           - Core user management
[x] campaigns       - Marketing campaigns
[x] orders          - Order processing
[ ] products        - Product catalog (skip)
[x] payments        - Payment handling
[ ] notifications   - Notification system (skip)

Selected: 4 modules
```

### 3.2 Confirm Order

```
📋 Documentation Order

Suggested order (dependencies first):
  1. users
  2. campaigns
  3. orders
  4. payments

[1] Accept this order
[2] Customize order
[3] Sort alphabetically

Choice:
```

### 3.3 Configure Per-Module Options

```
📋 Documentation Options

For each module, what should be documented?

users:
  [x] Full lifecycle (CRUD)
  [x] Include error states
  [ ] Custom flows

campaigns:
  [x] Full lifecycle (CRUD)
  [x] Include error states
  [x] Custom flows:
      - duplicate campaign
      - archive campaign

orders:
  [x] Full lifecycle (CRUD)
  [x] Include error states
  [ ] Custom flows

payments:
  [x] Full lifecycle (CRUD)
  [x] Include error states
  [ ] Custom flows
```

### 3.4 Cross-Module Flows

```
📋 Cross-Module Flows

Detected potential flows spanning multiple modules:

[x] User registration → First campaign
    Modules: users, campaigns

[x] Order checkout → Payment
    Modules: orders, payments, products

[ ] Custom flow (describe)

Selected: 2 cross-module flows
```

---

## STEP 4: GENERATE PLAN FILE

Create `docs/plan.yml`:

```yaml
# Documentation Plan
# Generated by /docs:plan
# Run /docs:execute to generate documentation

created_at: 2024-01-15T10:30:00Z
status: pending
total_modules: 4
estimated_docs: 12

modules:
  - name: users
    priority: 1
    reason: "Core module - other modules depend on it"
    knowledge_path: "docs/.knowledge/modules/users/"
    document:
      lifecycle: true
      include_errors: true
      flows: []
    output:
      directory: "docs/users/"
      files:
        - index.md
        - lifecycle.md
    status: pending

  - name: campaigns
    priority: 2
    reason: "Primary feature module with custom flows"
    knowledge_path: "docs/.knowledge/modules/campaigns/"
    document:
      lifecycle: true
      include_errors: true
      flows:
        - "duplicate campaign"
        - "archive campaign"
    output:
      directory: "docs/campaigns/"
      files:
        - index.md
        - lifecycle.md
        - duplicate-campaign.md
        - archive-campaign.md
    status: pending

  - name: orders
    priority: 3
    reason: "Depends on users and products"
    knowledge_path: "docs/.knowledge/modules/orders/"
    document:
      lifecycle: true
      include_errors: true
      flows: []
    output:
      directory: "docs/orders/"
      files:
        - index.md
        - lifecycle.md
    status: pending

  - name: payments
    priority: 4
    reason: "Depends on orders"
    knowledge_path: "docs/.knowledge/modules/payments/"
    document:
      lifecycle: true
      include_errors: true
      flows: []
    output:
      directory: "docs/payments/"
      files:
        - index.md
        - lifecycle.md
    status: pending

cross_module_flows:
  - name: "user-registration-to-first-campaign"
    title: "User Registration to First Campaign"
    modules: [users, campaigns]
    output: "docs/users/user-registration-to-first-campaign.md"
    status: pending

  - name: "order-checkout-payment"
    title: "Order Checkout to Payment"
    modules: [orders, payments, products]
    output: "docs/orders/order-checkout-payment.md"
    status: pending

output_structure:
  root: "docs/"
  index: "docs/index.md"
  module_pattern: "docs/{module}/"
  images_pattern: "docs/{module}/images/"
```

---

## STEP 5: DISPLAY SUMMARY

```
✅ Documentation Plan Created

📄 Plan saved to: docs/plan.yml

📊 Summary:
   Modules to document: 4
   Custom flows: 2
   Cross-module flows: 2
   Estimated files: 12

📋 Order:
   1. users (core)
   2. campaigns (2 custom flows)
   3. orders
   4. payments

📁 Output structure:
   docs/
   ├── index.md
   ├── users/
   ├── campaigns/
   ├── orders/
   └── payments/

💡 Next step: Run /docs:execute to generate documentation
```

---

## STEP 6: HANDLE --show FLAG

If `--show` was provided, display existing plan:

```
📋 Current Documentation Plan

Created: 2024-01-15 10:30:00
Status: in_progress

Progress:
  ✓ users         - Complete
  → campaigns     - In progress (50%)
  ○ orders        - Pending
  ○ payments      - Pending

Cross-module flows:
  ○ user-registration-to-first-campaign - Pending
  ○ order-checkout-payment - Pending

Resume with: /docs:execute --continue
```

---

## ERROR HANDLING

| Error | Action |
|-------|--------|
| No discovery data | Prompt to run `/docs:discover` first |
| Empty modules | Warn user, offer to re-run discover |
| Circular dependencies | Warn and suggest manual ordering |
| Existing plan | Ask to overwrite or show existing |

---

## COMPLETION

```
✅ Plan created successfully

📄 docs/plan.yml ready
📊 4 modules, 2 cross-module flows
💡 Run /docs:execute to start generating documentation
```
