docs-sync
/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.
- Author
- kamiazya ↗
- Repository
- whiteboard ↗
- Licence
- Apache-2.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
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.
Original author 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.
How it works
- Audience split & language (project rules)
- Trigger → target
- Diátaxis quadrants
- Honesty rule
- Doc images
- Discipline
SKILL.md preview
--- 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 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` (local `tmp/` 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. The project is excluded from the ordinary `pnpm test` run because it writes into the repo, so regenerate deliberately and commit the result. `docs:snapshots:check` generates TWICE before `git diff --exit-code`: Vite's first run after a config change can re-optimise dependencies and produce a one-off pixel drift, so the second run is the stable artifact. Diffs surviving a double run are a real UI change, not jitter. Cross-platform font rendering means a Linux CI capture is not byte-identical to a macOS one — this stays a developer-driven, regenerate-locally workflow. ## 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.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · kamiazya/whiteboard | 100 | Apache-2.0 |
| nearform/lastlight | 100 | MIT |
| laurigates/claude-plugins | 100 | MIT |
| microsoft/apm | 100 | MIT |
| microsoft/apm | 100 | MIT |
| itsofficialadi/boundiff | 100 | MIT |
| jMerta/codex-skills | 100 | MIT |
| zjunlp/skills | 100 | MIT |
| githubnext/apm | 100 | MIT |
Database snapshot: 13.11.2026 · package version 3bc307ff4771 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100dev-docs
Use when writing, organizing or updating project documentation - creating a docs/ folder, adding a doc page, recording a decision (ADR), writing a mission, architecture or reference page, or keeping docs in step with a code change. Sets the folder structure, the writing style,… - 100docs
Authors, audits, and maintains project docs — CLAUDE.md / .claude/rules/, AGENTS.md, README.md, and Diátaxis docs/ trees — in modes init, update, readme, and audit. Triggers on "init claude", "update docs", "docs drift", "write a README", "/docs". - 100keep-docs-in-sync
Keep documentation in sync with a code or contract change in the SAME PR. Use whenever you change an interface, wire field, endpoint, config field, default, harness/backend value, or runtime behavior, and after any implement-feature slice that lands such a change. Triggers -… - 100write-docs
Write or edit a page of the statica documentation site in docs/, following its Diátaxis layout, its style rules, and the Go tests and build checks that read the pages. Use for any change under docs/, including the documentation that accompanies a code change. - 100document-it
Diátaxis documentation builder for code repositories. Interviews the user about audience and scope, analyzes the codebase, writes a clear Diátaxis doc set (tutorials, how-to guides, reference, explanation) with Mermaid and code-generated diagrams, scaffolds a Zensical site (the… - 100documentation
Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API…