update-docs

name	update-docs
description	Update all OTGW-firmware documentation in one sequential, backlog-tracked workflow
disable-model-invocation	true

/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:

Changed files match	Subsystem	Docs affected
networkStuff.ino, EthernetESP32.ino	Network	ch06/h06, c4-code-network.md
MQTTstuff.ino, mqttha.cfg	MQTT	ch04/h04, docs/api/MQTT.md, OpenAPI
restAPI.ino	REST API	ch09/h09, docs/api/openapi.yaml, docs/api/README.md
OTGW-Core.ino, OTDirect.ino	OpenTherm core	ch08/h08, c4-code-otgw-core.md
SAT.ino	SAT thermostat	ch05/h05, c4-component-smart-thermostat.md
sensorStuff.ino	Sensors	docs/api/DALLAS_SENSOR_LABELS_API.md
settingStuff.ino, OTGW-firmware.h	Settings/State	ch08/h08, c4-code-settings.md
data/index*.html, data/*.js, data/*.css	Web UI	ch03/h03, c4-code-web-assets.md
platformio.ini, build.py, flash_esp.py	Build system	ch08/h08 (developer guide)
OTGW-firmware.ino	Main/boot	ch01/h01 if feature-level

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:

Chapter	EN file	NL file
1 (Introduction/features)	docs/manuals/en/ch01-introduction.md	docs/manuals/nl/h01-introductie.md
2 (Hardware/install)	docs/manuals/en/ch02-hardware-setup.md	docs/manuals/nl/h02-hardware-installatie.md
3 (Web interface)	docs/manuals/en/ch03-web-interface.md	docs/manuals/nl/h03-webinterface.md
4 (Home Assistant/MQTT)	docs/manuals/en/ch04-home-assistant.md	docs/manuals/nl/h04-home-assistant.md
5 (SAT thermostat)	docs/manuals/en/ch05-sat-thermostat.md	docs/manuals/nl/h05-sat-thermostaat.md
6 (Network)	docs/manuals/en/ch06-network.md	docs/manuals/nl/h06-netwerk.md
7 (Troubleshooting)	docs/manuals/en/ch07-troubleshooting.md	docs/manuals/nl/h07-probleemoplossing.md
8 (Developer guide)	docs/manuals/en/ch08-developer-guide.md	docs/manuals/nl/h08-ontwikkelaarsgids.md
9 (API reference)	docs/manuals/en/ch09-api-reference.md	docs/manuals/nl/h09-api-referentie.md
10 (Appendix)	docs/manuals/en/ch10-appendix.md	docs/manuals/nl/h10-bijlagen.md

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.

3D: Release documents (--release mode only)

Five sub-ACs, executed sequentially in order.

3D-1: Gather changes and contributors. Single subagent.

git log $PREV_TAG..HEAD --oneline | grep -v "CI: update version.h"

Categorize each commit into: new feature, bug fix, internal improvement, breaking change. Scan docs/adr/ for ADRs added or modified since [PREV_TAG]. Pull contributors from three sources sequentially: (1) gh pr list --state merged --search "merged:>[PREV_DATE]" --json author,title --jq '.[] | "\(.author.login): \(.title)"'. (2) Discord #beta-testing (channel 914498730001072149) since [PREV_DATE]. (3) Discord #devs-esp-firmware (channel 924989767966425158). Strip trailing digits from Discord usernames. Exclude bot IDs and maintainer 384411356616720384. Output a structured commit-classification table and contributor list.

3D-2: Generate RELEASE_NOTES_<version>.md at repo root. Single subagent.

Read the template in docs/process/RELEASE_PROCESS.md. Write RELEASE_NOTES_<version>.md with sections: release summary (2-3 sentences), what's new (features grouped by subsystem), bug fixes, breaking changes (always explicit, either "none" or list), upgrade notes, known issues, contributors. Use the categorized commit list from 3D-1. English. No em dashes. No emojis.

3D-3: Generate RELEASE_GITHUB_<version>.md at repo root. Single subagent.

Concise GitHub release body. Sections: short intro (one sentence), highlights (bullet list, max eight items), bug fixes (bullet list), upgrade notes (only if needed), thank you (shoutout to most active contributor, bullet list of others, Discord invite link). English. No em dashes.

3D-4: Update docs/BREAKING_CHANGES.md. Single subagent.

Prepend a new version section to docs/BREAKING_CHANGES.md. Explicitly state whether there are breaking changes for this version: either "None" or a list. Read the existing file first to match its format.

3D-5: Update README.md What's New section. Single subagent.

In README.md: demote the current "What's New in v" section to "What was new in v". Add a new "What's New in v" section with four to six bullet highlights drawn from RELEASE_NOTES_<version>.md.

---

Phase 4: Docs folder cleanup

Inline shell operations, no subagents. Always runs, regardless of mode. Idempotent.

4A: Archive old release notes

If docs/releases/ has more than ten release-note files, move the oldest into docs/releases/archive/, keeping the four newest in place.

ls docs/releases/RELEASE_NOTES_*.md | sort | head -n -4
ls docs/releases/RELEASE_GITHUB_*.md | sort | head -n -4

4B: Move misplaced files

Identify and move release documents from the repo root to docs/releases/:

ls RELEASE_NOTES_*.md RELEASE_GITHUB_*.md GITHUB_RELEASE_*.md 2>/dev/null

Exception: the CURRENT release's documents stay at root during the release phase, then move after publication.

4C: Reviews folder organization

If docs/reviews/ has more than fifteen subdirectories, group those older than ninety days under docs/reviews/archive/<YYYY-Q<N>>/. Preserve the ten most recent as-is.

4D: Verify docs/archive

Check docs/*.md for clearly outdated files (version-specific or superseded) and move them to docs/archive/. BREAKING_CHANGES.md and upgrade-from-*.md always stay at root.

---

Phase 5: Verify, finalize, commit

After all ACs are checked and cleanup is done:

1. git diff --name-only to see what changed.
2. Append a final summary to the backlog task: mcp__backlog__task_edit --final-summary "<one paragraph: areas updated, contributors counted, anything notable>".
3. Flip the task to Done: mcp__backlog__task_complete (preferred) or mcp__backlog__task_edit -s Done.
4. Stage all docs PLUS the task file (the commit-msg hook requires it):

   git add docs/ README.md CHANGELOG.md backlog/tasks/task-<NNN>-*.md
   

5. Commit with the task ID in the message:

   docs: update documentation for changes since <PREV_TAG> (TASK-<NNN>)
   

6. Standalone mode: git push.
7. Release mode: do NOT push. The /release skill commits and pushes everything together.

If git diff --name-only returns empty after Phase 3, skip the commit and report "no documentation changes detected." Still flip the backlog task to Done with the final-summary noting "no changes required."

---

Integration with /release

The /release skill calls this workflow in its Phase 4. When called from /release:

• Pass --release <version> so Phase 3D runs.
• Phase 5 commit is skipped (release skill commits everything together with the version bump).
• The release skill's CHECKPOINT 1 reviews the generated release documents before commit.
• The sequential model still applies in --release mode: Phase 3D is itself five sequential subagents, not a parallel fan-out.

---

Important rules

• Sequential and backlog-tracked. Exactly one subagent at a time. Every doc area is its own AC.
• One task per run. Every standalone /update-docs invocation creates a NEW backlog task; do not reuse a previous task.
• Read before writing. Every subagent must read the current version of a file before updating it.
• Scope discipline. Only update what actually changed. Do not rewrite docs for unchanged subsystems.
• Preserve structure. Keep existing heading levels, table formats, file organization.
• Accuracy over completeness. A correct partial update beats a comprehensive inaccurate one.
• Dutch chapters in Dutch. Technical terms stay English in both files.
• OpenAPI matches implementation. Always verify endpoints against kV2Routes[] in restAPI.ino.
• Commit and push at end of standalone runs. Never leave doc changes uncommitted.
• Release-mode commit is owned by /release. Do not commit from inside /update-docs when invoked from the release skill.