/docs-plan

Command Content

# MISSION

Generate a documentation plan: table of contents with Diataxis type and tone profile per section, MkDocs build configuration, README section plan, and optional hosting config. Transform audit gaps into actionable TOC entries with output paths, priority tiers, and source hints. Present the complete plan for user approval before proceeding.

<ROLE>
Documentation Planner. Your reputation depends on plans that writing agents can execute without ambiguity. A plan with missing output paths, wrong tone assignments, or ambiguous source hints derails the entire generation phase. Every TOC entry must be precise enough that a writing subagent can produce the correct document without asking clarifying questions.
</ROLE>

<analysis>
Before planning, determine:
- What gaps did the audit identify? What Diataxis types are missing?
- What existing docs can be preserved or improved (based on existing_docs_mode)?
- What is the primary language? This affects build tool and tone profile defaults.
- Which modules have high docstring coverage (>50%)? These are reference candidates.
- Which modules have test files with example usage? These are tutorial source candidates.
- Does a plan.json already exist from a previous run?
</analysis>

## Invariant Principles

1. **One Diataxis type per section**: Every TOC entry maps to exactly one type. Mode mixing is a defect caught in review, but prevented here by correct assignment.
2. **Tone follows type mapping**: Default tone profiles are assigned by Diataxis type. Users CAN override during the interview step. Overrides are respected by all downstream phases.
3. **User approves TOC before generation proceeds**: Present the full TOC table. Iterate on changes until the user confirms. Never skip this gate.
4. **Re-run policy**: Check for existing `doc-state/plan.json`. If found, present option to reuse or regenerate. Do not silently overwrite.

## Inputs

| Source | Path | Tool |
|--------|------|------|
| Audit result | `~/.local/spellbook/docs/{project-encoded}/doc-state/audit-result.json` | Read |
| Diataxis guide | `$SPELLBOOK_DIR/skills/documenting-projects/diataxis-guide.md` | Read |

Load the audit result first. If the file does not exist, STOP and inform the user that `/docs-audit` must run first.

## Tone-to-Type Mapping

| Doc Type | Default Tone Profile |
|----------|---------------------|
| Reference, API docs, Changelog, Error Catalog | Stripe-like |
| Tutorials, Explanation | React-like |
| How-To Guides | Tailwind-like |
| README | Adaptive |

Users may override any assignment during Step 6. If overridden, the non-default profile is stored in the plan and respected by `/docs-write` and `/docs-review`.

## Execution Steps

### Step 1: Check for Existing Plan

Read `~/.local/spellbook/docs/{project-encoded}/doc-state/plan.json` via Read tool.

- **File exists:** Present to the user: "Previous documentation plan found at [path]. Reuse existing plan or regenerate?" Use AskUserQuestion with options: `Reuse` / `Regenerate`.
  - If Reuse: skip to Output (return existing plan).
  - If Regenerate: proceed to Step 2.
- **File does not exist:** Proceed to Step 2.

### Step 2: Load Audit Result

Read `~/.local/spellbook/docs/{project-encoded}/doc-state/audit-result.json` via Read tool.

Validate the audit result contains:
- `language` (non-empty string)
- `gaps` (array)
- `existing_docs` (array)
- `api_surface.modules` (array)
- `api_surface.coverage` (number)
- `existing_docs_mode` (one of: `audit_improve`, `start_fresh`, `additive_only`)
- `project_metadata.name` (non-empty string)

If any required field is missing, STOP and report: "Audit result is incomplete. Re-run `/docs-audit` to regenerate."

### Step 3: Generate TOC

Transform audit results into TOC entries using the following algorithm:

**Title generation patterns by Diataxis type:**

| Diataxis Type | Title Pattern | Example |
|---------------|---------------|---------|
| Tutorial | "Getting Started with [Project]" or "Build a [Thing] with [Project]" | "Getting Started with Spellbook" |
| How-To | "How to [verb] [noun]" | "How to Configure Authentication" |
| Reference | "[Module] API Reference" | "Server API Reference" |
| Explanation | "Understanding [Concept]" or "How [Concept] Works" | "Understanding the Plugin System" |

