3.3 KiB
Decision Record Template
Use this template to document significant decisions about tool behavior. Decision records prevent rehashing settled questions and preserve context for future maintainers.
How to Use
- Create a decision record when choosing between meaningful alternatives
- Write while the decision is fresh - context fades quickly
- Store in a
decisions/directory alongside the tool - Reference in related invariants or golden examples
Template
# Decision: [Brief title]
**Date:** YYYY-MM-DD
**Context:** [Why this came up - what problem or question prompted this decision]
**Decision:** [What was decided - be specific and unambiguous]
**Rationale:** [Why this approach - what factors drove the choice]
**Alternatives Considered:**
- [Alternative 1]: [Why rejected]
- [Alternative 2]: [Why rejected]
**Future Considerations:** [When to revisit, if ever - what would change this decision]
Field Definitions
Brief title: Action-oriented summary. Start with verb when possible: "Use X for Y", "Require Z before W".
Date: When decided. Helps assess if context has changed enough to revisit.
Context: The situation that forced a decision. Without this, future readers can't evaluate if the decision still applies.
Decision: The actual choice. Should be clear enough to verify compliance.
Rationale: Why this choice over others. Focus on the deciding factors, not comprehensive analysis.
Alternatives Considered: What else was evaluated. Prevents re-evaluation of already-rejected options.
Future Considerations: Conditions that would invalidate this decision. Explicitly stating "never" is valid if true.
Example: Filled-in Template
# Decision: Require subagent for all creation work
**Date:** 2026-01-15
**Context:** Architect skills were creating files directly, leading to inconsistent patterns and context pollution in main conversation.
**Decision:** All architect skills must spawn a subagent for creation work. The main agent handles only dispatch and summary.
**Rationale:**
- Fresh context prevents pattern drift from accumulated conversation
- Subagent can fail without losing main conversation state
- Forces explicit instruction writing, which catches missing requirements
- Enables parallel work on independent tasks
**Alternatives Considered:**
- Direct creation with context management: Rejected because context pollution is subtle and hard to detect until patterns degrade
- Optional subagent for complex tasks: Rejected because "complex" is subjective and would lead to inconsistent application
**Future Considerations:** Revisit if subagent spawn overhead becomes significant (currently ~2s). Would need 10x improvement in direct creation consistency to justify reverting.
When to Create Decision Records
Do create for:
- Choosing between valid approaches
- Rejecting commonly-requested features
- Establishing patterns that constrain future work
- Resolving disagreements or confusion
Skip for:
- Obvious choices with no real alternatives
- Temporary workarounds with clear end dates
- Implementation details that don't affect behavior
Organizing Decision Records
Store in chronological order with date prefix:
my-tool/
SKILL.md
decisions/
2026-01-15-require-subagent.md
2026-01-18-description-validation.md
Link from SKILL.md or invariants when relevant.