Docs Workflow

All modes end with a deterministic verification step. See the Verification section below.

Mode Selection

If the user doesn't specify a mode, infer from context:

• Existing docs + recent code changes → update
• No docs exist for the target → quickstart
• User wants to plan or assess → analyze
• Docs have accumulated and need triage → consolidate
• Unclear → ask which mode

Intent-based classification: When selecting a mode or classifying content, use the intent classification to identify what type of documentation is needed (tutorial, how-to, explanation, reference). See references/docs-structure.md for the classification and references/principles.md P1 for the intent-first taxonomy principle.

Verification

All modes end with deterministic verification. The verification script is bundled with this skill at scripts/docs_verify.py (relative to the skill directory, NOT the target repo). Run it by reading the script content and executing it against the target repo root:

python <skill-dir>/scripts/docs_verify.py <target-repo-root>

If the script is not directly executable (e.g., the agent cannot resolve the skill directory), replicate its checks manually:

• Internal links resolve to existing files
• Frontmatter is present on docs/*.md content files (excluding README.md and AGENTS.md)
• docs/AGENTS.md index is complete (references all docs/ files)
• docs/README.md links are valid

This implements references/principles.md P3 (deterministic verification over subjective quality).

See references/deterministic-doc-tests.md for pytest-based test patterns that repos can adopt.

Mode: Analyze

Purpose: Audit existing documentation and create a documentation plan.

Use when: Starting fresh, assessing documentation needs, planning what to write.

Process:

1. Study any reference documentation as exemplars
2. Scan existing docs (e.g., /docs directory)
3. Identify gaps, outdated content, or temporary documentation
4. Create a documentation plan

Output: For each proposed document:

• Document title and output location
• Table of contents / structured outline
• 100-200 word writing sample demonstrating style

Validation checklist (verify before finishing):

• Every proposed doc has title, location, TOC, writing sample, priority, and effort estimate
• Commands in writing samples are annotated as verified (confirmed from source) or unverified
• No speculative content; UNKNOWN used where details cannot be confirmed from code
• Output follows the structured plan format from references/analyze.md

Detailed instructions: Load references/analyze.md

Mode: Quickstart

Purpose: Generate one-screen, high-signal onboarding docs for a module.

Use when: A module needs documentation from scratch or comprehensive refresh.

Inputs (gather from user or infer):

• feature_dir: Repo-relative path to the module
• tech_stack: Languages, frameworks, services
• scope: What modules are covered
• known_docs: Any existing related docs

Output location: <feature_dir>/docs/

Generated files (reading order set by tour.md reading guide):

tour.md           # Quickstart + module overview (≤500 words + 1 diagram)
architecture.md   # Structure with diagrams (≤5 diagrams total)
interfaces.md     # Public API, events, types
data.md           # Tables, cache keys, invariants (only if applicable)
exercises.md      # Up to 5 learning tasks
tests.md          # Only if tests exist

Diagram rules:

• Prefer Mermaid flowchart LR
• ≤10 nodes per diagram, ≤5 diagrams total
• No parentheses () in node text
• Add Updated: YYYY-MM-DD below each

Detailed instructions: Load references/quickstart.md

Mode: Update

Purpose: Sync documentation with code changes.

Use when: Code has changed and docs may be stale.

Auto-detection (in order):

1. Uncommitted changes in working directory
2. Current branch vs main/master
3. Last 10 commits on current branch
4. Last 7 days of commits (fallback)

Change categories:

• 🔴 Breaking: API changes, removed features, changed behaviors
• 🟡 Feature: New functionality, endpoints, options
• 🟢 Enhancement: Performance, UI/UX improvements
• Fix: Bug fixes affecting documented behavior

Sub-modes:

• PLAN (default): Present update report, ask which to proceed with
• AUTO: Execute critical and important updates automatically

Output format:

## Documentation Update Report

### Summary
- X files need updates
- Y new documents recommended
- Z deprecated sections to remove

### Priority Actions
#### 🔴 Critical Updates
#### 🟡 Important Updates
#### 🟢 Minor Updates

### Detailed Changes
[File-by-file instructions]

Detailed instructions: Load references/update.md

Mode: Consolidate

Purpose: Inventory all docs in a repo, classify each file, and produce a manifest to clean up stale, scattered, or misplaced content.

Use when: Docs have accumulated over time and need triage — finished migration plans, redundant references, human-facing content in AGENTS.md, or gaps with no doc.

Sub-modes:

• PLAN (default): Produce inventory report and manifest; present before touching any files
• AUTO: Execute manifest after showing it

Classification: First classify each file by doc type (tutorial/how-to/explanation/reference) and audience (agent/human). Then derive the action:

• Keep: Accurate reference docs, architecture docs, how-to guides still actively used
• Archive → docs/_archive/: Completed migration plans, one-time runbooks for finished work, superseded content
• Move: Human-facing content in AGENTS.md → docs/{topic}-reference.md; misplaced docs
• Create: Identified gaps (e.g., no routing index, missing reference doc for a configured tool)
• Rename: Naming inconsistencies vs. derived conventions

Output format:

## Consolidation Report

### Inventory
- X files in docs/
- Y nested AGENTS.md files reviewed for misplaced content
- Z root .md files

### Manifest
#### Keep
- docs/architecture.md — accurate architecture reference
#### Archive → docs/_archive/
- docs/migration-plan-2024.md — migration complete, superseded
#### Move
- config/editor/AGENTS.md (keybindings section) → docs/editor-reference.md
#### Create
- docs/AGENTS.md — routing index for docs/

### Actions pending: N

Detailed instructions: Load references/consolidate.md

Universal Guidelines

See references/principles.md for the full set of documentation principles that guide all modes.

Writing style:

• Concise, factual, imperative voice
• Prefer examples over prose
• Every documented element should serve a purpose
• Good docs are discoverable, actionable, maintenance-friendly

Frontmatter: All generated docs/*.md content files get simplified YAML frontmatter. AGENTS.md files are routing indexes and do not require frontmatter -- agents auto-discover them by convention.

---