documentation-and-adrs

To write an architectural decision record, use a structured template covering Status, Context, Decision, and Consequences, ensuring you capture the why behind the choice rather than restating the code. This preserves reasoning for future contributors.

You need durable documentation when adding or changing public APIs, shipping user-facing behavior shifts, or onboarding humans and agents. This prevents teams from re-litigating architectural rationale during recurring explain this again moments.

The lifecycle status flow for an architectural decision record progresses sequentially through four stages: PROPOSED, ACCEPTED, SUPERSEDED, and DEPRECATED. This explicit lifecycle manages decision history within repository-specific capability timelines.

To explain intent in inline documentation, write comments that articulate the constraints and reasoning behind the code rather than restating what the code does. This intent-focused standard ensures durable documentation survives across the system lifecycle.

Yes, you need an ADR template, sequential numbering rules, and repository-specific capability-timeline linking to OpenSpec workflows. These conventions maintain decision history under docs/decisions/ and ensure structured documentation across the system lifecycle.