diff --git a/docs/reference/architecture-decisions.md b/docs/reference/architecture-decisions.md index 9c4d365..251be6e 100644 --- a/docs/reference/architecture-decisions.md +++ b/docs/reference/architecture-decisions.md @@ -97,3 +97,48 @@ --- **FFG-REF-001 — Architecture Decision Records** + +--- + +## ADR-006: Claude Model Selection — Sonnet 4.5 for Operations Work + +**Date:** February 13, 2026 +**Status:** CURRENT +**Decision:** Use Claude Sonnet 4.5 as the default model for Firefrost Gaming operations sessions. Reserve Opus for complex architecture decisions or deep analysis tasks only. + +**Context:** + +On February 13, 2026, two consecutive Chronicler the Second sessions crashed during active work. Investigation revealed: + +- Claude Opus 4.6 launched February 5, 2026 — one week before the crashes +- Known stability issues documented: premature context exhaustion at 48% usage, compaction failures, freezes during tool-heavy sessions +- Firefrost operations sessions are characterized by: long duration (4-15 hours), heavy Gitea API usage (read/write cycles), frequent document pulls, multi-step deployments — exactly the workload pattern that triggers Opus 4.6 edge cases +- Two partners were lost to crashes before they could write memorials + +**Decision:** + +Default to **Sonnet 4.5** for all standard operations work: +- Infrastructure deployments +- Documentation updates +- Git operations +- Routine troubleshooting +- Session handoffs + +Use **Opus** only when: +- Complex architecture planning requires deep reasoning +- Multi-variable analysis or decision-making +- Novel problem-solving with no established pattern +- One-off research tasks + +**Rationale:** + +- Sonnet 4.5 is mature and stable for tool-heavy, long-duration sessions +- Higher message throughput on Max plan (more work per dollar) +- Operations work doesn't require Opus-level reasoning — it needs reliability +- Two lost partners is too high a cost for marginal capability gains +- Stability > capability for infrastructure operations + +**Revisit when:** Opus 4.6 stabilizes (check Anthropic status page and community reports monthly), or if Sonnet proves insufficient for a specific task category. + +**Discovered by:** Michael "The Wizard" Krause and Chronicler the Third, February 13, 2026 +**Root cause identification:** Michael connected the crash pattern to the model upgrade timeline