Skip to content

feat(whiteboard): add docs write-back mode #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
markphelps merged 1 commit into from
Sep 24, 2026
Merged

feat(whiteboard): add docs write-back mode #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion development/.codex-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down Expand Up @@ -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.",
Expand Down
5 changes: 3 additions & 2 deletions development/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
34 changes: 18 additions & 16 deletions development/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
48 changes: 42 additions & 6 deletions development/skills/whiteboard/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -49,6 +52,7 @@ Parse the argument after `/whiteboard`:
| `/whiteboard zoom <region>` | 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 `<region>` can be an existing region slug, a name from the Unexplored list, or
a plain description ("the sync engine", "auth"). Resolve descriptions to paths
Expand All @@ -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: <branch>` 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.
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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: <branch>` 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: <branch>` 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: <path>]`. 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
Expand Down
Loading
Loading