docs-manager

What this skill does

# Documentation Manager Workflow

Execute a structured 6-phase workflow for managing documentation. Supports two documentation formats (MkDocs sites and standalone markdown files) and three action types (generate, update, change summary).

**CRITICAL: Complete ALL applicable phases.** Some phases are conditional. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

## Phase Overview

Execute these phases in order, completing ALL of them:

1. **Interactive Discovery** — Determine documentation type, format, and scope through user interaction
2. **Project Detection & Setup** — Detect project context, conditionally scaffold MkDocs
3. **Codebase Analysis** — Deep codebase exploration using the deep-analysis skill
4. **Documentation Planning** — Translate analysis findings into a concrete plan for user approval
5. **Documentation Generation** — Launch docs-writer agents to generate content
6. **Integration & Finalization** — Write files, validate, present results

---

## Phase 1: Interactive Discovery

**Goal:** Determine through user interaction what documentation to create and in what format.

### Step 1 — Infer intent from `$ARGUMENTS`

Parse the user's input to pre-fill selections:
- Keywords like "README", "CONTRIBUTING", "ARCHITECTURE" → infer `basic-markdown`
- Keywords like "mkdocs", "docs site", "documentation site" → infer `mkdocs`
- Keywords like "changelog", "release notes", "what changed" → infer `change-summary`

If the intent is clear, present a summary for quick confirmation before proceeding (skip to Step 4). If ambiguous, proceed to Step 2.

### Step 2 — Q1: Documentation type

If the documentation type is ambiguous or needs confirmation, use `AskUserQuestion`:

```
What type of documentation would you like to create?
1. "MkDocs documentation site" — Full docs site with mkdocs.yml, Material theme
2. "Basic markdown files" — Standalone files like README.md, CONTRIBUTING.md, ARCHITECTURE.md
3. "Change summary" — Changelog, release notes, commit message
```

Store as `DOC_TYPE` = `mkdocs` | `basic-markdown` | `change-summary`.

### Step 3 — Conditional follow-up questions

**If `DOC_TYPE = mkdocs`:**

Q2: `AskUserQuestion` — Existing project or new setup?
- "Existing MkDocs project" → `MKDOCS_MODE = existing`
- "New MkDocs setup" → `MKDOCS_MODE = new`

Q3 (if `existing`): `AskUserQuestion` — What to do?
- "Generate new pages"
- "Update existing pages"
- "Both — generate and update"
Store as `ACTION`.

Q3 (if `new`): `AskUserQuestion` — Scope?
- "Full documentation"
- "Getting started only (minimal init)"
- "Custom pages"
Store as `MKDOCS_SCOPE`. If custom, use `AskUserQuestion` for desired pages (free text).

**If `DOC_TYPE = basic-markdown`:**

Q2: `AskUserQuestion` (multiSelect) — Which files?
- "README.md"
- "CONTRIBUTING.md"
- "ARCHITECTURE.md"
- "API documentation"
Store as `MARKDOWN_FILES`. If "Other" is selected, use `AskUserQuestion` for custom file paths/descriptions.

**If `DOC_TYPE = change-summary`:**

Q2: `AskUserQuestion` — What range?
- "Since last tag"
- "Between two refs"
- "Recent changes"
Follow up for specific range details (tag name, ref pair, etc.).

### Step 4 — Confirm selections

Present a summary of all selections and use `AskUserQuestion`:
- "Proceed"
- "Change selections"

If the user wants to change, loop back to the relevant question.

**Immediately proceed to Phase 2.**

---

## Phase 2: Project Detection & Setup

**Goal:** Detect project context automatically, conditionally scaffold MkDocs.

### Step 1 — Detect project metadata (all paths)

