docs-manager

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).

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
4. Documentation Planning — Translate analysis findings into a concrete plan for user approval
5. Documentation Generation — Launch documentation writing tasks 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 input

Accept the following inputs:

• action-or-description — What kind of documentation to create or update

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, prompt the user to choose:

• "MkDocs documentation site" — Full docs site with mkdocs.yml, Material theme
• "Basic markdown files" — Standalone files like README.md, CONTRIBUTING.md, ARCHITECTURE.md
• "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: Prompt the user — Existing project or new setup?

• "Existing MkDocs project" → MKDOCS_MODE = existing
• "New MkDocs setup" → MKDOCS_MODE = new

Q3 (if existing): Prompt the user — What to do?

• "Generate new pages"
• "Update existing pages"
• "Both — generate and update"

Store as ACTION.

Q3 (if new): Prompt the user — Scope?

• "Full documentation"
• "Getting started only (minimal init)"
• "Custom pages"

Store as MKDOCS_SCOPE. If custom, prompt the user for desired pages (free text).

If DOC_TYPE = basic-markdown:

Q2: Prompt the user — Which files? The user may select multiple options:

• "README.md"
• "CONTRIBUTING.md"
• "ARCHITECTURE.md"
• "API documentation"

Store as MARKDOWN_FILES. If "Other" is selected, prompt the user for custom file paths/descriptions.

If DOC_TYPE = change-summary:

Q2: Prompt the user — 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 prompt the user to choose:

• "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)

• Search for files matching 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. Use the MkDocs Configuration Template (see below) to scaffold the configuration
2. Fill template with detected metadata (ask the user if incomplete)
3. Generate mkdocs.yml, create docs/index.md and docs/getting-started.md
4. Present scaffold for confirmation before writing

If MKDOCS_SCOPE = minimal (getting started only): write the scaffold files 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 to understand what to document.

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 codebase analysis

Refer to the deep-analysis skill (from the core-tools package) and follow its workflow.

Pass the documentation-focused analysis context from Step 1.

The deep analysis handles all exploration orchestration (reconnaissance, team planning, parallel exploration, and synthesis).

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

After analysis, additionally:

1. Run git diff --name-only [base-ref] for changed files
2. Search existing docs for references to changed files/functions
3. Cross-reference with synthesis findings

For change-summary path (instead of deep analysis)

1. Run git log --oneline [range] and git diff --stat [range]
2. Delegate to a code exploration task to analyze the changed files:
3. Focus: Analyze files changed in the specified range
4. For each significant change, identify what was added/modified/removed, impact on public APIs, and whether any changes are breaking
5. Return a structured report of findings

Immediately proceed to Phase 4.

Phase 4: Documentation Planning

Goal: Translate analysis findings into a concrete documentation plan.

Step 1 — Produce plan based on doc type

MkDocs:

• Pages to create (with docs/ paths)
• Pages to update (with specific sections)
• Proposed mkdocs.yml nav updates
• Page dependency ordering (independent pages first, then pages that cross-reference them)

Basic Markdown:

• Files to create/update (with target paths)
• Proposed structure/outline for each file
• Content scope per file

Change Summary:

• Output formats to generate (Format 1: Changelog, Format 2: Commit message, Format 3: MkDocs page — only if MkDocs site exists)
• Range confirmation
• Scope of c