@@ -1,5 +1,8 @@
11 # Zoea Nova Development Workflow
22
3+**Version:** 1.0
4+**Last updated:** 2026-02-07
5+
36 ## Purpose
47
58 This document defines the standard workflow for complex refactoring and architectural changes in Zoea Nova. It codifies the process used successfully for the nudge-to-encouragement system migration (commit 82df0ce, -785 lines, 11 agents coordinated).
@@ -19,6 +22,7 @@ Do NOT use for:
1922 - Documentation-only changes
2023 - Dependency updates
2124 - Configuration tweaks
25+- You aren't confident in the approach
2226
2327 ---
2428
@@ -28,12 +32,17 @@ Do NOT use for:
2832
2933 **Goal:** Create single source of truth before touching code.
3034
35+**Estimated time:** 30-60 minutes
36+
37+**Abort if:** Can't define clear truth table after 90 minutes (problem too complex/unclear)
38+
3139 **Steps:**
3240
3341 1. **Analyze the problem**
3442 - What's broken or needs changing?
3543 - What's the root cause?
3644 - What are the constraints?
45+ - How is it expected to work (do we have an existing truth table in our architecture: `documentation/architecture`?)
3746
3847 2. **Create truth table**
3948 - Document all possible states
@@ -66,7 +75,14 @@ Do NOT use for:
6675
6776 **Goal:** Execute changes efficiently using coordinated agent fleet.
6877
69-**Minimum agents:** 3 (recommended: 5-6 for large changes)
78+**Estimated time:** 30-90 minutes (depending on agent count and complexity)
79+
80+**Agent count by change size:**
81+- Small refactor (5-10 files): 3 agents minimum
82+- Medium refactor (10-20 files): 5-6 agents recommended
83+- Large refactor (20+ files): 6-8 agents, consider splitting into sub-workflows
84+
85+**Abort if:** >50% agents report blocking dependencies (task breakdown needs revision)
7086
7187 **Steps:**
7288
@@ -87,6 +103,8 @@ Do NOT use for:
87103 - Use task tool with clear instructions
88104 - Reference the truth table document
89105 - Specify what NOT to change (avoid conflicts)
106+ - Use separate git branches per agent if changes overlap
107+ - Ask for test coverage when applicable
90108 - Request specific deliverables (summary with line numbers)
91109
92110 3. **Monitor agent completion**
@@ -104,6 +122,10 @@ Do NOT use for:
104122
105123 **Goal:** Verify agent work integrates correctly and matches truth table.
106124
125+**Estimated time:** 20-40 minutes
126+
127+**Abort if:** >20 compilation errors after integration (indicates fundamental design issue)
128+
107129 **Steps:**
108130
109131 1. **Check for conflicts**
@@ -112,6 +134,10 @@ Do NOT use for:
112134 - Check for missing dependencies
113135
114136 2. **Verify truth table compliance**
137+ - Use Grep tool to find each state transition
138+ - Trace code path for each scenario
139+ - Run targeted tests for each row
140+ - Document verification in checklist
115141 - For each row in truth table:
116142 - Find corresponding code
117143 - Verify behavior matches spec
@@ -143,7 +169,11 @@ Do NOT use for:
143169
144170 **Goal:** Find issues the first agent pass missed.
145171
146-**Minimum review agents:** 3 (independent perspectives)
172+**Estimated time:** 30-45 minutes
173+
174+**Review agents:** 3-5 (3 minimum, 5 for large changes, independent perspectives)
175+
176+**Abort if:** Review agents find architectural flaws (not bugs) - indicates design needs revision
147177
148178 **Steps:**
149179
@@ -180,19 +210,26 @@ Do NOT use for:
180210
181211 **Goal:** Implement fixes for issues found in regression analysis.
182212
213+**Estimated time:** 20-60 minutes (depends on issue complexity)
214+
183215 **Approach:** Multiple agents with different solutions (if complex)
184216
217+**Abort if:** All 3 fix agents fail to solve issue (problem needs redesign)
218+
185219 **Steps:**
186220
187221 1. **For complex fixes:**
188222 - Launch 3 agents with same requirements
189223 - Each agent implements independent solution
190224 - Compare approaches:
191- - Code simplicity
225+ - Truth table compliance (eliminates non-compliant)
226+ - Code simplicity (prefer simpler)
227+ - Test coverage (prefer better tested)
192228 - Performance
193229 - Maintainability
194230 - Risk level
195- - Choose best solution or merge ideas
231+ - Choose best solution (ask user if tied)
232+ - Never merge incompatible approaches
196233
197234 2. **For simple fixes:**
198235 - Implement directly
@@ -214,6 +251,10 @@ Do NOT use for:
214251
215252 **Goal:** Get user approval and create clean commit history.
216253
254+**Estimated time:** 15-30 minutes
255+
256+**Abort if:** User finds critical missing functionality (scope was incomplete)
257+
217258 **Steps:**
218259
219260 1. **Present summary**
@@ -253,13 +294,22 @@ Do NOT use for:
253294
254295 A successful workflow execution should achieve:
255296
297+**Process metrics:**
298+- Phase 1 completion: <90 minutes
299+- Agent coordination: <3 conflicts requiring manual merge
300+- Review findings: <5 critical issues found
301+- Fix iterations: <2 rounds needed
302+- Total time: <4 hours for medium refactor
303+
304+**Quality metrics:**
256305 1. **Correctness:** All truth table scenarios verified in code
257306 2. **Completeness:** No missing edge cases or half-implemented features
258-3. **Test coverage:** All new behavior has tests, obsolete tests removed
307+3. **Test coverage:** No decrease from baseline, all new behavior has tests
259308 4. **Documentation:** Truth table doc created, outdated comments cleaned
260-5. **Code quality:** Net negative lines (removed complexity)
261-6. **Build status:** All tests passing, clean compilation
262-7. **Efficiency:** Parallel agents complete in fraction of sequential time
309+5. **Code quality:** Net negative lines preferred (removed complexity)
310+6. **Build status:** All tests passing, zero warnings
311+7. **User approval:** First-try acceptance
312+8. **Efficiency:** Parallel agents complete in fraction of sequential time
263313
264314 ---
265315
@@ -285,6 +335,49 @@ A successful workflow execution should achieve:
285335
286336 ---
287337
338+## Handling Scope Changes
339+
340+**If scope changes during Phase 1-2:**
341+- STOP all agents
342+- Update truth table
343+- Get user re-approval
344+- Restart from Phase 2
345+
346+**If scope changes during Phase 3-5:**
347+- Document new scope in TODO
348+- Complete current workflow
349+- Start new workflow for additional scope
350+
351+**Never:** Mix scope changes into in-flight workflow
352+
353+---
354+
355+## Rollback Procedure
356+
357+**If workflow fails mid-execution:**
358+
359+1. **Assess damage:**
360+ - Run `git status` to see uncommitted changes
361+ - Run `git diff --stat` to see scope
362+ - Check if any agents are still running
363+
364+2. **Clean rollback:**
365+ - `git restore .` (discard all changes)
366+ - `git clean -fd` (remove untracked files)
367+ - Verify with `make build && make test`
368+
369+3. **Document failure:**
370+ - Add to KNOWN_ISSUES.md
371+ - Note what went wrong
372+ - Note what was learned
373+
374+4. **Restart decision:**
375+ - If truth table was wrong: Fix table, restart Phase 1
376+ - If agent coordination failed: Adjust task breakdown, restart Phase 2
377+ - If architectural flaw found: Escalate to user, new design needed
378+
379+---
380+
288381 ## Tool Usage
289382
290383 ### Agent Coordination
@@ -408,33 +501,15 @@ Use this checklist for each workflow execution:
408501
409502 ## Workflow Evolution
410503
411-This workflow will evolve based on experience. Future improvements:
504+This workflow will evolve based on experience. After using this workflow multiple times to build confidence in the process, consider:
412505
413506 - [ ] Add metrics tracking (agent count, time per phase, bugs found)
414507 - [ ] Refine agent task templates (reusable prompts)
415-- [ ] Optimize agent count (minimum effective team size)
416508 - [ ] Improve review agent focus areas (coverage matrix)
417509 - [ ] Streamline fix agent comparison (scoring rubric)
510+- [ ] Create decision tree for when to use which phase
418511
419512 ---
420513
421-## Notes for Revision
422-
423-**User requested:** Review and refine this workflow for general use
424-
425-**Questions to address:**
426-- Optimal agent count per phase?
427-- How to handle mid-flight scope changes?
428-- When to abort and restart vs push through?
429-- How to handle conflicting agent solutions?
430-- Metrics for "is this working well"?
431-
432-**Future additions:**
433-- Phase timing guidelines (how long should each phase take?)
434-- Agent prompt templates for common tasks
435-- Decision tree for when to use which phase
436-- Rollback procedure if workflow fails mid-execution
437-
438----
439-
440-Last updated: 2026-02-07
514+**Version:** 1.0
515+**Last updated:** 2026-02-07