---
name: design-docs
metadata:
  version: "0.24.9"
description: Generate or sync the design document, code walkthrough, or requirements doc. Frozen dated pairs tied to a release tag, live current pairs regenerated from the actual code. Uses document-specialist v3.2.2, design-doc-mermaid v1.1.1, plantuml v1.2.2. Use when asked for a design doc, architecture doc, code walkthrough, or requirements doc, and automatically (background agents) at every release.
---

# Design docs and code walkthroughs

Two artifact kinds, four files, one rule: **generated from the actual repo,
never from memory.** The templates live in `references/`; this skill is the
procedure around them.

## Companion skills (required)

When this skill writes an architecture doc, a code walkthrough, or a requirements doc, invoke the
Spillwave documentation suite. Install from
`SpillwaveSolutions/spillwave-documentation-marketplace` **v0.2.1**.
Load `references/companion-skills.md` before either prompt.

| Role | Skill | Version | Rule |
|------|--------|---------|------|
| Prose | `document-specialist` | v3.2.2 | Default voice is STE100. Switch to `google-docs-style` v1.1.4 only when the user names Google style. Never mix packs. Wireframes belong in this skill's diagram pass. |
| GitHub-safe diagrams | `design-doc-mermaid` | v1.1.1 | Default for flowchart, sequence, class, ER, state, C4, and component views. Fenced `mermaid` in the Markdown. Validate before publish. |
| Leftover UML and wireframes | `plantuml` | v1.2.2 | Use case, timing, ArchiMate, Salt wireframes, nwdiag, WBS. Always render PNG or SVG. GitHub wiki does not render PlantUML source. |

Hard bans for prose in both voice packs:

- No em dash.
- Do not start a sentence with So, That, Thus, or Hence.

## Artifacts

| File | Kind | Rule |
|---|---|---|
| `docs/designs/<DATE>_<NAME>_design_doc.md` | dated | frozen. Publish once, never regenerate (same rule as roadmap snapshots) |
| `docs/designs/<DATE>_<NAME>_code_walkthrough.md` | dated | frozen. Same |
| `docs/designs/current_design_doc.md` | live | regenerated each release; in-place rewrite is sanctioned (like `docs/roadmap.md`) |
| `docs/designs/current_code_walkthrough.md` | live | same |
| `docs/requirements/<NAME>_srs.md` or `_prd.md` | ad-hoc | generated on request from `requirements-doc-prompt.md`. Register with `worklog wiki-add`. |

`<NAME>` at release time is `vX.Y.Z-release` (matches roadmap-snapshot
naming). Ad-hoc names are fine mid-cycle.

## Frontmatter: how a reader knows what they are looking at

Dated files:

    ---
    wiki_key: design/<date>_<name>-design-doc   # or -code-walkthrough
    doc_type: design
    truth_state: snapshot
    date: YYYY-MM-DD
    name: vX.Y.Z-release
    tag: vX.Y.Z
    git_hash: <full sha the doc was generated against>
    branch: <branch at generation>
    roadmap_snapshot: docs/roadmap/<date>_<name>.md
    ---

Current files: same minus `date`/`name`/`roadmap_snapshot`, plus
`generated_at: <UTC ISO date-time>` and `roadmap: docs/roadmap.md`, with
`wiki_key: design/current-design-doc` (or `-code-walkthrough`) and
`truth_state: current`. `tag` is
the latest release tag at generation. Stamp from `git rev-parse HEAD`,
`git branch --show-current`, `git describe --tags --abbrev=0`. Never guess.
The identity trio (`wiki_key`, `doc_type`, `truth_state`) is required by the
IA gates (plan ia-content-model §5.4). Regenerating without it trips
`worklog ia-normalize --check`.

## 1. Read the config

`release.sync_docs` in `.work/config.yml` lists what regenerates at release
(`design-doc`, `code-walkthrough`, `user-guide`, `readme`). Absent list =
defaults all on. This skill owns the first two entries; the release skill
routes the other two to the user-docs refresh agent.

## 2. Generate

Load `references/companion-skills.md`, then run
`references/design-doc-prompt.md` (architecture / design),
`references/code-walkthrough-prompt.md` (walkthrough), or
`references/requirements-doc-prompt.md` (SRS / PRD)
against the repository at HEAD. The template's own rules govern content.

Sections are a menu. Omissions are listed with reasons. Every code claim
cites `path, function(), lines N-M`. Fill System Context and Source Material
from the repo itself: README, docs/worklog-spec.md,
docs/plans/, docs/adr/, `.work/config.yml`, the test suites.

## 2b. Verify before you report done. Not optional

Run `bin/worklog doc-verify` and fix every **FABRICATED** finding in the
files you just wrote, then re-run until they are gone. Do this before
publishing and before reporting completion.

This is the step whose absence caused #294. Line citations were checked by
nobody, and a measured **12 of 26 were wrong**, pointing at offsets from
several releases earlier. Every one was written by an agent that had the
file open and copied the previous edition's number forward. One wrong claim
was even introduced while hand-fixing the previous wrong claim, which is
what a regeneration without a check does: it moves the error rather than
removing it.

Reading the verdicts:

- **FABRICATED**: the citation is wrong at the commit you generated
  against. Your bug, in the file you just wrote. Fix it.
- **DRIFT**: right when written, moved since. Expected in the frozen dated
  copies; in a `current_*` file it means you cited an older tree than the
  one you generated against, so treat it as yours too.
- **UNSTAMPED / UNRESOLVABLE**: no `git_hash`, or a commit not in this
  clone (see ADR-0008). Report it; never re-check against HEAD.

Do not hand-edit a frozen dated copy to silence a finding. Frozen means
frozen: the correction belongs in the next edition, and the current pair
should say so in prose where a reader would be misled.

## 3. Modes

- **Release mode** (invoked by the release skill after the tag exists):
  regenerate both `current_*` files against the tagged commit, then copy
  each to its dated frozen name with the dated frontmatter. Four files out.
- **Sync mode** (ad-hoc, "update the design doc"): regenerate `current_*`
  only. A dated freeze happens only when explicitly asked.

## 4. Publish

wiki-publish, standard ledger flow (`.work/published.json`):
- `design/current-design-doc` to page `Design-Doc` (live: republish on
  source-hash change), `design/current-code-walkthrough` to `Code-Walkthrough`.
- Dated files to `Design-Doc-<date>_<name>` / `Code-Walkthrough-<date>_<name>`
  (frozen: publish once), linked from Home next to the roadmap snapshots.

## 5. Execution rule: always a background subagent

Generation reads the whole repo. It never blocks the main thread or a
release. Same non-blocking pattern as viz and plan-publish: spawn the agent,
fold the result in when it reports. At release time the release skill spawns
this; the tag never waits for prose.