documentation-guidelines
Documentation Guidelines
Capture durable meaning that code alone does not explain: business intent, ownership, invariants, permissions, contracts, and operational decisions. Let source and tests own implementation details and executable evidence.
Delegation
Run in the main conversation by default. Delegation can increase usage: obtain explicit approval for the proposed agent count and scope before using subagents. Reuse that approval within its bounds; ask again before expanding the approved count or scope.
Find the owner and evidence
Read the relevant documentation index and owner when present, then verify affected facts against source, tests, schemas, configuration, and runtime evidence. Follow links needed to understand the changed contract; stop when further reading no longer affects the result. Missing or stale documentation is a reason to inspect source, not a prerequisite that blocks work.
For the scope at hand, identify applicable actors, triggers, rules, state transitions, inputs/outputs, side effects, failure paths, ownership, and compatibility requirements. Omit irrelevant categories; record unresolved material facts without inventing them.