docs-workflow

Use when a decision has been made or is about to be made about architecture, a library/framework choice, an API contract, or any change that's expensive to reverse later - drafts an Architecture Decision Record so the reasoning isn't lost.

Use after a change that adds, removes, or restructures a service, module boundary, data store, or integration point - checks the repo's ARCHITECTURE.md against the current code and updates it so the doc doesn't drift from reality.

Use before starting non-trivial implementation work - a new feature, a cross-cutting change, or anything touching multiple components - to draft a design doc covering goals, approach, and alternatives considered, so review happens before code is written.

Use after an incident, outage, data issue, or significant bug has been resolved - drafts a blameless postmortem covering timeline, root cause, and follow-up actions so the same failure is less likely to recur.

Use when an operational procedure - deploying, rotating a credential, recovering a service, running a manual migration - has been done by hand and would need to be repeated or handed off, so it should be captured as a runbook instead of living only in someone's memory or shell history.