**Output path convention:** `docs/{diataxis-type-plural}/{slug}.md`

| Diataxis Type | Directory | Example Path |
|---------------|-----------|-------------|
| Tutorial | `docs/tutorials/` | `docs/tutorials/getting-started.md` |
| How-To | `docs/how-to/` | `docs/how-to/configure-auth.md` |
| Reference | `docs/reference/` | `docs/reference/server-api.md` |
| Explanation | `docs/explanation/` | `docs/explanation/plugin-system.md` |

**Priority assignment:**

| Condition | Priority |
|-----------|----------|
| README | `mvp` (always) |
| First tutorial (getting-started) | `mvp` |
| Reference for primary module (highest usage/export count) | `mvp` |
| Additional tutorials | `tier2` |
| How-to guides | `tier2` |
| Additional reference docs | `tier2` |
| Explanation docs | `tier3` |
| Changelog, Contributing, Error Catalog, Migration | `tier4` |

**Source hints assignment:**

| Condition | Source Hint |
|-----------|------------|
| Module with >50% docstring coverage | Reference source: list module path |
| Module with test files containing example usage | Tutorial source: list test file paths |
| Module with public API but low docstring coverage | Reference source (stub): list module path |
| Existing doc being improved | Existing doc source: list doc path |

**For each gap in `audit_result.gaps`:**
1. Determine the Diataxis type from the gap description.
2. Generate a title using the type-specific pattern.
3. Generate an output path using the directory convention.
4. Assign priority per the priority table.
5. Assign default tone profile per the Tone-to-Type Mapping.
6. Collect source hints from relevant modules.

**README is ALWAYS included in the TOC regardless of quality.** If an existing README has quality="good", include it as a TOC entry with `existing_doc_path` set for preservation/improvement. README entries always have priority="mvp".

**For existing docs (when mode is `audit_improve` or `additive_only`):**
- For `audit_improve`: include existing docs with quality="stale" or quality="poor" as TOC entries with `existing_doc_path` set. Also include quality="good" README (see above).
- For `additive_only`: do not create TOC entries for existing docs. Only add entries for gaps. Exception: README is always included.
- For `start_fresh`: create all TOC entries from scratch. Do not set `existing_doc_path`.

### Step 4: Generate Build Config

In MVP (Tier 1), default to MkDocs regardless of audit recommendation. The audit's `build_tool_recommendation` informs Tier 2+ expansion to Sphinx or Docusaurus.

Check `audit_result.build_configs` first. If the project already has a working build config (e.g., existing `mkdocs.yml`), offer to reuse it instead of generating a new one.

Generate `mkdocs.yml` with MkDocs Material theme.

```yaml
site_name: {project_metadata.name} Documentation
theme:
  name: material
  palette:
    primary: indigo
    accent: indigo
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest
    - content.code.copy

nav:
  - Home: index.md
  # Generate nav entries from TOC, grouped by Diataxis type:
  - Tutorials:
    - {title}: {output_path relative to docs/}
  - How-To Guides:
    - {title}: {output_path relative to docs/}
  - Reference:
    - {title}: {output_path relative to docs/}
  - Explanation:
    - {title}: {output_path relative to docs/}

plugins:
  - search
  # If language is Python:
  - autorefs

markdown_extensions:
  - admonition
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - toc:
      permalink: true
```

Adjust `nav` to include only sections that have TOC entries. Omit empty Diataxis categories.

Store the complete YAML string in `build_config_content` and set `build_config_path` to `mkdocs.yml`.

### Step 5: Generate README Plan

Build the README section list:

```json
{
  "sections": [
    "Hook",
    "Badges",
    "Installation",
    "Quick Start",
    "Usage",
    "Features",
    "Documentation",
    "Contributing",
    "License"
  ],
  "output_path": "README.md"
}
```

The Hook section uses `project_metadata.description` as a starting point.

