Skip to content

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

Merged
markphelps merged 1 commit into
mainfrom
feat/whiteboard-docs
Sep 24, 2026
Merged

markphelps merged 1 commit into
mainfrom
feat/whiteboard-docs

Conversation

@markphelps

Copy link
Copy Markdown
Owner

Adds /whiteboard docs, which carries what a map learned back into the repo's own docs as a reviewable branch.

What it does

  • Inputs: stale-doc, undocumented, and confusing friction, [stated] rationale, unexplained decisions, and refuted suspected bugs.
  • Targets: README, ARCHITECTURE.md, CONTRIBUTING, docs/, AGENTS.md/CLAUDE.md, and code comments/docstrings. It follows existing repo docs conventions and never proposes code renames. ADR-shaped items are handed off by wording ("candidates for decision records (ADRs)"), with a design-decisions doc as the fallback.
  • Flow: check whether the map is tracked (ask once to include it or write self-contained docs, recorded in .map/scout.md) → propose changes in chat, grouped by file, and the user picks → write in a git worktree branch as two commits (docs, then comments-only) → show the diff stat and push/open a PR only on an explicit yes.
  • Comment check: the comments commit is rejected if any changed line isn't entirely a comment or docstring.
  • Content rules: stale claims are corrected in place. Missing docs get a short summary plus a map link when the map is shared, or fuller self-contained sections when it isn't. [inferred] rationale never goes into repo docs. PR evidence cites code receipts and commits, never map paths.
  • Map lifecycle: included entries are marked proposed: <branch>. On the next /whiteboard or refresh, landed changes remove the entry and upgrade evidence to [documented: <path>]; abandoned branches reopen it.

Other whiteboard changes

  • The hard rule changes from "never modify source code" to "never modify the working tree", with docs as the only, narrowly scoped exception.
  • New friction types stale-doc and undocumented. inconsistent now covers only "two patterns doing the same job".

Checks

Ran locally: npm run format:check, npm run validate, and npm run sync (mirror under skills/ included).

@markphelps
markphelps merged commit db9b2e4 into main Sep 24, 2026
1 check passed
@markphelps
markphelps deleted the feat/whiteboard-docs branch September 24, 2026 18:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant