docs: team OS guide (Guide 06) — strategic, scenario-driven, for eng + QA

[smorchestraai-code]

Summary

Reframes the team user guide as an OS manual built around scenarios + judgment, not a command reference.

825 lines. Covers smorch-dev v1.6.0 + smorch-ops v1.1.0.

Structure (10 parts)

1. Why This OS Exists — philosophy + what we optimize for
2. The Mental Model — 3-layer cognitive framework, chain as forcing function, verb boundaries
3. Constraints to Internalize — RULE 0, 9 lessons, escalation gates, branch model, codex doctrine
4. 12 Scenarios — the meat (Day 1, new feature, existing-project feature, bug fix, hotfix at 11pm, /smo-score 78, /smo-score 88, Lana sends back at 65, /smo-canary auto-rolled back, tempted to skip /smo-verify, QA "out of scope" dispute, inherit legacy repo without overlay) — each with Situation → Temptation → Right Path → Rule → Evidence (+ Anti-pattern where relevant)
5. Decision Frameworks — when X vs Y matrices (bridge-gaps vs replan, patch/minor/major, careful/guard, when to ping Mamoun, Codex vs Claude)
6. Cadences — session / PR / daily / weekly / sprint / monthly / incident
7. Failure Modes — anti-patterns + cost
8. When Things Go Sideways — RED dev-start, validator failures, stuck plugin, SSH issues, production incidents
9. Appendices — 22 commands · canonical paths · server registry · 30-second pocket card
10. Glossary

Why this matters

The team doc is the first thing a new hire reads. If it's a command reference, they learn syntax. If it's an OS guide, they learn judgment — and judgment is what the 5% of decisions the OS doesn't make for you require.

Every scenario maps to a real situation that's already happened (or will happen). Each one cites the rule that codifies the right answer.

Test plan

• Read end-to-end (target: 25 min)
• Verify all command refs resolve (no /smo-X that doesn't exist in v1.6)
• Verify all SOP refs resolve (SOP-13, SOP-14, SOP-36 paths)
• Spot check 2-3 scenarios against your own experience — do they reflect reality?

🤖 Generated with Claude Code