Decision Records

This skill is guidance, not a script. Preserve reasons a future maintainer cannot reliably recover from code. Local mechanical changes and ordinary discussions do not automatically need a record.

When not to use

• Temporary task state, plans, or investigation logs. Use plan or the conversation.
• The current explanation of a system, or an incident story about a defect that escaped. Use canonical-docs.
• Wording of the record. Use prose-standard.

Inputs and authorization

• Required: the problem, the choice, and the alternatives actually considered. Never invent alternatives to fill a template.
• Authorization: recording a status records reality; it grants no implementation permission.

Method

Search for an existing owner first. Follow the project's rules for amending or superseding it; do not create a new file per session. Record the problem, choice, meaningful constraints, real alternatives, consequences, and verification or evidence gaps that still affect judgment. Include conditions for reconsideration when useful.