- Check manifests: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`
- Run `git remote get-url origin 2>/dev/null`
- Note primary language and framework

### Step 2 — Check existing documentation (all paths)

- Glob for `docs/**/*.md`, `README.md`, `CONTRIBUTING.md`, `ARCHITECTURE.md`
- For MkDocs: check for `mkdocs.yml`/`mkdocs.yaml`, read if found

### Step 3 — MkDocs Initialization (only if `DOC_TYPE = mkdocs` AND `MKDOCS_MODE = new`)

1. Load `${CLAUDE_PLUGIN_ROOT}/skills/docs-manager/references/mkdocs-config-template.md`
2. Fill template with detected metadata (ask via `AskUserQuestion` if incomplete)
3. **Ensure MkDocs dependencies are installed** so the Phase 6 build/serve checks can run:
   - Python project (`pyproject.toml`): add a `docs` dependency group with `mkdocs-material` and `pymdown-extensions` (e.g. under `[dependency-groups]`), then sync (`uv sync --group docs`, or `pip install mkdocs-material`).
   - Other projects: MkDocs is Python-based — `pip install mkdocs-material` (or `pipx`).
   - If `mkdocs` is already importable/on PATH, skip.
4. Generate `mkdocs.yml` (keep its `extra_css` key) and create:
   - `docs/index.md` and `docs/getting-started.md`
   - **`docs/stylesheets/extra.css`** — the Mermaid dark-mode companion from the template. **Not optional:** the palette ships a dark `slate` scheme, and the standard Mermaid palette (light fills + dark text) is unreadable in dark mode without it.
5. Present scaffold for confirmation before writing

If `MKDOCS_SCOPE = minimal` (getting started only): write the scaffold files (including `docs/stylesheets/extra.css`) and skip to Phase 6.

### Step 4 — Set action-specific context (for update/change-summary)

For **update** modes, determine the approach:
- **git-diff** — Update docs affected by recent code changes (default if user mentions "recent changes" or a branch/tag)
- **full-scan** — Compare all source code against all docs for gap analysis (default if user says "full update" or "sync all")
- **targeted** — Update specific pages or sections (default if user specifies file paths or page names)

For **change-summary**, run `git log` and `git diff --stat` for the determined range.

**Immediately proceed to Phase 3.**

---

## Phase 3: Codebase Analysis

**Goal:** Deep codebase exploration using the deep-analysis skill.

**Skip conditions:**
- Skip for `change-summary` (uses git-based analysis instead — see below)
- Skip for MkDocs minimal init-only (`MKDOCS_SCOPE = minimal`)

### Step 1 — Build documentation-focused analysis context

Construct a specific context string based on Phase 1 selections:

| Selection | Analysis Context |
|-----------|-----------------|
| MkDocs generate | "Documentation generation — find all public APIs, architecture, integration points, and existing documentation..." |
| MkDocs update | "Documentation update — identify changes to public APIs, outdated references, documentation gaps..." |
| Basic markdown README | "Project overview — understand purpose, architecture, setup, key features, configuration, and dependencies..." |
| Basic markdown ARCHITECTURE | "Architecture documentation — map system structure, components, data flow, design decisions, key dependencies..." |
| Basic markdown API docs | "API documentation — find all public functions, classes, methods, types, their signatures and usage patterns..." |
| Basic markdown CONTRIBUTING | "Contribution guidelines — find dev workflow, testing setup, code style rules, commit conventions, CI process..." |
| Multiple files | Combine relevant contexts from above |

### Step 2 — Run deep-analysis

Read `${CLAUDE_PLUGIN_ROOT}/../core-tools/skills/deep-analysis/SKILL.md` and follow its workflow.

Pass the documentation-focused analysis context from Step 1.

Deep-analysis handles all agent orchestration (reconnaissance, team planning, approval — auto-approved when skill-invoked — team creation, code-explorers + code-synthesizer). Since docs-manager is the calling skill, deep-analysis returns control without standalone summary.

**Note:** Deep-analysis may return cached results if a valid exploration cache exists. In skill-invoked mode, cache hits are auto-accepted — this is expected behavior that avoids redundant exploration.

### Step 3 — Supplemental analysis for update with git-diff mode

After deep-analysis, additionally:
1. Run `git diff --name-only [base-ref]` fo