docs-standards
Documentation maintenance rules — which docs map to which code areas, the thin-pointer/no-drift rule, and the graphify-update step. Owned by project-steward. Load for /update-docs and the docs-sync step of the implement-workflow.
saeedkolivand · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add saeedkolivand/ai-job-hunter-app --skill docs-standardsAbout this skill
name: docs-standards description: Documentation maintenance rules — which docs map to which code areas, the thin-pointer/no-drift rule, and the graphify-update step. Owned by project-steward. Load for /update-docs and the docs-sync step of the implement-workflow.
Docs standards (project-steward)
Code → docs map
- IPC contract change (
packages/shared/src/ipc/contracts/) → write the prose as TSDoc on the contract member, thenpnpm gen:api.docs/API.mdis generated (scripts/gen-api-docs.mjs) and must never be hand-edited; CI enforces freshness viapnpm gen:api:check. - New domain/module or boundary change →
docs/knowledge/+docs/ARCHITECTURE.md. - Export/template change →
docs/EXPORT_TEMPLATES.md+docs/knowledge/resume-domain.md. - Scraping/provider change →
docs/knowledge/automation-domain.md. - Design-system change →
docs/DESIGN_SYSTEM.md. - Architecture / module / IPC-contract / registry change → also refresh the landing diagrams
apps/landing/src/data/architecture-map.ts+apps/landing/src/content/how-it-works/body.html, then runpnpm check:landing-drift(CI enforces it via the Lint & Format job). - A durable architecture decision → an ADR in
docs/knowledge/decision-records/.
No-drift rule (thin pointers)
Applies to everything under docs/, not only docs/knowledge/ — that is the scope reviewers enforce, so it is the scope to write to.
Describe shape and contracts; never copy drift-prone literals (scoring weights, thresholds, template/board/applier counts, function signatures, enum members, file lists). Point at the owning source symbol instead (weights → commands/match_resume.rs; templates → export/templates/mod.rs; registries → scraping/boards/mod.rs (SCRAPERS)).
The ~150-line cap is narrower than the rule around it: it applies to docs/knowledge/ files only, not to every page under docs/.
Self-check before saving a doc edit: for every number, name or signature on the page, ask "if someone changed this in the code tomorrow, would this page silently become a lie?" If yes, replace it with a pointer to where it lives.
Generated pages are exempt because they are not editable at all. A file opening with a GENERATED FILE banner (docs/API.md) is rendered from its source by a script; restating the contract is its whole purpose. Fix the TSDoc on the contract member and re-run the generator — never the page.
After editing code or docs
Run graphify update . (AST-only, no API cost) so the graph stays current.
Last-updated header maintenance
Most docs carry a Last updated: YYYY-MM-DD header (line ~3). The auto-bump hook updates the date automatically when files are staged for commit via lint-staged, so no manual date updates are needed.
If a doc's header includes a trailing annotation like Last updated: YYYY-MM-DD (v0.116.0) or (task #16: ...), refresh the annotation to describe the current change whenever you edit that doc — the hook preserves it. Example:
- Before:
Last updated: 2026-07-16 (v0.116.0) - After edit for new feature:
Last updated: 2026-07-16 (v0.117.0: new feature)or just(v0.117.0)if the versioning scheme is simple.
This makes commit history and blame queries meaningful — the annotation documents why the doc was touched, not just when.
Lessons graduation
When an Architecture-decision lesson becomes an ADR, remove it from lessons.jsonl — the ADR is then its single source.
External standards & best-practices (verified 2026-06-19)
- Diátaxis — keep the four types distinct, never mixed in one page: Tutorial (learning), How-to (task), Reference (lookup/spec), Explanation (the "why"). Axes: action↔cognition, acquisition↔application. https://diataxis.fr/
- Docs-as-code — docs in-repo, versioned, reviewed in PRs, built/linted in CI. https://www.writethedocs.org/guide/docs-as-code/
- Thin-pointer / no-drift — see §No-drift rule above for the scope and the self-check; it is the whole of
docs/, not justdocs/knowledge/. After code changes, re-sync docs + rungraphify update ..
Common mistakes: a "reference" page drifting into tutorial prose (split it — one need per page); pasting code values/signatures into docs instead of pointing at the source (guaranteed drift).