Document Skill — Task Mode Workflow

Lightweight, incremental documentation update triggered by task spec files. Updates only the docs affected by implemented tasks — does NOT redo full discovery, verification, or problem extraction.

Trigger

User provides one or more task spec files (e.g., @_docs/02_tasks/done/AZ-173_*.md)
AND _docs/02_document/ already contains module/component docs

Accepts

One or more task spec files from _docs/02_tasks/todo/ or _docs/02_tasks/done/.

Steps

Task Step 0: Scope Analysis

Read each task spec — extract the "Files Modified" or "Scope / Included" section to identify which source files were changed
Map changed source files to existing module docs in DOCUMENT_DIR/modules/
Map affected modules to their parent components in DOCUMENT_DIR/components/
Identify which higher-level docs might be affected (system-flows, data_model, data_parameters)

Output: a list of docs to update, organized by level:

Module docs (direct matches)
Component docs (parents of affected modules)
System-level docs (only if the task changed API endpoints, data models, or external integrations)
Problem-level docs (only if the task changed input parameters, acceptance criteria, or restrictions)

Task Step 0.5: Import-Graph Ripple

A module that changed may be imported by other modules whose docs are now stale even though those other modules themselves were not directly edited. Compute the reverse-dependency set and fold it into the update list.

For each source file in the set of changed files from Step 0, build its module-level identifier (Python module path, C# namespace, Rust module path, TS import-specifier, Go package path — depending on the project language).
Search the codebase for files that import from any of those identifiers. Preferred tooling per language:
- Python: rg -e "^(from|import) <module>" then parse with ast to confirm actual symbol use.
- TypeScript / JavaScript: rg "from ['\"].*<path>" then resolve via tsconfig.json paths / jsconfig.json if present.
- C#: rg "^using <namespace>" plus .csproj ProjectReference graph.
- Rust: rg "use <crate>::" plus Cargo.toml workspace members.
- Go: rg "\"<module-path>\"" plus go.mod requires.
If a static analyzer is available for the project (e.g., pydeps, madge, depcruise, NDepend, cargo modules, go list -deps), prefer its output — it is more reliable than regex.
For each importing file found, look up the component it belongs to via _docs/02_document/module-layout.md (if present) or by directory match against DOCUMENT_DIR/components/.
Add every such component and module to the update list, even if it was not in the current cycle's task spec.
Produce _docs/02_document/ripple_log_cycle<N>.md (where <N> is state.cycle from _docs/_autodev_state.md, default 1) listing each downstream doc that was added to the refresh set and the reason (which changed file triggered it). Example line:
```
- docs/components/02_ingestor.md — refreshed because src/ingestor/queue.py imports src/shared/serializer.py (changed by AZ-173)
```
When parsing imports fails (missing tooling, unsupported language), log the parse failure in the ripple log and fall back to a directory-proximity heuristic: any component whose source directory contains files matching the changed-file basenames. Note: heuristic mode is explicitly marked in the log so the user can request a manual pass.

Task Step 1: Module Doc Updates

For each affected module:

Read the current source file
Read the existing module doc
Diff the module doc against current code — identify:
- New functions/methods/classes not in the doc
- Removed functions/methods/classes still in the doc
- Changed signatures or behavior
- New/removed dependencies
- New/removed external integrations
Update the module doc in-place, preserving the existing structure and style
If a module is entirely new (no existing doc), create a new module doc following the standard template from workflows/full.md Step 1

Task Step 2: Component Doc Updates

For each affected component:

Read all module docs belonging to this component (including freshly updated ones)
Read the existing component doc
Update internal interfaces, dependency graphs, implementation details, and caveats sections
Do NOT change the component's purpose, pattern, or high-level overview unless the task fundamentally changed it

Task Step 3: System-Level Doc Updates (conditional)

Only if the task changed API endpoints, system flows, data models, or external integrations:

Update system-flows.md — modify affected flow diagrams and data flow tables
Update data_model.md — if entities changed
Update architecture.md — only if new external integrations or architectural patterns were added

Task Step 4: Problem-Level Doc Updates (conditional)

Only if the task changed API input parameters, configuration, or acceptance criteria:

Update _docs/00_problem/input_data/data_parameters.md
Update _docs/00_problem/acceptance_criteria.md — if new testable criteria emerged

Task Step 5: Summary

Present a summary of all docs updated:

══════════════════════════════════════
 DOCUMENTATION UPDATE COMPLETE
══════════════════════════════════════
 Task(s): [task IDs]
 Module docs updated: [count]
 Component docs updated: [count]
 System-level docs updated: [list or "none"]
 Problem-level docs updated: [list or "none"]
 Ripple-refreshed docs (imports changed indirectly): [count, see ripple_log_cycle<N>.md]
══════════════════════════════════════

Principles

Minimal changes: only update what the task actually changed. Do not rewrite unaffected sections.
Preserve style: match the existing doc's structure, tone, and level of detail.
Verify against code: for every entity added or changed in a doc, confirm it exists in the current source.
New modules: if the task introduced an entirely new source file, create a new module doc from the standard template.
Dead references: if the task removed code, remove the corresponding doc entries. Do not keep stale references.

6.4 KiB Raw Blame History