| name | design-decisions |
| description | Design Decision Log Pattern guidance for Fortress Rollback. Use when Architectural decisions, design alternatives, superseding prior choices. |
Design Decision Log Pattern
Use a lightweight, append-only decision log for major design choices. Keep it short, searchable, and linked to code and PR context.
Location
Store logs under this skill's references/ directory as plain text files by domain,
for example:
references/network.txtreferences/sync-layer.txt
Read the design-history index before adding or superseding
an entry. Load only the domain file relevant to the current decision.
Entry Format
YYYY-MM-DD | Decision | Supersedes | Rationale | Evidence | PR/Issue
Example:
2026-03-20 | Use checked frame arithmetic in rollback paths | None | Prevent overflow-triggered desync | src/lib.rs Frame::try_add/try_sub | PR #123
When to Log
- Public API behavior choices
- Determinism-sensitive algorithm choices
- Safety/reliability guardrail choices
- Performance trade-offs on hot paths
- Replacements of prior architectural patterns
When Not to Log
- Trivial refactors
- Test-only maintenance changes
- Formatting/lint-only changes
- Non-behavioral comment updates
Supersedes Chains
If replacing prior guidance or behavior, set Supersedes to the prior entry date/title.
2026-03-20 | Switch queue iteration to stable order | 2025-11-02 HashMap iteration in queue processing | Determinism | src/input_queue/mod.rs | PR #456
Review Integration
During review:
- Confirm major design-impacting PRs include a decision log entry.
- Confirm supersedes links are correct when old patterns are replaced.
- Reject vague rationale with no code evidence.
Anti-Patterns
- Do not write essays. One line per decision.
- Do not create logs for every small change.
- Do not omit evidence links (file/symbol/PR).
