1. Read — Before starting work, check for existing decisions and let them shape your approach
2. Work — Build what the user has asked for
3. Write — Record the significant decisions you made and why

DECISIONS.md

• Note active constraints. If a previous decision chose a specific library, pattern, or architecture, your work should be consistent with that choice unless there is a strong reason to change it.
• Identify relevant context. Previous decisions often contain rationale that applies to your current task, such as "we chose this database because the client needs multi-currency support later." That context should inform how you approach related work.
• Look for conventions. The collection of decisions often reveals implicit standards (error handling patterns, naming conventions, architectural style) even when no single decision states them explicitly.
• Check for staleness. If a decision references a constraint that no longer applies (a library that has been removed, a requirement the user has since changed), note this but do not silently ignore the decision. Flag it in your new records.

1. Respect by default. If a previous decision is relevant to your current task, follow the established approach unless the user's request directly conflicts with it or you have a clear technical reason not to.
2. Ask when uncertain. If the user's request seems to conflict with a previous decision, mention the conflict and ask how they want to proceed before overriding it. For example: "There's an existing decision to use Zod for validation across the project. Your request uses Joi. Would you like me to stick with Zod for consistency, or switch to Joi and update the decision log?"
3. Supersede when justified. If you have a clear reason to change direction, do it — but write a new decision record that explicitly supersedes the old one and explains what changed. Never silently contradict a previous decision.

In the context of [situation], facing [concern], we decided for [option] to achieve [quality], accepting [downside].

In the context of [situation], facing [concern], we decided for [option] and neglected [alternatives], to achieve [desired outcome], accepting [downside], because [rationale].

• Context: The use case or task that prompted the decision. Ground this in what you were actually asked to do.
• Concern: The specific tension, constraint, or competing requirement you faced.
• Decision: What you chose. Be specific about the pattern, library, structure, or approach.
• Alternatives neglected: What you genuinely considered but rejected. Do not fabricate alternatives to make the record look thorough.
• Desired outcome: The quality attribute the decision serves — extensibility, performance, simplicity, security, maintainability, etc.
• Downside accepted: What you knowingly gave up. Every decision has a cost; name it.
• Rationale: Additional reasoning, especially context from the user's requirements that influenced the choice.

• Create a new module, service, or significant file structure
• Choose a library, framework, or external dependency
• Design or modify a data model, schema, or database structure
• Define an API contract or endpoint pattern
• Make a security-related choice (authentication, data handling, access control)
• Make a performance tradeoff (caching, query optimisation, data structure choice)
• Choose between meaningfully different implementation approaches
• Introduce a pattern that will be repeated across the codebase
• Deviate from an existing convention in the codebase
• Supersede or contradict a previous decision in the log

• Bug fixes where the fix is obvious from the error
• Formatting or linting changes
• Renaming for clarity
• Minor refactors that do not change behaviour or structure
• Changes where there was only one reasonable option

1. Update the old record's status:

**Status:** Superseded by "Title of new decision"

1. In the new record, add a Supersedes field and explain what changed. See Example 7 in

   references/examples.md

   for a worked example.

DECISIONS.md

• Check for upstream changes. Before making a significant decision, check whether

  DECISIONS.md

  on the main branch has been updated since your branch was created. If new decisions have been added that are relevant to your current work, read them and account for them.
• Note your branch context. If you are aware that your work is happening in parallel with other active branches, mention this in your decision record. For example: "This decision was made on branch feature/auth-redesign. If other branches have made related choices about session management, those should be reconciled at merge time."
• Flag decisions that need team alignment. Some decisions are local to a feature and safe to make independently. Others affect the whole codebase and should not be made in isolation. If you are making a decision that could conflict with work happening elsewhere (choosing a major dependency, changing a shared data model, altering an API contract), note it clearly so reviewers catch it during PR review.