Chapter 9: Decisions Are Trade-offs
Learning Objectives
Learn to use "decision matrix" thinking to transform "I want to do X" into "I accept the cost of Y for X."
What is a "Decision"?
For any task that seems to have only one way of doing it, a closer look reveals 2-5 approaches, each with its own trade-offs.
This is precisely what will be documented in the subsequent design.md.
Fixed Template for Decision Matrix
| Option | Pros | Cons | Recommended? |
|---|---|---|---|
| A | ... | ... | ✓/✗ |
| B | ... | ... | ✓/✗ |
| C | ... | ... | ✓/✗ |
Every decision should be evaluated using this table.
8 Real Decisions Made for doc2video
flowchart TB
D1["D1: Terminal Control
tmux vs subprocess vs AppleScript"] --> R1["Choose tmux"]
D2["D2: Screen Recording
Fullscreen vs Window Area"] --> R2["Choose Fullscreen"]
D3["D3: TTS
say vs edge-tts vs OpenAI"] --> R3["Choose edge-tts"]
D4["D4: Documentation Panel
React vs Pure HTML+WS vs Electron"] --> R4["Choose Pure HTML+WS"]
D5["D5: Synchronization
Read then Type vs Read and Type Simultaneously"] --> R5["Choose Read then Type"]
D6["D6: Error Handling
AI Auto-fix vs Pause and Ask"] --> R6["Choose Pause and Ask"]
D7["D7: Markdown Protocol
Strict DSL vs Natural Markdown"] --> R7["Choose Natural + :::manual container"]
D8["D8: Language
Python vs Node vs Rust"] --> R8["Choose Python"]
style R1 fill:#c8e6c9
style R2 fill:#c8e6c9
style R3 fill:#c8e6c9
style R4 fill:#c8e6c9
style R5 fill:#c8e6c9
style R6 fill:#c8e6c9
style R7 fill:#c8e6c9
style R8 fill:#c8e6c9Each item corresponds to a decision matrix. For example, D5:
| Option | Pros | Cons | Recommended |
|---|---|---|---|
| Read then Type | Easy to implement, easy for beginners to understand | Less flexible than a human lecturer | ✓ |
| Read and Type Simultaneously | Natural, like a human | Reactive scheduling hell, uncontrollable command execution length | ✗ (Not for MVP) |
→ "Read then Type" is hardcoded by D5. Three months later, if any agent wants to "Read and Type Simultaneously," a reviewer will reject it based on D5. This is the process of solidifying decisions into constraints.
3 Categories of Decisions
flowchart LR
All["All Decisions"] --> Tech["Technical Decisions
(Which libraries/architecture to use)"]
All --> Scope["Scope Decisions
(What to do/not to do)"]
All --> Process["Process Decisions
(How to collaborate)"]
Tech --> Tex["D1 D2 D3 D4 D8"]
Scope --> Scx["Non-Goals List"]
Process --> Prx["D5 D6 D7"]Anti-Patterns: Avoiding Pseudo-Decisions
❌ "We use the most advanced technology" ← Not a decision, it's a slogan
❌ "We'll decide later" ← Postponing is giving up
❌ "Choose the best one" ← Doesn't state "what criteria"
❌ "Anything works" ← There are always trade-offs; no explanation means no thought
✅ "Choose X because A is more important, accepting the cost of B which is inferior to other options"
Decision Writing Template
Each decision in design.md should be written as follows:
### D5. Synchronization Strategy: Read then Type
**Choose**: Each step follows a strict sequence — TTS plays completely → command typing → wait for command completion → next step
**Why**:
- Degrades the "reactive real-time scheduling" problem to "linear playback"
- Consistent with a beginner's understanding: "first listen, then watch it being done"
- Does not rely on precise alignment of voiceover/command duration
**Trade-offs**: Cannot perform advanced "read and type simultaneously" demonstrations; this is an experience explicitly abandoned for the MVP.
→ A three-part structure: What was chosen / Why / What was traded off.
What You Can Do Now
- Write at least 5 project decisions that include "trade-offs."
- Use a decision matrix to help yourself (or an explore agent) make choices.
- Identify pseudo-decisions (slogans, postponements, vagueness).
In the next chapter, we will use /opsx:propose to formally implement these decisions as change artifacts.