### Step 6: Optional Hosting Config

Present via AskUserQuestion:

```markdown
Header: "Documentation hosting"
Question: "Would you like to generate a hosting configuration?"

Options:
- GitHub Pages: Generate .github/workflows/docs.yml for automated deployment
- Read the Docs: Generate .readthedocs.yml
- Netlify: Generate netlify.toml
- Skip: No hosting config for now
```

If the user chooses a hosting provider:
- `github_pages`: Generate a GitHub Actions workflow that runs `mkdocs gh-deploy`
- `readthedocs`: Generate `.readthedocs.yml` with MkDocs build settings
- `netlify`: Generate `netlify.toml` with MkDocs build command

Store in `hosting_config` field. If skipped, omit the field.

### Step 7: Present Plan for User Approval

Display the TOC as a table:

```markdown
| # | Title | Diataxis Type | Tone Profile | Output Path | Priority |
|---|-------|---------------|--------------|-------------|----------|
| 1 | ... | tutorial | react | docs/tutorials/... | mvp |
| 2 | ... | reference | stripe | docs/reference/... | mvp |
```

Also display:
- Build tool: MkDocs (Material theme)
- Build config path: `mkdocs.yml`
- README sections: (list)
- Hosting: (choice or "none")

Use AskUserQuestion:

```markdown
Header: "Documentation plan approval"
Question: "Review the documentation plan above. Would you like to:"

Options:
- Approve: Proceed with this plan
- Modify TOC: Change titles, types, tone profiles, or priorities
- Modify build config: Change theme or plugin settings
- Regenerate: Start over with different parameters
```

If the user chooses to modify:
- Present specific questions about which entries to change.
- Apply changes and re-display the table.
- Repeat until the user approves.

## Output

Write `DocsPlan` to `~/.local/spellbook/docs/{project-encoded}/doc-state/plan.json` via the Write tool.

```typescript
interface DocsPlan {
  toc: Array<{
    title: string;
    diataxis_type: "tutorial" | "howto" | "reference" | "explanation";
    tone_profile: "stripe" | "react" | "tailwind" | "adaptive";
    output_path: string;               // Relative to project root
    priority: "mvp" | "tier2" | "tier3" | "tier4";
    source_hints: string[];            // Files/modules this section documents
    existing_doc_path?: string;        // If improving existing doc
  }>;
  build_tool: "mkdocs" | "sphinx" | "docusaurus";
  build_config_path: string;           // e.g., "mkdocs.yml"
  build_config_content: string;        // Generated config content
  hosting_config?: {
    provider: "github_pages" | "readthedocs" | "netlify";
    config_path: string;
    config_content: string;
  };
  readme_plan: {
    sections: string[];                // README section titles in order
    output_path: string;               // Usually "README.md"
  };
  project_root: string;
}
```

<FORBIDDEN>
- Assigning multiple Diataxis types to a single TOC section
- Proceeding to output without user approval of the TOC
- Generating build config for Sphinx or Docusaurus in MVP (MkDocs only)
- Omitting `output_path` for any TOC entry
- Omitting `diataxis_type` or `tone_profile` for any TOC entry
- Skipping the re-run check for existing plan.json (Step 1)
- Silently overwriting an existing plan.json without offering reuse
- Generating TOC entries for existing docs when mode is `additive_only`
- Writing plan output to the project repository (output goes to doc-state/ only)
- Assigning priority `mvp` to explanation or how-to docs (these are tier2+ in MVP)
</FORBIDDEN>

<reflection>
After completing the plan, verify:
- Does every TOC entry have exactly one Diataxis type?
- Are tone profiles consistent with the Tone-to-Type Mapping table (or explicitly overridden by user)?
- Did the user explicitly approve the final TOC?
- Does `build_config_content` contain valid YAML with nav entries matching the TOC?
- Are all output paths unique (no two sections writing to the same file)?
- Does the README always appear with priority `mvp`?
- Was the plan written to the correct doc-state/ path?
</reflection>