Update Docs

/update-docs : Documentation Update Workflow

Update all project documentation in one well-tracked sequential pass. Can be invoked standalone or as part of a release.

Why sequential and backlog-tracked

This workflow used to spawn one subagent per affected manual chapter in parallel. Fast in theory, but on releases that touched four or more chapters it tripped Claude API concurrency limits and the run failed mid-flight. The new model has two properties:

• Exactly one subagent runs at a time. Slower wall-clock, no rate-limit hits, and a deterministic order of operations.
• Every doc area is an AC on a single backlog task. The run is replayable from the task on its own; progress is visible in mcp__backlog__task_view while the workflow runs in the background; partial failures leave a clear breadcrumb trail.

Usage

/update-docs                       # Standalone: scope from git changes
/update-docs --release 2.0.1       # Release mode: also generate release documents
/update-docs --scope full          # Force-update all docs regardless of git diff

Writing style rules

• Never use em dashes. Use colons, periods, commas, or parentheses.
• All release documents in English (international audience).
• Manual chapters: English version always, Dutch version always.
• No emojis in technical documentation.
• Concise and correct over long and impressive.

Phase 1: Scope detection

Determine what changed since the last release and which documentation is affected.

PREV_TAG=$(gh release view --json tagName --jq '.tagName' 2>/dev/null || git describe --tags --abbrev=0)
git diff --name-only $PREV_TAG..HEAD

Categorize using this mapping:

If --scope full or six or more subsystems changed, treat all docs as affected.

Output of Phase 1: an ordered list of affected doc areas, the PREV_TAG hash, and a categorized commit summary. Pass this to Phase 2 verbatim. Do NOT wait for user confirmation in standalone mode.

Phase 2: Plan as a backlog task

Before any documentation is written, capture the run as one backlog task.

Create the task via mcp__backlog__task_create:

• title: docs: update for changes since <PREV_TAG> (in --release mode add the version: docs: update for v<version> (changes since <PREV_TAG>))
• status: In Progress
• assignee: ["@claude"]
• labels: ["docs", "update-docs"] (add "release" in --release mode)
• description: paste the Phase 1 output verbatim (PREV_TAG, categorized commits, list of affected areas)
• acceptanceCriteria: one entry per affected doc area, in execution order:
  1. Manual chapter <N> (<EN file>, <NL file>) updated (one AC per affected chapter)
  2. API documentation (openapi.yaml, README.md, MQTT.md, ...) updated (only if API changed)
  3. C4 architecture docs (<files>) updated (only if structural change)
  4. Cleanup phase complete (archive old releases, move misplaced files, reorg reviews)
  5. (--release only) Release documents generated (RELEASE_NOTES, RELEASE_GITHUB, BREAKING_CHANGES, README What's New)

Record the assigned TASK-NNN ID returned by task_create. Phase 5's commit message uses it; the commit-msg hook will block the commit if the task file is not staged.

Phase 3: Sequential execution

Exactly one subagent runs at a time. When it finishes, update the backlog task and start the next.

For each AC in order:

1. Spawn ONE subagent in the background (run_in_background=true) with the relevant prompt template (3A / 3B / 3C / 3D below).
2. Wait for the completion notification. Do not spawn the next subagent before this notification arrives.
3. Read the agent's summary. If it reports errors, mcp__backlog__task_edit --append-notes with the failure detail and either retry once with a corrected prompt or escalate to the user.
4. On success: mcp__backlog__task_edit --check-ac <N> to tick the AC, and --append-notes with a one-line summary of what was changed.
5. Move to the next AC.

3A: Manual chapter subagent

Used for each affected manual chapter. One subagent per chapter, sequential.

Chapter mapping:

Prompt template:

Read the current [EN file] and [NL file]. Read the git diff for the relevant source files: git diff [PREV_TAG]..HEAD -- [source files]. Update both files to reflect the changes accurately. Preserve all existing content that is still correct. The EN file must be in English, the NL file must be in Dutch. Technical terms stay in English in both. Keep the same ## Chapter N: / ## Hoofdstuk N: heading format. Write the updated files back. Report which sections you changed and why; flag any change that needed an architectural decision rather than a doc edit.

3B: API documentation subagent

Single subagent, only if REST or MQTT changed.

Files in scope: docs/api/openapi.yaml, docs/api/README.md, docs/api/MQTT.md, docs/api/WEBSOCKET_FLOW.md (only if WebSocket changed), docs/api/DALLAS_SENSOR_LABELS_API.md (only if Dallas API changed).

Prompt template:

Read the current docs in docs/api/. Read the git diff: git diff [PREV_TAG]..HEAD -- restAPI.ino MQTTstuff.ino. Update the affected API docs to match the current implementation. For openapi.yaml: ensure every endpoint present in kV2Routes[] in restAPI.ino has a spec entry. Add new endpoints, remove removed ones, update changed response schemas. For MQTT.md: verify topic paths and payload formats match the current MQTTstuff.ino publish calls. Report endpoints added, removed, and changed.

3C: C4 architecture docs subagent

Single subagent, only if a new .ino file was added or three or more .ino files changed.

Prompt template:

Read the current docs/c4/c4-code-*.md and docs/c4/c4-component-*.md files affected by the changes in git diff [PREV_TAG]..HEAD -- src/OTGW-firmware/*.ino. Targeted updates only, no rewrites from scratch. Preserve the existing C4 structure (Code level documents per source area, Component level per logical group). Report which sections were touched.