Docs sync
When and how to update the whiteboard project's docs alongside a code change — the trigger→target map, Diátaxis quadrants, doc locations, the honesty rule, and doc-image regeneration. Use when a change has a user-visible effect, alters an API/contract/config, or when triaging a docs gap.From its SKILL.md
npx -y skills add kamiazya/whiteboard --skill docs-syncAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.8 KB, as published. Nobody here has run it
Docs Sync
Docs, code, and tests stay in sync within the same change. A user-visible behavior, API, contract, or config change that ships without its docs is incomplete.
Audience split & language (project rules)
./docs/**= USER-facing only, Diátaxis (tutorials / how-to / reference / explanation).- Developer/contributor docs = OSS convention at repo root:
README.md,SECURITY.md,CONTRIBUTING.md,CODE_OF_CONDUCT.md,.github/templates, etc. Never put contributor guides under./docs. - Language: English for everything under
docs/,README,SECURITY,CONTRIBUTING,.github(localtmp/notes may differ).
Trigger → target
| Change | Update |
|---|---|
| User-visible behavior (UI, flow, MCP tool result that depends on state) | the how-to / tutorial that covers that flow; attach evidence per PR Visual Evidence rule |
| MCP tool added/changed (input/output schema) | tool reference docs + any skill that lists tools (keep tool lists in sync — a known drift source) |
| HTTP route / response shape | API reference; the typed-client docs if any |
| Persisted JSON / migration / data model | the relevant explanation/reference + migration notes |
| Config / env / deploy path | README + getting-started + self-host/docker docs + .env.example |
| New capability with no doc home | propose a new page in the right Diátaxis quadrant |
Diátaxis quadrants
- Tutorial — learning-oriented, "first X in 5 minutes" (the empty quadrant is a known gap).
- How-to — task-oriented recipes.
- Reference — dry, complete (tools, routes, config).
- Explanation — why/architecture/trade-offs.
Keep each doc in its quadrant; don't mix tutorial and reference.
Honesty rule
Document the shipped state, never the aspiration. Do not describe a feature/flag/route/path that doesn't exist yet. If the code is partial (e.g. apps/web mid-migration), document the real current behavior. Getting-started must be runnable as written.
Doc images
Images under docs/assets/** produced from the UI are regenerated by Vitest browser-mode tests, not hand-edited:
pnpm --filter @kamiazya/whiteboard-web docs:snapshots
Add a *.docs-snapshot.test.tsx, pin the clock, save via resolveDocAssetPath, run, and commit the PNG with the markdown that references it.
Discipline
Update only doc files in a docs pass; commit them separately with a docs: message. Fix broken links you touch. Surface any user-visible change you could not find a doc home for.