doc-updater

name

doc-updater

description

Automatically update documentation to reflect current codebase state. Use this skill whenever the user wants to update, refresh, or sync documentation with code changes — including design docs, README, usage guides, API docs, test docs, architecture docs, or any markdown/text documentation files. Make sure to use this skill when the user mentions "update docs", "同步文档", "更新文档", "文档跟进", "刷新文档", or when they've finished a coding session and want the documentation in a specific directory brought up to date. Also use when the user wants to create a new documentation file in a directory and no matching file exists yet — the skill will survey the codebase and generate appropriate documentation from scratch.

Doc Updater

A skill for keeping documentation in sync with code changes. Two core scenarios:

1. Incremental update — code has changed, existing docs need to reflect those changes
2. Create from scratch — a documentation file is requested but doesn't exist yet

---

Scenario 1: Incremental Documentation Update

When the user asks to update documentation in a directory that already contains docs:

Step 1: Gather Change Sources (Parallel)

Fire these subagents in parallel — they're independent:

Agent A — Session history review:

task(subagent_type="explore", run_in_background=true, load_skills=[],
  prompt="[CONTEXT]: The user wants to update documentation in {target_dir}. I need to understand what code changes happened in the current session.
[GOAL]: Find all modifications made to files under {target_dir} (or related code directories) in the current conversation session.
[DOWNSTREAM]: I will use this to determine what documentation sections need updating.
[REQUEST]: Review the session history for any file edits, reads, or writes related to {target_dir}. Return a summary of what changed: file paths, nature of changes, and which logical features/components were touched.")

Agent B — Git diff analysis:

Execute: git diff --stat and git diff --name-status for {target_dir} and related directories.
Focus on commits or uncommitted changes. Return:
- List of changed files with change type (added/modified/deleted)
- Brief summary of what each change does (read the diffs if needed)
- Any new files, renamed files, or deleted files")

Agent C — Existing documentation inventory:

task(subagent_type="explore", run_in_background=true, load_skills=[],
  prompt="[CONTEXT]: The user wants to update documentation in {target_dir}.
[GOAL]: Catalog all existing documentation files and their current structure.
[DOWNSTREAM]: I will use this to identify which existing doc sections map to the changed code.
[REQUEST]: In {target_dir}, list all documentation files (.md, .txt, .rst). For each file, extract:
- The table of contents / section headings
- What features, APIs, or components it documents
- Last-modified date if available
Return a structured index.")

Step 2: Synthesize Changes

Once all three agents complete:

1. Collect results from Agents A, B, and C
2. Build a change-to-doc mapping table:

Code Change	Affected Doc File(s)	Doc Section(s) to Update	Update Type
e.g., new API endpoint /users/batch	api-reference.md	"User endpoints" section	Add new endpoint docs
e.g., renamed fetchData → loadData	usage.md	Code examples	Replace function names
e.g., new module auth/jwt.py	(none yet)	—	Needs new section or file

3. Identify update types:
   • Replace — section exists but content is stale (rewrite in-place)
   • Add — new feature/component needs new section (insert at logical position)
   • Remove — deleted feature/section should be removed from docs
   • Rename — reflected in doc headings, cross-references, and content

Step 3: Apply Updates

For each affected document, use a single subagent per file to apply all updates at once:

task(category="writing", load_skills=[], run_in_background=false,
  prompt="Update the documentation file at {doc_file_path}.

TASK: Apply {N} targeted updates to this file based on code changes.

EXPECTED OUTCOME: The same file with updated content — format, structure, and style must remain identical to the original.

REQUIRED TOOLS: Read, Edit

MUST DO:
1. Read the current file first to understand its structure and style
2. For REPLACE updates: find the exact section and rewrite it to reflect current code
3. For ADD updates: insert new sections at the most logical position (follow existing heading hierarchy)
4. For REMOVE updates: delete the stale section entirely
5. For RENAME updates: update all mentions — headings, inline text, code examples, cross-references
6. Preserve the original formatting: heading levels, code block language tags, link styles, list styles
7. Preserve the original tone and writing style

MUST NOT DO:
- Do NOT append all changes at the end of the file
- Do NOT change section ordering unless absolutely necessary
- Do NOT alter sections that are unaffected by code changes
- Do NOT change the overall document structure
- Do NOT modify the table of contents without also checking it matches the new headings

CONTEXT:
- Current file: {read the file}
- Changes to apply: {list from mapping table, with details from git diff and session review}
- Related code files for reference: {list paths}")

Key Principles for Incremental Updates

• In-place updates over appending: Every change should land in the correct section, not tacked on at the end
• Format preservation: If the doc uses ### for sub-headings, don't switch to ####. If it uses backtick code blocks, don't switch to indented blocks
• Minimal disruption: Only touch what needs updating. Unaffected sections should be byte-identical
• Cross-reference integrity: If you rename something, update all links and references to it across the documentation set

---

Scenario 2: Create Documentation from Scratch

When the user requests a documentation file that doesn't exist yet in the target directory:

Step 1: Survey the Codebase (Parallel)

Fire 3-4 explore agents in parallel to understand different aspects:

Agent A — Project structure:

task(subagent_type="explore", run_in_background=true, load_skills=[],
  prompt="[CONTEXT]: The user wants to create a new documentation file: {doc_type} in {target_dir}. No such file exists yet.
[GOAL]: Understand the overall project structure and architecture.
[DOWNSTREAM]: I will use this to create accurate documentation that reflects the real codebase.
[REQUEST]: In {project_root}, identify:
- Top-level directory structure (what's in each major folder)
- Entry points (main files, app initialization, route definitions)
- Key modules/packages and their responsibilities
- Configuration files and their purposes
Return a concise architecture overview.")

Agent B — Existing documentation patterns:

task(subagent_type="explore", run_in_background=true, load_skills=[],
  prompt="[CONTEXT]: Creating {doc_type} in {target_dir}.
[GOAL]: Understand the documentation conventions already in use.
[DOWNSTREAM]: I will match these conventions in the new file.
[REQUEST]: In {target_dir} and nearby documentation directories, find:
- Heading hierarchy patterns (H1/H2/H3 usage)
- Code block conventions (language tags, inline vs block)
- Link/reference patterns
- Any templates or recurring section structures
- Tone and style (formal, casual, tutorial-style, reference-style)
Return a style guide summary.")

Agent C — Feature/component inventory:

task(subagent_type="explore", run_in_background=true, load_skills=[],
  prompt="[CONTEXT]: Creating {doc_type} in {target_dir}.
[GOAL]: List the specific features, APIs, or components that should be documented.
[DOWNSTREAM]: This becomes the content outline for the new doc.
[REQUEST]: For {relevant_code_dirs}, identify all public APIs, exported functions, classes, or features that users would need documented. Include function signatures, parameter types, and brief descriptions of what each does.")

Step 2: Create the Document

Once all agents complete:

1. Synthesize findings into a document outline
2. Create the file using a writing subagent:

task(category="writing", load_skills=[], run_in_background=false,
  prompt="Create the documentation file at {doc_file_path}.

TASK: Write a comprehensive {doc_type} document based on codebase analysis.

EXPECTED OUTCOME: A complete, accurate Markdown documentation file that reflects the actual codebase.

REQUIRED TOOLS: Write

MUST DO:
1. Follow the documentation conventions found in {target_dir} (matching heading levels, code block styles, link patterns, etc.)
2. Document all relevant features/APIs/components identified in the survey
3. Include concrete examples — real function signatures, actual parameter names, working code snippets
4. Use accurate terminology from the codebase (real class names, method names, file paths)
5. Structure logically: overview first, then details; common usage before edge cases
6. Include a table of contents if other docs in this directory do
7. Cross-reference other documentation files in the same directory when relevant

MUST NOT DO:
- Do NOT use placeholder content like 'TODO' or 'Coming soon'
- Do NOT invent API names or function names that don't exist
- Do NOT use generic descriptions like 'this function processes data' when you can be specific
- Do NOT include code examples that wouldn't actually work

CONTEXT:
- Project structure: {from Agent A}
- Documentation conventions: {from Agent B}
- Features/components to document: {from Agent C}
- Target path: {doc_file_path}")

---

Quality Checklist

Before reporting completion, verify:

For Incremental Updates

• All code changes are reflected in documentation
• No sections were accidentally duplicated
• Table of contents matches actual headings (if applicable)
• Code examples in docs match current code APIs
• Cross-references and internal links still valid
• Unaffected sections are unchanged

For New Documentation

• File created at the requested path
• Format matches other docs in the directory
• All public APIs/components are documented
• Code examples are accurate and would actually run
• No placeholder or TODO content remaining
• Content is specific to this codebase, not generic