Purpose: Use this after implementing or reviewing a change to keep the repo knowledge base synchronized with real behavior.
Read:
AGENTS.mdARCHITECTURE.mddocs/SECURITY.mddocs/RELIABILITY.mddocs/QUALITY_SCORE.md- relevant
docs/product-specs/*
Workflow:
- inspect changed files
- determine whether behavior, architecture, reliability, or security posture changed
- update the smallest set of docs needed
- if repeated guidance is emerging, update the nearest
AGENTS.mdor create/update a skill - run
npm run verify:docs
Output:
- minimal doc diffs that eliminate drift
- if no doc changes are needed, state why in the PR description or plan log
Heuristics:
- user-visible behavior => product spec
- repeated review comment => AGENTS or skill
- boundary/layer change => ARCHITECTURE
- failure-mode / telemetry / smoke-path change => RELIABILITY
- trust-boundary / auth / secret / tool-authority change => SECURITY
- evidence-based score shift => QUALITY_SCORE