菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
How to run the periodic standing-codebase-health audit in the whiteboard repo — fan out auditors across health dimensions, adversarially verify, triage into Tasks/tmp-issues. Use when scheduling or running a periodic review (after a fold, weekly, pre-milestone) for unwired/incomplete features, architecture debt, maintainability, contract drift, test gaps, and dev-experience friction. Not for reviewing a single diff (that is the review workflow).
How to run the whiteboard repo's per-diff change-review gate — args, return contract, and the externalized-criteria mechanism for review.workflow.mjs. Use when running a standalone review gate (pre-merge, pre-un-draft, ad-hoc) or when authoring/tuning the review workflow that dev-loop composes.
Local-private task/ticket management for the whiteboard repo across workflows and agents, without GitHub Issues. Defines the tmp/ workspace buckets, the tmp/issues frontmatter convention, and the bridge between the native Task list (live board) and tmp/issues (durable backlog). Use when triaging findings, tracking in-flight work across dev-loop/review/dogfood-triage/reconcile/plan-initiative, or recording/resolving a follow-up.
Conventions and hard-won gotchas for authoring/maintaining the whiteboard repo's Dynamic Workflows (.claude/workflows/*.workflow.mjs) — dev-loop, review, dogfood-triage, reconcile. Use when editing or adding a Workflow script, debugging args not arriving, composing workflows, or running parallel dev-loops.
Monitor and triage the POST-PUSH automated-review surface for the whiteboard repo — GitHub Actions CI, CodeRabbit, AccessLint, the WIP app, CodeQL, and Dependabot — into Tasks/tmp-issues. Use after the integrator pushes, when CI/PR checks complete or a review bot comments, to decide what is real and file/fix it. Complements the local lefthook pre-push gate (which runs before push); this covers what only the cloud sees.
Triage, review, and merge Dependabot dependency-bump PRs + clear Dependabot security alerts for the whiteboard repo. Security-first, semver x ecosystem classification, verify-CI + `pnpm audit --prod` gate awareness, conflict-cascade-safe batch merging by the single integrator. Adapted for this repo's constraints — NO GitHub Issues (backlog -> Tasks/tmp-issues), release-please conventional commits, npm-published runtime-dep priority. Pairs with the dependabot-triage workflow (which does the read-only analysis fan-out).
| name | docs-sync |
| description | 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. |
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.
./docs/** = USER-facing only, Diátaxis (tutorials / how-to / reference / explanation).README.md, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, .github/ templates, etc. Never put contributor guides under ./docs.docs/, README, SECURITY, CONTRIBUTING, .github (local tmp/ notes may differ).| 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 |
Keep each doc in its quadrant; don't mix tutorial and reference.
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.
Images under docs/assets/** produced from the UI are regenerated by Vitest browser-mode tests, not hand-edited:
pnpm --filter @kamiazya/whiteboard-mcp 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.
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.