From c18a5e3bbfa7f11a6b13f8368cdc5f5c2e45b582 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Thu, 24 Sep 2026 14:08:12 -0400 Subject: [PATCH] feat(whiteboard): add docs write-back mode --- development/.codex-plugin/plugin.json | 3 +- development/AGENTS.md | 5 +- development/README.md | 34 ++--- development/skills/whiteboard/SKILL.md | 48 ++++++- .../skills/whiteboard/references/docs.md | 136 ++++++++++++++++++ .../skills/whiteboard/references/templates.md | 8 +- skills/whiteboard/SKILL.md | 48 ++++++- skills/whiteboard/references/docs.md | 136 ++++++++++++++++++ skills/whiteboard/references/templates.md | 8 +- 9 files changed, 393 insertions(+), 33 deletions(-) create mode 100644 development/skills/whiteboard/references/docs.md create mode 100644 skills/whiteboard/references/docs.md diff --git a/development/.codex-plugin/plugin.json b/development/.codex-plugin/plugin.json index ed429e8..1ff7c0c 100644 --- a/development/.codex-plugin/plugin.json +++ b/development/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "development", - "version": "0.0.8", + "version": "0.0.9", "description": "Developer workflow skills for agent context, PR fixups, CLI design, codebase-grounded landing copy, architecture mapping and whiteboard defense, OSS readiness, OSS marketing, session log audits, bug verification, decision records, and GitHub Actions self-hosted runners.", "author": { "name": "Mark Phelps" @@ -63,6 +63,7 @@ "Design commands, flags, help text, and output behavior for a new command-line tool.", "Map this codebase into a layered architecture overview.", "Quiz me whiteboard-defense style on this system's flows, trade-offs, and failure modes.", + "Turn this codebase map into doc and comment fixes on a branch.", "Write landing-page copy for this product using only capabilities proven by its codebase.", "Fact-check this product pitch against the code that actually ships and provide an evidence table.", "Audit this repo for open source readiness and first-contributor friction.", diff --git a/development/AGENTS.md b/development/AGENTS.md index 5daf938..9a70591 100644 --- a/development/AGENTS.md +++ b/development/AGENTS.md @@ -54,8 +54,9 @@ agent context. the numbered phases in order and meet each gate. Treat what the user suspects as a hypothesis to test, not as a finding. - For whiteboard maps, never invent design rationale. Tag rationale claims with - evidence, keep defense records local under `.map/`, and never modify source - code while mapping or defending. + evidence, keep defense records local under `.map/`, and never modify the + working tree. `/whiteboard docs` writes only to a worktree branch, keeps + source edits to a comments-only commit, and pushes only on confirmation. - For bug verification, never touch the working tree (repros run only in a `git worktree` under `.verify/`), never fix code or open issues, and post verdicts to GitHub only after the user confirms each post. diff --git a/development/README.md b/development/README.md index e3a8c6b..5bc60f2 100644 --- a/development/README.md +++ b/development/README.md @@ -8,19 +8,19 @@ Actions self-hosted runners. ## Skill Set -| Skill | What It Does | When to Invoke | -| --------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| `cli-design` | Designs and reviews command-line interfaces using clig.dev guidance. | When creating CLI commands, flags, help text, output contracts, error messages, or destructive workflows. | -| `codebase-landing-copy` | Writes product landing-page copy grounded in shipped code and an evidence ledger. | When writing or fact-checking landing pages, homepages, product pitches, hero copy, or store listings for a repo-backed product. | -| `context-file-tuneup` | Audits, rewrites, and tightens `CLAUDE.md` / `AGENTS.md` context files. | When reviewing, shrinking, restructuring, or improving agent context. | -| `decision-records` | Writes and maintains decision and plan records (ADRs) and their registry table, preserving history. | When recording an architecture, product, design, or dependency decision, amending or superseding a record, or starting a records directory. | -| `github-pr-fixup` | Addresses unresolved GitHub PR review comments and failing CI on the existing source branch. | When a user gives you an existing PR URL and wants review feedback or CI failures fixed without a new PR. | -| `github-self-hosted-runner` | Installs, registers, verifies, or removes namespaced GitHub Actions self-hosted runners on a Linux host. | When a user gives a repository or organization URL and wants a persistent runner managed by systemd. | -| `whiteboard` | Maps architecture and design rationale, then runs whiteboard-defense quizzes. | When the user explicitly invokes `/whiteboard` to map a codebase, explore a region, refresh a map, or defend their understanding. | -| `verify-bug` | Rules on whether claimed bugs are real via an isolated Prover/Skeptic/Referee hearing. | When the user asks whether a bug is real, wants findings or review comments verified, or points at suspected bugs from a map. | -| `oss-marketing` | Sharpens README and public-doc positioning for first-time visitors. | When a repo needs launch copy, clearer positioning, or a README that explains what the project is. | -| `oss-repo-readiness` | Audits and prepares a repo for open source release, focused on developer experience. | When making a repo public, writing CONTRIBUTING or issue templates, or running a pre-launch checklist. | -| `session-log-audit` | Mines local agent session logs for papercuts and produces a ranked fix list. | When the user wants to know what is annoying about their own tool, or why they work around it. | +| Skill | What It Does | When to Invoke | +| --------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `cli-design` | Designs and reviews command-line interfaces using clig.dev guidance. | When creating CLI commands, flags, help text, output contracts, error messages, or destructive workflows. | +| `codebase-landing-copy` | Writes product landing-page copy grounded in shipped code and an evidence ledger. | When writing or fact-checking landing pages, homepages, product pitches, hero copy, or store listings for a repo-backed product. | +| `context-file-tuneup` | Audits, rewrites, and tightens `CLAUDE.md` / `AGENTS.md` context files. | When reviewing, shrinking, restructuring, or improving agent context. | +| `decision-records` | Writes and maintains decision and plan records (ADRs) and their registry table, preserving history. | When recording an architecture, product, design, or dependency decision, amending or superseding a record, or starting a records directory. | +| `github-pr-fixup` | Addresses unresolved GitHub PR review comments and failing CI on the existing source branch. | When a user gives you an existing PR URL and wants review feedback or CI failures fixed without a new PR. | +| `github-self-hosted-runner` | Installs, registers, verifies, or removes namespaced GitHub Actions self-hosted runners on a Linux host. | When a user gives a repository or organization URL and wants a persistent runner managed by systemd. | +| `whiteboard` | Maps architecture and design rationale, then runs whiteboard-defense quizzes. | When the user explicitly invokes `/whiteboard` to map a codebase, explore a region, refresh a map, defend their understanding, or write fixes back to the repo's docs. | +| `verify-bug` | Rules on whether claimed bugs are real via an isolated Prover/Skeptic/Referee hearing. | When the user asks whether a bug is real, wants findings or review comments verified, or points at suspected bugs from a map. | +| `oss-marketing` | Sharpens README and public-doc positioning for first-time visitors. | When a repo needs launch copy, clearer positioning, or a README that explains what the project is. | +| `oss-repo-readiness` | Audits and prepares a repo for open source release, focused on developer experience. | When making a repo public, writing CONTRIBUTING or issue templates, or running a pre-launch checklist. | +| `session-log-audit` | Mines local agent session logs for papercuts and produces a ranked fix list. | When the user wants to know what is annoying about their own tool, or why they work around it. | ## Notes @@ -38,9 +38,11 @@ Actions self-hosted runners. of opening a new PR. - OSS readiness and OSS marketing are separate concerns. Readiness covers contribution mechanics; marketing covers first-visit clarity and conversion. -- Whiteboard is explicit-invocation only, never modifies source code, and keeps - personal defense records under `.map/` while committed maps live under - `docs/map/`. +- Whiteboard is explicit-invocation only, never modifies the working tree, and + keeps personal defense records under `.map/` while committed maps live under + `docs/map/`. Its `docs` mode proposes doc and comment fixes on a separate + branch; source files change only in a comments-only commit, and nothing is + pushed without confirmation. - Whiteboard logs `suspected-bug` leads without investigating them; `verify-bug` rules on them. Neither skill depends on the other. - Bug verification never modifies the working tree. Repro tests run only in a diff --git a/development/skills/whiteboard/SKILL.md b/development/skills/whiteboard/SKILL.md index df9c2b5..2448a91 100644 --- a/development/skills/whiteboard/SKILL.md +++ b/development/skills/whiteboard/SKILL.md @@ -27,10 +27,13 @@ The skill has two halves that feed each other: ## Hard rules -- **Never modify source code.** The only files this skill writes are under - `docs/map/` (or the repo's existing docs location, see below) and `.map/`. - Cleanup ideas go in the friction log, not in edits. Understanding comes first; - changing code mid-map corrupts the thing being mapped. +- **Never modify the working tree.** While mapping, refreshing, or defending, + the only files this skill writes are under `docs/map/` (or the repo's existing + docs location, see below) and `.map/`. Cleanup ideas go in the friction log, + not in edits; changing code mid-map corrupts the thing being mapped. The one + exception is `/whiteboard docs`, which writes to a separate branch in a + `git worktree`, and changes source files only in a comments-only commit that + passes the comment check (see `references/docs.md`). - **Never invent rationale.** Every claim about why something is the way it is carries an evidence tag. If there is no evidence, say so and log it as an open question. A fabricated "why" is worse than a missing one, because the defense @@ -49,6 +52,7 @@ Parse the argument after `/whiteboard`: | `/whiteboard zoom ` | Map one region in depth; works even with no overview yet | | `/whiteboard defend [reg]` | Run a defense session; no region means pick one (see defense) | | `/whiteboard refresh` | Check every mapped region for staleness and remap what changed | +| `/whiteboard docs` | Propose repo doc and comment fixes from the map, on a branch | A `` can be an existing region slug, a name from the Unexplored list, or a plain description ("the sync engine", "auth"). Resolve descriptions to paths @@ -64,7 +68,8 @@ writing. `mapped_at` is no longer an ancestor of HEAD (rebased or force-pushed history), which makes the region stale by definition. 3. Read `.map/defense/*.md` for pass status. -4. Report in chat, compactly: regions with staleness counts and pass status, the +4. Resolve any `proposed: ` friction entries (see "Docs write-back"). +5. Report in chat, compactly: regions with staleness counts and pass status, the Unexplored list, and one recommended next step with a one-line reason. Example: "Sync engine is 38 commits stale; refresh it before defending." Report pass status only in chat, never in a committed file. @@ -192,7 +197,9 @@ Each entry is typed: | ----------------- | ------------------------------------------------------------------ | ---------------- | | `unexplained` | A significant decision with no recorded why | scout, zoom | | `confusing` | Misleading names, surprising indirection, comment contradicts code | zoom | -| `inconsistent` | Two patterns doing the same job; docs disagree with code | scout | +| `inconsistent` | Two patterns doing the same job | scout | +| `stale-doc` | A doc claim (README, docs, AGENTS.md) contradicts the code | scout, zoom | +| `undocumented` | A region or entry point that no doc covers | scout, zoom | | `cleanup` | Dead code, abandoned dependency, ancient TODO | any | | `suspected-bug` | A concrete scenario where the code looks wrong or unhandled | zoom, defense | | `defense-exposed` | The user missed a question because the code misled them | defense | @@ -232,12 +239,41 @@ Large or structural changes: remap the region. Either way: - Keep `[stated]` evidence unless the change contradicts it; if it does, move it to friction as `inconsistent` and flag it for the user. +- Resolve `proposed: ` entries the same way the bare command does. - Re-derive the region's core questions (see `references/defense.md`); keep pass status for any question whose underlying decision didn't change. - If `paths` no longer match anything, the region was moved or deleted; find where it went via `git log --follow` or rename detection, and ask before rewriting the boundary. +## Docs write-back (`docs`) + +Carry what the map learned back into the repo's own docs. Read +`references/docs.md` before starting; it covers inputs, targets, the comment +check, content rules, and the PR. In short: + +1. **Check whether the map is shared:** `git ls-files docs/map` on the target + branch and `git check-ignore docs/map`. If it isn't tracked, ask once whether + to include the map in this PR or write self-contained docs, and record the + answer in `.map/scout.md`. +2. **Propose** every candidate change in chat, grouped by target file, each with + a one-line summary and its source map entry. The user picks what to include. + Nothing is written before that. +3. **Write** the selected changes in a `git worktree` on a new branch, as two + commits: docs first, then comments. The comments commit must pass the comment + check. +4. **Push and open a PR only on an explicit yes**, after showing the diff stat. +5. **Mark** each included friction entry `proposed: ` in the map. + +When a later `/whiteboard` or `refresh` finds a proposed change reachable from +HEAD, remove the entry and upgrade its evidence: `[stated]` rationale and +answered `unexplained` decisions become `[documented: ]`. If the branch is +gone and the change never landed, reopen the entry. + +Rationale that belongs in decision records is handed off by wording: tell the +user these are candidates for decision records (ADRs). If they'd rather not, it +goes into the repo's existing design-docs location instead. + ## Defense phase Read `references/defense.md` before starting a session. It covers question diff --git a/development/skills/whiteboard/references/docs.md b/development/skills/whiteboard/references/docs.md new file mode 100644 index 0000000..8880410 --- /dev/null +++ b/development/skills/whiteboard/references/docs.md @@ -0,0 +1,136 @@ +# Docs write-back + +`/whiteboard docs` turns what the map learned into a reviewable branch of doc +and comment fixes. The user's working tree is never touched, nothing is written +before the user picks changes, and nothing is pushed without an explicit yes. + +## Contents + +- Inputs and targets +- Is the map shared? +- The proposal +- The branch and the comment check +- Content rules +- The PR +- After the PR + +## Inputs and targets + +| Map input | Usual target | +| --------------------------------------------- | ---------------------------------------------------------- | +| `stale-doc` | The doc that makes the claim, corrected in place | +| `undocumented` | README, ARCHITECTURE.md, CONTRIBUTING, or `docs/` | +| `confusing` (misleading comment or name) | The comment or docstring at the receipt | +| `refuted` suspected bug | A comment at the line that looks wrong, explaining why not | +| `[stated]` rationale, `unexplained` decisions | Decision records (ADRs), handed off by wording | +| The map itself, when shared | A pointer in AGENTS.md / CLAUDE.md | + +Follow the repo's conventions over these defaults: if it already maintains +`docs/architecture.md` or a design-docs folder, update that rather than adding a +parallel file. + +Never propose renaming code, even for a `confusing` name. That's a code change; +leave it in the friction log. + +## Is the map shared? + +Check on the branch the write-back targets (usually the default branch): + +- `git ls-files docs/map` lists files → **shared**. +- Otherwise, or if `git check-ignore docs/map` matches → **not shared**. + +If not shared and `.map/scout.md` has no recorded choice, ask once: + +> The map isn't tracked in this repo. Include `docs/map/` in this PR, or write +> self-contained docs that don't link to it? + +Record the answer in `.map/scout.md`. "Include" adds the map to the docs commit +and then treats it as shared. + +## The proposal + +List every candidate change in chat, grouped by target file: + +```text +README.md + 1. Fix: says config is YAML-only; TOML is also supported (stale-doc, config.md) + 2. Add: short "How it's built" section linking to the map (undocumented, index) +internal/sync/engine.go [comment] + 3. Explain why the double-check isn't a race (refuted, sync-engine) +AGENTS.md + 4. Add pointer to docs/map/ for architecture (map shared) +``` + +Then the handoff line if ADR-shaped items exist. Wait for the user to pick ("all +but 3", "only README"). Don't write anything until they do. + +## The branch and the comment check + +1. Create the branch from the target branch (usually the default branch), not + from whatever is checked out: + `git worktree add -b docs/whiteboard- .map/worktrees/docs `. + `.map/` is already excluded, so the worktree stays out of the tracked tree. +2. **Commit 1, docs:** doc files only (and `docs/map/` if the user chose to + include it). +3. **Commit 2, comments:** source-file comment and docstring changes only. + Before committing, run `git diff --cached -U0` and inspect every changed + line. Reject the commit if any added or removed line is not entirely a + comment or docstring in that file's language, including whitespace-only code + changes. Fix the offending hunk and check again; if it can't be made + comment-only, drop that change and tell the user. +4. Remove the worktree after pushing or when the user declines to push; the + branch stays. + +Skip commit 2 when no comment changes were selected. + +## Content rules + +**Stale claims:** correct them in place, matching the surrounding voice and +length. Don't rewrite the section around them. + +**Missing docs, map shared:** a few sentences that rarely go stale (what the +system is, its major parts, where to go next), plus a link to the relevant map +region for depth. The map stays the single deep source because it's the one with +staleness detection. Add a one-line pointer in AGENTS.md / CLAUDE.md so future +agents start from the map. + +**Missing docs, map not shared:** self-contained sections with no links to +`docs/map/` and no AGENTS.md pointer. Write them fuller, since they're the only +copy anyone else will see, but keep to what the map has evidence for. + +**Comments:** explain why, not what, and only where the map has evidence. A +refuted-bug comment names the protection: "Safe without a lock: `Run` is only +called from the single scheduler goroutine (scheduler.go:42)." + +**Decisions:** ADR-shaped items are offered to the user as candidates for +decision records (ADRs). If the user wants them in this branch instead, add them +to the repo's existing design-docs location, or a single +`docs/design-decisions.md` if there is none: one short entry per decision (what +was chosen, over what, why), with its evidence. + +**Everywhere:** only write claims backed by the map's evidence. `[inferred]` +rationale never goes into repo docs. + +## The PR + +After committing, show the diff stat and ask whether to push and open a PR. Only +on a clear yes, push the branch and open the PR with: + +- a one-paragraph summary, +- a table of changes, each with its evidence: code receipts and commit SHAs, + never map paths, so reviewers can check claims against the code without + trusting the map, +- a note that the comments commit is comment-only and can be dropped + independently. + +## After the PR + +Append `proposed: ` to each included friction entry in the map (and note +the branch in `.map/scout.md`). On the next `/whiteboard` or `refresh`: + +- **Change reachable from HEAD** (`git merge-base --is-ancestor`, or the + corrected text is present at HEAD after a squash merge): remove the entry, and + upgrade the evidence of any rationale it carried to `[documented: ]`. +- **Branch gone and change not present:** remove the `proposed:` marker so the + entry is open again. +- **Branch still open:** leave it. diff --git a/development/skills/whiteboard/references/templates.md b/development/skills/whiteboard/references/templates.md index 59374df..2589c97 100644 --- a/development/skills/whiteboard/references/templates.md +++ b/development/skills/whiteboard/references/templates.md @@ -113,11 +113,15 @@ If a scenario looks unhandled, also log it as a `suspected-bug` below. - `` (``) - `suspected-bug` (``) — verdict: unverified +- `stale-doc` says ; code does (``) A verification pass may later replace `unverified` with `confirmed: `, `refuted: `, or `unclear: `. Preserve whatever verdict is there when refreshing. +`/whiteboard docs` appends `proposed: ` to entries it includes in a +write-back branch; the entry is removed once the change reaches HEAD. + ## Zoom candidates - **** (``): @@ -132,7 +136,9 @@ directory. ```markdown # Scout notes -Map location: docs/map/ (or the chosen alternative, and why) +- Map location: docs/map/ (or the chosen alternative, and why) +- Docs write-back: , chosen + ## Evidence sources diff --git a/skills/whiteboard/SKILL.md b/skills/whiteboard/SKILL.md index df9c2b5..2448a91 100644 --- a/skills/whiteboard/SKILL.md +++ b/skills/whiteboard/SKILL.md @@ -27,10 +27,13 @@ The skill has two halves that feed each other: ## Hard rules -- **Never modify source code.** The only files this skill writes are under - `docs/map/` (or the repo's existing docs location, see below) and `.map/`. - Cleanup ideas go in the friction log, not in edits. Understanding comes first; - changing code mid-map corrupts the thing being mapped. +- **Never modify the working tree.** While mapping, refreshing, or defending, + the only files this skill writes are under `docs/map/` (or the repo's existing + docs location, see below) and `.map/`. Cleanup ideas go in the friction log, + not in edits; changing code mid-map corrupts the thing being mapped. The one + exception is `/whiteboard docs`, which writes to a separate branch in a + `git worktree`, and changes source files only in a comments-only commit that + passes the comment check (see `references/docs.md`). - **Never invent rationale.** Every claim about why something is the way it is carries an evidence tag. If there is no evidence, say so and log it as an open question. A fabricated "why" is worse than a missing one, because the defense @@ -49,6 +52,7 @@ Parse the argument after `/whiteboard`: | `/whiteboard zoom ` | Map one region in depth; works even with no overview yet | | `/whiteboard defend [reg]` | Run a defense session; no region means pick one (see defense) | | `/whiteboard refresh` | Check every mapped region for staleness and remap what changed | +| `/whiteboard docs` | Propose repo doc and comment fixes from the map, on a branch | A `` can be an existing region slug, a name from the Unexplored list, or a plain description ("the sync engine", "auth"). Resolve descriptions to paths @@ -64,7 +68,8 @@ writing. `mapped_at` is no longer an ancestor of HEAD (rebased or force-pushed history), which makes the region stale by definition. 3. Read `.map/defense/*.md` for pass status. -4. Report in chat, compactly: regions with staleness counts and pass status, the +4. Resolve any `proposed: ` friction entries (see "Docs write-back"). +5. Report in chat, compactly: regions with staleness counts and pass status, the Unexplored list, and one recommended next step with a one-line reason. Example: "Sync engine is 38 commits stale; refresh it before defending." Report pass status only in chat, never in a committed file. @@ -192,7 +197,9 @@ Each entry is typed: | ----------------- | ------------------------------------------------------------------ | ---------------- | | `unexplained` | A significant decision with no recorded why | scout, zoom | | `confusing` | Misleading names, surprising indirection, comment contradicts code | zoom | -| `inconsistent` | Two patterns doing the same job; docs disagree with code | scout | +| `inconsistent` | Two patterns doing the same job | scout | +| `stale-doc` | A doc claim (README, docs, AGENTS.md) contradicts the code | scout, zoom | +| `undocumented` | A region or entry point that no doc covers | scout, zoom | | `cleanup` | Dead code, abandoned dependency, ancient TODO | any | | `suspected-bug` | A concrete scenario where the code looks wrong or unhandled | zoom, defense | | `defense-exposed` | The user missed a question because the code misled them | defense | @@ -232,12 +239,41 @@ Large or structural changes: remap the region. Either way: - Keep `[stated]` evidence unless the change contradicts it; if it does, move it to friction as `inconsistent` and flag it for the user. +- Resolve `proposed: ` entries the same way the bare command does. - Re-derive the region's core questions (see `references/defense.md`); keep pass status for any question whose underlying decision didn't change. - If `paths` no longer match anything, the region was moved or deleted; find where it went via `git log --follow` or rename detection, and ask before rewriting the boundary. +## Docs write-back (`docs`) + +Carry what the map learned back into the repo's own docs. Read +`references/docs.md` before starting; it covers inputs, targets, the comment +check, content rules, and the PR. In short: + +1. **Check whether the map is shared:** `git ls-files docs/map` on the target + branch and `git check-ignore docs/map`. If it isn't tracked, ask once whether + to include the map in this PR or write self-contained docs, and record the + answer in `.map/scout.md`. +2. **Propose** every candidate change in chat, grouped by target file, each with + a one-line summary and its source map entry. The user picks what to include. + Nothing is written before that. +3. **Write** the selected changes in a `git worktree` on a new branch, as two + commits: docs first, then comments. The comments commit must pass the comment + check. +4. **Push and open a PR only on an explicit yes**, after showing the diff stat. +5. **Mark** each included friction entry `proposed: ` in the map. + +When a later `/whiteboard` or `refresh` finds a proposed change reachable from +HEAD, remove the entry and upgrade its evidence: `[stated]` rationale and +answered `unexplained` decisions become `[documented: ]`. If the branch is +gone and the change never landed, reopen the entry. + +Rationale that belongs in decision records is handed off by wording: tell the +user these are candidates for decision records (ADRs). If they'd rather not, it +goes into the repo's existing design-docs location instead. + ## Defense phase Read `references/defense.md` before starting a session. It covers question diff --git a/skills/whiteboard/references/docs.md b/skills/whiteboard/references/docs.md new file mode 100644 index 0000000..8880410 --- /dev/null +++ b/skills/whiteboard/references/docs.md @@ -0,0 +1,136 @@ +# Docs write-back + +`/whiteboard docs` turns what the map learned into a reviewable branch of doc +and comment fixes. The user's working tree is never touched, nothing is written +before the user picks changes, and nothing is pushed without an explicit yes. + +## Contents + +- Inputs and targets +- Is the map shared? +- The proposal +- The branch and the comment check +- Content rules +- The PR +- After the PR + +## Inputs and targets + +| Map input | Usual target | +| --------------------------------------------- | ---------------------------------------------------------- | +| `stale-doc` | The doc that makes the claim, corrected in place | +| `undocumented` | README, ARCHITECTURE.md, CONTRIBUTING, or `docs/` | +| `confusing` (misleading comment or name) | The comment or docstring at the receipt | +| `refuted` suspected bug | A comment at the line that looks wrong, explaining why not | +| `[stated]` rationale, `unexplained` decisions | Decision records (ADRs), handed off by wording | +| The map itself, when shared | A pointer in AGENTS.md / CLAUDE.md | + +Follow the repo's conventions over these defaults: if it already maintains +`docs/architecture.md` or a design-docs folder, update that rather than adding a +parallel file. + +Never propose renaming code, even for a `confusing` name. That's a code change; +leave it in the friction log. + +## Is the map shared? + +Check on the branch the write-back targets (usually the default branch): + +- `git ls-files docs/map` lists files → **shared**. +- Otherwise, or if `git check-ignore docs/map` matches → **not shared**. + +If not shared and `.map/scout.md` has no recorded choice, ask once: + +> The map isn't tracked in this repo. Include `docs/map/` in this PR, or write +> self-contained docs that don't link to it? + +Record the answer in `.map/scout.md`. "Include" adds the map to the docs commit +and then treats it as shared. + +## The proposal + +List every candidate change in chat, grouped by target file: + +```text +README.md + 1. Fix: says config is YAML-only; TOML is also supported (stale-doc, config.md) + 2. Add: short "How it's built" section linking to the map (undocumented, index) +internal/sync/engine.go [comment] + 3. Explain why the double-check isn't a race (refuted, sync-engine) +AGENTS.md + 4. Add pointer to docs/map/ for architecture (map shared) +``` + +Then the handoff line if ADR-shaped items exist. Wait for the user to pick ("all +but 3", "only README"). Don't write anything until they do. + +## The branch and the comment check + +1. Create the branch from the target branch (usually the default branch), not + from whatever is checked out: + `git worktree add -b docs/whiteboard- .map/worktrees/docs `. + `.map/` is already excluded, so the worktree stays out of the tracked tree. +2. **Commit 1, docs:** doc files only (and `docs/map/` if the user chose to + include it). +3. **Commit 2, comments:** source-file comment and docstring changes only. + Before committing, run `git diff --cached -U0` and inspect every changed + line. Reject the commit if any added or removed line is not entirely a + comment or docstring in that file's language, including whitespace-only code + changes. Fix the offending hunk and check again; if it can't be made + comment-only, drop that change and tell the user. +4. Remove the worktree after pushing or when the user declines to push; the + branch stays. + +Skip commit 2 when no comment changes were selected. + +## Content rules + +**Stale claims:** correct them in place, matching the surrounding voice and +length. Don't rewrite the section around them. + +**Missing docs, map shared:** a few sentences that rarely go stale (what the +system is, its major parts, where to go next), plus a link to the relevant map +region for depth. The map stays the single deep source because it's the one with +staleness detection. Add a one-line pointer in AGENTS.md / CLAUDE.md so future +agents start from the map. + +**Missing docs, map not shared:** self-contained sections with no links to +`docs/map/` and no AGENTS.md pointer. Write them fuller, since they're the only +copy anyone else will see, but keep to what the map has evidence for. + +**Comments:** explain why, not what, and only where the map has evidence. A +refuted-bug comment names the protection: "Safe without a lock: `Run` is only +called from the single scheduler goroutine (scheduler.go:42)." + +**Decisions:** ADR-shaped items are offered to the user as candidates for +decision records (ADRs). If the user wants them in this branch instead, add them +to the repo's existing design-docs location, or a single +`docs/design-decisions.md` if there is none: one short entry per decision (what +was chosen, over what, why), with its evidence. + +**Everywhere:** only write claims backed by the map's evidence. `[inferred]` +rationale never goes into repo docs. + +## The PR + +After committing, show the diff stat and ask whether to push and open a PR. Only +on a clear yes, push the branch and open the PR with: + +- a one-paragraph summary, +- a table of changes, each with its evidence: code receipts and commit SHAs, + never map paths, so reviewers can check claims against the code without + trusting the map, +- a note that the comments commit is comment-only and can be dropped + independently. + +## After the PR + +Append `proposed: ` to each included friction entry in the map (and note +the branch in `.map/scout.md`). On the next `/whiteboard` or `refresh`: + +- **Change reachable from HEAD** (`git merge-base --is-ancestor`, or the + corrected text is present at HEAD after a squash merge): remove the entry, and + upgrade the evidence of any rationale it carried to `[documented: ]`. +- **Branch gone and change not present:** remove the `proposed:` marker so the + entry is open again. +- **Branch still open:** leave it. diff --git a/skills/whiteboard/references/templates.md b/skills/whiteboard/references/templates.md index 59374df..2589c97 100644 --- a/skills/whiteboard/references/templates.md +++ b/skills/whiteboard/references/templates.md @@ -113,11 +113,15 @@ If a scenario looks unhandled, also log it as a `suspected-bug` below. - `` (``) - `suspected-bug` (``) — verdict: unverified +- `stale-doc` says ; code does (``) A verification pass may later replace `unverified` with `confirmed: `, `refuted: `, or `unclear: `. Preserve whatever verdict is there when refreshing. +`/whiteboard docs` appends `proposed: ` to entries it includes in a +write-back branch; the entry is removed once the change reaches HEAD. + ## Zoom candidates - **** (``): @@ -132,7 +136,9 @@ directory. ```markdown # Scout notes -Map location: docs/map/ (or the chosen alternative, and why) +- Map location: docs/map/ (or the chosen alternative, and why) +- Docs write-back: , chosen + ## Evidence sources