Problem
Users have no systematic way to debug Squad failures. The 4-layer model (Governance, Platform, LLM, State) is documented in issue comments but not in user-facing docs.
From
Flight + Procedures reviews of #21. Phase 2 in revised plan.
Proposed
Create docs/troubleshooting.md covering:
- The 4-layer failure model with clear definitions
- Investigation checklists per symptom (NOT blame tables)
squad doctor as first step for every problem- Common failure patterns with exact fix commands
- 'My agent did nothing' / 'Decisions keep growing' / 'Agent gave wrong answer' walkthroughs
Key Constraint
Heuristics must be framed as 'investigation checklist' not 'root cause' — multiple layers can produce identical symptoms.
Owner
Procedures (Prompt Engineer) + PAO (DevRel)
Problem
Users have no systematic way to debug Squad failures. The 4-layer model (Governance, Platform, LLM, State) is documented in issue comments but not in user-facing docs.
From
Flight + Procedures reviews of #21. Phase 2 in revised plan.
Proposed
Create
docs/troubleshooting.mdcovering:squad doctoras first step for every problemKey Constraint
Heuristics must be framed as 'investigation checklist' not 'root cause' — multiple layers can produce identical symptoms.
Owner
Procedures (Prompt Engineer) + PAO (DevRel)