SKILL.md (6478B)
1 --- 2 name: "architectural-proposals" 3 description: "How to write comprehensive architectural proposals that drive alignment before code is written" 4 domain: "architecture, product-direction" 5 confidence: "high" 6 source: "earned (2026-02-21 interactive shell proposal)" 7 tools: 8 - name: "view" 9 description: "Read existing codebase, prior decisions, and team context before proposing changes" 10 when: "Always read .squad/decisions.md, relevant PRDs, and current architecture docs before writing proposal" 11 - name: "create" 12 description: "Create proposal in docs/proposals/ with structured format" 13 when: "After gathering context, before any implementation work begins" 14 --- 15 16 ## Context 17 18 Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when: 19 - Architecture shifts invalidate existing assumptions 20 - Product direction changes require new foundation 21 - Multiple waves/milestones will be affected by a decision 22 - External dependencies (Copilot CLI, SDK APIs) change 23 24 ## Patterns 25 26 ### Proposal Structure (docs/proposals/) 27 28 **Required sections:** 29 1. **Problem Statement** — Why current state is broken (specific, measurable evidence) 30 2. **Proposed Architecture** — Solution with technical specifics (not hand-waving) 31 3. **What Changes** — Impact on existing work (waves, milestones, modules) 32 4. **What Stays the Same** — Preserve existing functionality (no regression) 33 5. **Key Decisions Needed** — Explicit choices with recommendations 34 6. **Risks and Mitigations** — Likelihood + impact + mitigation strategy 35 7. **Scope** — What's in v1, what's deferred (timeline clarity) 36 37 **Optional sections:** 38 - Implementation Plan (high-level milestones) 39 - Success Criteria (measurable outcomes) 40 - Open Questions (unresolved items) 41 - Appendix (prior art, alternatives considered) 42 43 ### Tone Ceiling Enforcement 44 45 **Always:** 46 - Cite specific evidence (user reports, performance data, failure modes) 47 - Justify recommendations with technical rationale 48 - Acknowledge trade-offs (no perfect solutions) 49 - Be specific about APIs, libraries, file paths 50 51 **Never:** 52 - Hype ("revolutionary", "game-changing") 53 - Hand-waving ("we'll figure it out later") 54 - Unsubstantiated claims ("users will love this") 55 - Vague timelines ("soon", "eventually") 56 57 ### Wave Restructuring Pattern 58 59 When a proposal invalidates existing wave structure: 60 1. **Acknowledge the shift:** "This becomes Wave 0 (Foundation)" 61 2. **Cascade impacts:** Adjust downstream waves (Wave 1, Wave 2, Wave 3) 62 3. **Preserve non-blocking work:** Identify what can proceed in parallel 63 4. **Update dependencies:** Document new blocking relationships 64 65 **Example (Interactive Shell):** 66 - Wave 0 (NEW): Interactive Shell — blocks all other waves 67 - Wave 1 (ADJUSTED): npm Distribution — shell bundled in cli.js 68 - Wave 2 (DEFERRED): SquadUI — waits for shell foundation 69 - Wave 3 (ADJUSTED): Public Docs — now documents shell as primary interface 70 71 ### Decision Framing 72 73 **Format:** "Recommendation: X (recommended) or alternatives?" 74 75 **Components:** 76 - Recommendation (pick one, justify) 77 - Alternatives (what else was considered) 78 - Decision rationale (why recommended option wins) 79 - Needs sign-off from (which agents/roles must approve) 80 81 **Example:** 82 ``` 83 ### 1. Terminal UI Library: `ink` (recommended) or alternatives? 84 85 **Recommendation:** `ink` 86 **Alternatives:** `blessed`, raw readline 87 **Decision rationale:** Component model enables testable UI. Battle-tested ecosystem. 88 89 **Needs sign-off from:** Brady (product direction), Fortier (runtime performance) 90 ``` 91 92 ### Risk Documentation 93 94 **Format per risk:** 95 - **Risk:** Specific failure mode 96 - **Likelihood:** Low / Medium / High (not percentages) 97 - **Impact:** Low / Medium / High 98 - **Mitigation:** Concrete actions (measurable) 99 100 **Example:** 101 ``` 102 ### Risk 2: SDK Streaming Reliability 103 104 **Risk:** SDK streaming events might drop messages or arrive out of order. 105 **Likelihood:** Low (SDK is production-grade). 106 **Impact:** High — broken streaming makes shell unusable. 107 108 **Mitigation:** 109 - Add integration test: Send 1000-message stream, verify all deltas arrive in order 110 - Implement fallback: If streaming fails, fall back to polling session state 111 - Log all SDK events to `.squad/orchestration-log/sdk-events.jsonl` for debugging 112 ``` 113 114 ## Examples 115 116 **File references from interactive shell proposal:** 117 - Full proposal: `docs/proposals/squad-interactive-shell.md` 118 - User directive: `.squad/decisions/inbox/copilot-directive-2026-02-21T202535Z.md` 119 - Team decisions: `.squad/decisions.md` 120 - Current architecture: `docs/architecture/module-map.md`, `docs/prd-23-release-readiness.md` 121 122 **Key patterns demonstrated:** 123 1. Read user directive first (understand the "why") 124 2. Survey current architecture (module map, existing waves) 125 3. Research SDK APIs (exploration task to validate feasibility) 126 4. Document problem with specific evidence (unreliable handoffs, zero visibility, UX mismatch) 127 5. Propose solution with technical specifics (ink components, SDK session management, spawn.ts module) 128 6. Restructure waves when foundation shifts (Wave 0 becomes blocker) 129 7. Preserve backward compatibility (squad.agent.md still works, VS Code mode unchanged) 130 8. Frame decisions explicitly (5 key decisions with recommendations) 131 9. Document risks with mitigations (5 risks, each with concrete actions) 132 10. Define scope (what's in v1 vs. deferred) 133 134 ## Anti-Patterns 135 136 **Avoid:** 137 - ❌ Proposals without problem statements (solution-first thinking) 138 - ❌ Vague architecture ("we'll use a shell") — be specific (ink components, session registry, spawn.ts) 139 - ❌ Ignoring existing work — always document impact on waves/milestones 140 - ❌ No risk analysis — every architecture has risks, document them 141 - ❌ Unbounded scope — draw the v1 line explicitly 142 - ❌ Missing decision ownership — always say "needs sign-off from X" 143 - ❌ No backward compatibility plan — users don't care about your replatform 144 - ❌ Hand-waving timelines ("a few weeks") — be specific (2-3 weeks, 1 engineer full-time) 145 146 **Red flags in proposal reviews:** 147 - "Users will love this" (citation needed) 148 - "We'll figure out X later" (scope creep incoming) 149 - "This is revolutionary" (tone ceiling violation) 150 - No section on "What Stays the Same" (regression risk) 151 - No risks documented (wishful thinking)