# 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

1. Create a decision record when choosing between meaningful alternatives
2. Write while the decision is fresh - context fades quickly
3. Store in a `decisions/` directory alongside the tool
4. Reference in related invariants or golden examples

## Template

```markdown
# 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

```markdown
# 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.