Decision Logger

When a significant decision is made during development, record it.

When to Log

• A spec requirement is added, removed, or modified after approval
• A technical approach is changed (e.g., switching from polling to websockets)
• A trade-off is accepted (e.g., choosing simplicity over performance)
• A dependency is added or removed
• An architectural pattern is established

How to Log

Create a file in .factory/decisions/ with this format:

Filename: NNN-descriptive-name.md (e.g., 001-use-websockets-for-realtime.md)

Content:

# NNN: [Decision Title]
**Date:** YYYY-MM-DD
**Status:** Accepted | Superseded by NNN | Deprecated
**Relates to:** Requirement N (if applicable)

## Context
[What situation prompted this decision? 2-3 sentences.]

## Decision
[What was decided? 1-2 sentences.]

## Rationale
[Why this approach over alternatives? Key reasons.]

## Alternatives Considered
- [Alternative 1]: [Why rejected]
- [Alternative 2]: [Why rejected]

## Consequences
- [What changes as a result]
- [What trade-offs were accepted]

Process

1. Check .factory/decisions/ for the latest number
2. Increment by 1, zero-pad to 3 digits
3. Write the decision record
4. Reference it in any related code comments if helpful

Rules

• Keep decisions concise (under 30 lines)
• One decision per file
• Never modify past decisions -- create a new one that supersedes
• Link to related requirements when applicable