| name | package-docs-graph |
| description | Enforce the repository package documentation contract as a navigable dependency graph. Use when creating or updating package README, docs pages, navigation tables, architecture router, API docs, usage docs, constraints, blast-radius/consumer records, internals, decisions, or testing docs. Docs exist so a later model drills down from task to edit target with minimal context and sees blast radius before editing. Keep content terse; keep only repo-specific contracts, paths, edges, intent, and decisions. |
Package Docs Graph
Docs are a navigable dependency graph, not prose. Their job: let a later model
reach the exact edit target, understand why it exists, and see what breaks —
without reading the whole package.
Optimize for retrieval and blast-radius awareness, not pedagogy.
Two jobs every doc serves
- Drill-down: reach the right file/symbol cheaply, stopping early.
- Blast radius: know consumers and invariants before editing, so a precise
change does not ripple.
A doc that does neither is noise; delete it.
Required structure
- Every package:
README.md + docs/.
- README first line: one-line summary. README is an index only.
- README nav table links every required doc (exact shape in
references/templates.md).
- Required doc set:
overview, architecture, api, usage, constraints,
internals, testing.
architecture.md is the router node: a path -> contract table mapping each
top-level source partition to its responsibility. Drill-down starts here.- Domain docs beyond the required set are allowed; add one nav-table row each.
- Large packages: co-locate a sub-node doc with a source subtree (e.g.
src/agent/README.md) so a model loads only that subtree, not the whole
package api.md. Keep package docs/ as the index that links sub-nodes.
Graph edges (the part that makes it a graph)
- Doc -> code: link down to
path/file.ts#symbol, not just a directory.
- Code -> doc: a comment anchor pointing back, e.g.
// see docs/x.md#section.
Place anchors only where a non-obvious contract or decision lives.
- Both directions must exist for any contract worth documenting; a one-way link
is a dead end for the session that entered from the other side.
Blast radius (required, usually missing)
- For each exported subpath, record in
constraints.md:
- Consumers — who depends on this surface.
- Invariants — what callers rely on that a change must not break.
- This is the edge set a model uses to bound a change. Without it the model
greps globally and the docs failed their purpose.
Design intent (protect from the terseness rule)
internals.md keeps a Decisions/Invariants list: one line per decision +
one line of why.- Drop generic explanations the model already knows. Keep only non-obvious
intent specific to this repo. Terse and intent-preserving do not conflict
when intent has its own bounded slot.
UI packages
- If a package renders UI, document the browser-test locator contract in
constraints.md and testing.md: approved test ids (as a list/table),
landmarks and roles, accessible naming, and known exceptions. A generic
"uses semantic markup" line does not satisfy this. Defer to the
headless-browser-markup skill for the contract shape.
Freshness (a stale doc is worse than none)
- A model trusts docs to avoid reading code; a confidently wrong doc causes the
exact ripple this contract prevents.
- Update the covering doc section in the same change as the source it describes.
- Keep
architecture.md's path table in sync with real src/*; treat drift as
a defect, not a style nit.
Writing rule
- README index-like and short.
- Durable contracts in docs, not comments.
- JSDoc only where an exported API needs a durable contract not already clear
from its name and type.
- TypeDoc optional; never commit generated output.
Output
Return: missing docs, generated/updated docs, structural gaps, missing graph
edges (doc->code / code->doc), missing consumer/invariant records, and any
path-table drift found.
Load
If writing, read references/templates.md.
A full worked example produced by this skill lives in assets/example/.
