Chapter 13: Writing tasks.md
Learning Objectives
Translate the spec into executable "groups" – the smallest units for dispatch.
Core Structure of the Task List
## Chapter 13: 1. Group Name
- [ ] 1.1 Task Description
- [ ] 1.2 Task Description
- [ ] 1.3 Task Description
## Chapter 13: 2. Group Name
- [ ] 2.1 ...
Two strict rules:
## N.Numbered headings define groups (these are dispatch boundaries).- [ ]Checkboxes are status markers (developers change to- [x]upon completion).
Group Granularity
flowchart LR
Bad1["Too Coarse:
1 group, 30 tasks"] --> ProB1["Context explosion
with each dispatch"]
Bad2["Too Fine:
1 group per task"] --> ProB2["50+ dispatches
High orchestration cost"]
Good["Just Right:
3~7 tasks / group"] --> ProG["10-15 dispatches
Clear workload per dispatch"]
style Bad1 fill:#ffcdd2
style Bad2 fill:#ffcdd2
style Good fill:#c8e6c9→ For the MVP phase, break down into 3-7 tasks per group.
Group to Requirement Mapping
It's not 1:1, but many-to-many:
Group 3 (TTS Backend) ─┬→ Requirement: TTS Voiceover Generation
└→ Partial: Markdown Parsing (narration field)
Group 7 (Orchestrator) ─┬→ Requirement: Synchronization Strategy
├→ Requirement: Pause on Error During Recording (Partial)
└→ Partial: Terminal Control
→ A group can involve multiple Requirements, and a Requirement can be implemented by multiple groups.
Task "Definition of Done"
Each task must be verifiable with a yes/no answer. Template:
✅ "Implement the TTSBackend abstract class with method synthesize(text) -> Path"
→ Check if the class exists in the code, and if the method signature is correct. This can be immediately verified.
❌ "Improve the TTS module"
→ What does "improve" mean? Cannot be verified.
❌ "Improve code quality"
→ Same as above, vague.
Example: 13 Groups for doc2video
flowchart TB
G1["1. Project Scaffolding
(4 tasks)"] --> G2["2. Markdown Parsing
(5 tasks)"]
G2 --> G3["3. TTS Backend
(4 tasks)"]
G2 --> G4["4. Tmux Terminal Control
(6 tasks)"]
G3 --> G7["7. Orchestrator
(5 tasks) TDD"]
G4 --> G7
G2 --> G5["5. Document Panel
(5 tasks)"]
G5 --> G7
G4 --> G6["6. Screen Recording
(5 tasks)"]
G6 --> G7
G7 --> G8["8. Dry-run Pre-check
(5 tasks)"]
G7 --> G9["9. Pause on Error
(7 tasks) TDD"]
G7 --> G10["10. Video Synthesis
(4 tasks)"]
G10 --> G11["11. Report Output
(3 tasks)"]
G11 --> G12["12. CLI Integration
(5 tasks)"]
G12 --> G13["13. Documentation & Examples
(3 tasks)"]
style G7 fill:#fff9c4
style G9 fill:#fff9c4→ Yellow highlights indicate TDD groups (write tests first, then implement).
Sorting Rules
✅ Upstream modules first (Scaffolding → Parsing → TTS / Terminal → Orchestration)
✅ Independent, parallelizable groups placed adjacently (TTS and Tmux are mutually independent)
✅ Integration groups last (CLI Integration, E2E Examples)
✅ Complex TDD groups clearly marked
❌ Do not sort by "workload size"
❌ Do not place verification-type groups first
TDD Marking
Some groups require tests to be written first (H3 rule):
## Chapter 13: 7. Orchestrator (Synchronization Strategy) <!-- TDD -->
- [ ] 7.1 ...
- [ ] 7.2 ...
The <!-- TDD --> comment tells dev.md to dispatch a tester to write failing tests before dispatching a developer.
Anti-patterns
❌ One group with 20+ tasks Too large
❌ One group with 1 task Too granular
❌ Cross-group circular dependencies Deadlock
❌ Task not verifiable Cannot determine completion
❌ Task lists "implement" verb but doesn't specify what No contract
What You Can Do Now
- Break down the spec into 5-15 groups.
- Ensure each task can be verified with a yes/no answer upon completion.
- Mark complex groups that require TDD.
- Draw a dependency graph of the groups.