ai-training/.cursor/skills/document/workflows/task.md

# 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

1. Read each task spec — extract the "Files Modified" or "Scope / Included" section to identify which source files were changed
2. Map changed source files to existing module docs in `DOCUMENT_DIR/modules/`
3. Map affected modules to their parent components in `DOCUMENT_DIR/components/`
4. 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.

1. 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).
2. 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.
3. 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/`.
4. Add every such component and module to the update list, even if it was not in the current cycle's task spec.
5. 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)
   ```
6. 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:

1. Read the current source file
2. Read the existing module doc
3. 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
4. Update the module doc in-place, preserving the existing structure and style
5. 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:

1. Read all module docs belonging to this component (including freshly updated ones)
2. Read the existing component doc
3. Update internal interfaces, dependency graphs, implementation details, and caveats sections
4. 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:

1. Update `system-flows.md` — modify affected flow diagrams and data flow tables
2. Update `data_model.md` — if entities changed
3. 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:

1. Update `_docs/00_problem/input_data/data_parameters.md`
2. 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.