docs(tracks): strip day estimates from exception_handling_audit + rag_test_failures (Tier 1 rule)

This commit is contained in:
ed
2026-06-16 10:16:17 -04:00
parent 4c0b19b4db
commit ed6602274d
5 changed files with 36 additions and 34 deletions
@@ -149,12 +149,13 @@
}, },
"estimated_effort": { "estimated_effort": {
"phase_1": "30 min - spec + plan + metadata + tracks.md", "method": "Scope (per conductor/workflow.md §Tier 1 Track Initialization Rules). NO day estimates.",
"phase_2": "1-2 hours - audit script + verifications (script already drafted in spec phase)", "phase_1": "5 artifacts (spec + plan + metadata + tracks.md update)",
"phase_3": "1-2 hours - 5 doc/codestyle updates (small additions)", "phase_2": "792-line audit script + 4 verifications",
"phase_4": "30 min - final report + metadata update", "phase_3": "5 doc/codestyle updates + 1 product-guidelines cross-reference",
"phase_5": "5 min - user manual verification (the user reviews the report)", "phase_4": "370-line audit report + metadata update",
"total": "0.5 day Tier 2 work (2-4 hours)" "phase_5": "User manual verification (the user reviews the report)",
"total": "~800 lines of new artifacts; 9 atomic commits; all with git notes"
}, },
"risk_register": { "risk_register": {
@@ -5,7 +5,7 @@
**Priority:** B (informational; precedes the user's planned implementation refactor of the migration-target files) **Priority:** B (informational; precedes the user's planned implementation refactor of the migration-target files)
**Owner:** Tier 2 Tech Lead **Owner:** Tier 2 Tech Lead
**Type:** audit + documentation (no production code changes; no behavior change) **Type:** audit + documentation (no production code changes; no behavior change)
**Estimated effort:** 0.5 day Tier 2 work (2-4 hours) **Scope:** ~800 lines of new artifacts (792-line audit script + 5 doc/codestyle updates + 370-line report)
**Parent tracks:** `data_oriented_error_handling_20260606` (shipped 2026-06-12), `ai_loop_regressions_20260614`, `doeh_test_thinking_cleanup_20260615`, `public_api_migration_and_ui_polish_20260615`, `rag_test_failures_20260615` (all shipped 2026-06-15) **Parent tracks:** `data_oriented_error_handling_20260606` (shipped 2026-06-12), `ai_loop_regressions_20260614`, `doeh_test_thinking_cleanup_20260615`, `public_api_migration_and_ui_polish_20260615`, `rag_test_failures_20260615` (all shipped 2026-06-15)
**Sibling tracks:** `data_structure_strengthening_20260606` (planned, parallel), `mcp_architecture_refactor_20260606` (planned, depends on convention being complete) **Sibling tracks:** `data_structure_strengthening_20260606` (planned, parallel), `mcp_architecture_refactor_20260606` (planned, depends on convention being complete)
@@ -147,12 +147,13 @@
}, },
"estimated_effort": { "estimated_effort": {
"phase_1": "1-2 hours - investigation + reproducing test", "method": "Scope (per conductor/workflow.md §Tier 1 Track Initialization Rules). NO day estimates.",
"phase_2": "1-3 hours - fix (dependent on Phase 1 finding)", "phase_1": "1 task: investigation + reproducing test",
"phase_3": "30 min - full + batched test verification", "phase_2": "1 task: fix (2 production lines + 3 new unit tests)",
"phase_4": "15 min - docs update (conditional)", "phase_3": "1 task: full + batched test verification",
"phase_5": "15 min - metadata + tracks.md", "phase_4": "1 task: docs update (conditional)",
"total": "0.5-1 day Tier 2 work (4-8 hours)" "phase_5": "1 task: metadata + tracks.md",
"total": "5 phases, ~10 tasks, 4 atomic commits, all with git notes"
}, },
"risk_register": { "risk_register": {
@@ -179,7 +180,7 @@
"R5_takes_longer_than_estimated": { "R5_takes_longer_than_estimated": {
"likelihood": "low", "likelihood": "low",
"impact": "low", "impact": "low",
"mitigation": "Even 2 days is acceptable; user's overall plan is 2 more tracks before data structure." "mitigation": "The spec is a guide, not a contract. The Tier 2 reports scope growth; the user decides whether to expand the track or defer to a follow-up."
} }
}, },
@@ -19,7 +19,7 @@ Per the project rule (see `AGENTS.md` "Critical Anti-Patterns"), per-task atomic
--- ---
## Phase 1: Investigation + reproducing test (1-2 hours) ## Phase 1: Investigation + reproducing test
**Focus:** Find the exact location of the `.get(None)` call. The spec §1.4 lists 5 candidate sites; the investigation will narrow to 1. **Focus:** Find the exact location of the `.get(None)` call. The spec §1.4 lists 5 candidate sites; the investigation will narrow to 1.
@@ -57,7 +57,7 @@ Per the project rule (see `AGENTS.md` "Critical Anti-Patterns"), per-task atomic
--- ---
## Phase 2: Fix (1-3 hours) ## Phase 2: Fix
**Focus:** Fix the root cause found in Phase 1. The fix is dependent on what the investigation reveals. **Focus:** Fix the root cause found in Phase 1. The fix is dependent on what the investigation reveals.
@@ -95,7 +95,7 @@ Per the project rule (see `AGENTS.md` "Critical Anti-Patterns"), per-task atomic
--- ---
## Phase 3: Full test suite + batched verification (30 min) ## Phase 3: Full test suite + batched verification
**Focus:** Ensure no regression in the broader test suite. **Focus:** Ensure no regression in the broader test suite.
@@ -117,7 +117,7 @@ Per the project rule (see `AGENTS.md` "Critical Anti-Patterns"), per-task atomic
--- ---
## Phase 4: Docs update (15 min) ## Phase 4: Docs update
**Focus:** Document the fix in `docs/guide_rag.md` (if it exists). **Focus:** Document the fix in `docs/guide_rag.md` (if it exists).
@@ -137,7 +137,7 @@ Per the project rule (see `AGENTS.md` "Critical Anti-Patterns"), per-task atomic
--- ---
## Phase 5: Metadata + tracks.md (15 min) ## Phase 5: Metadata + tracks.md
**Focus:** Mark the track complete in the project registry. **Focus:** Mark the track complete in the project registry.
@@ -161,8 +161,8 @@ Per the project rule (see `AGENTS.md` "Critical Anti-Patterns"), per-task atomic
## Summary ## Summary
- **Total tasks:** ~10 (across 5 phases) - **Total tasks:** ~10 (across 5 phases)
- **Total atomic commits:** ~5-7 (1 diagnostic + 1 reproducing test + 1 fix + 1 diag removal + 1 defensive guard + 1 docs + 1 metadata) - **Total atomic commits:** 4 (1 fix + 1 docs + 1 metadata + 1 final-state)
- **Total estimated effort:** 0.5-1 day Tier 2 work (4-8 hours) - **All commits have git notes**
- **Dependencies:** None (independent track) - **Dependencies:** None (independent track)
- **Out of scope (deferred):** `send_result``send` mass rename (user's manual refactor); 23 lower-impact weak-type files (data_structure_strengthening); live_gui_mock_injection infrastructure - **Out of scope (deferred):** `send_result``send` mass rename (user's manual refactor); 23 lower-impact weak-type files (data_structure_strengthening); live_gui_mock_injection infrastructure
@@ -5,7 +5,7 @@
**Priority:** A (foundational; precedes `data_structure_strengthening_20260606` and the user's planned `send_result``send` mass rename) **Priority:** A (foundational; precedes `data_structure_strengthening_20260606` and the user's planned `send_result``send` mass rename)
**Owner:** Tier 2 Tech Lead **Owner:** Tier 2 Tech Lead
**Type:** bugfix + test_fix **Type:** bugfix + test_fix
**Estimated effort:** 0.5-1 day Tier 2 work (4-8 hours) **Scope:** 3 test failures (tier-3 live_gui RAG tests) + 1 production bug in 2 lines + 3 new unit tests
**Parent tracks:** `data_oriented_error_handling_20260606` (shipped 2026-06-12), `ai_loop_regressions_20260614` (shipped 2026-06-15), `doeh_test_thinking_cleanup_20260615` (shipped 2026-06-15), `public_api_migration_and_ui_polish_20260615` (shipped 2026-06-15) **Parent tracks:** `data_oriented_error_handling_20260606` (shipped 2026-06-12), `ai_loop_regressions_20260614` (shipped 2026-06-15), `doeh_test_thinking_cleanup_20260615` (shipped 2026-06-15), `public_api_migration_and_ui_polish_20260615` (shipped 2026-06-15)
--- ---
@@ -263,11 +263,11 @@ If the implementer can't find the bug from the error message alone:
This is a small bug-fix track. The phases are simple: This is a small bug-fix track. The phases are simple:
1. **Phase 1: Investigation + reproducing test (1-2 hours)** 1. **Phase 1: Investigation + reproducing test**
2. **Phase 2: Fix (1-3 hours)** 2. **Phase 2: Fix**
3. **Phase 3: Full test suite + batched verification (30 min)** 3. **Phase 3: Full test suite + batched verification**
4. **Phase 4: Docs update (15 min)** 4. **Phase 4: Docs update**
5. **Phase 5: Metadata + tracks.md (15 min)** 5. **Phase 5: Metadata + tracks.md**
The order doesn't matter much (it's all one fix); the implementer can iterate between Phase 1 and 2 as needed. The order doesn't matter much (it's all one fix); the implementer can iterate between Phase 1 and 2 as needed.
@@ -302,7 +302,7 @@ The order doesn't matter much (it's all one fix); the implementer can iterate be
| **R2** | The bug is in a hard-to-reach code path (deep in IO pool worker) | Medium | Medium | Add diagnostic traceback in the except clause; capture the actual error site; document in the commit message. | | **R2** | The bug is in a hard-to-reach code path (deep in IO pool worker) | Medium | Medium | Add diagnostic traceback in the except clause; capture the actual error site; document in the commit message. |
| **R3** | The fix is in the test (subprocess state pollution) not the production code | Low | Low | If the fix is in the test, document this in the commit message. Consider adding a teardown reset in the test. | | **R3** | The fix is in the test (subprocess state pollution) not the production code | Low | Low | If the fix is in the test, document this in the commit message. Consider adding a teardown reset in the test. |
| **R4** | The fix introduces a regression in `test_rag_engine_ready_status_bug.py` | Low | Medium | Run the full RAG test suite after the fix. | | **R4** | The fix introduces a regression in `test_rag_engine_ready_status_bug.py` | Low | Medium | Run the full RAG test suite after the fix. |
| **R5** | The implementation takes longer than estimated (1 day) | Low | Low | This is a 0.5-1 day track; even 2 days is acceptable. The user's overall plan is to do 2 more tracks (this + a `send_result``send` rename) before the data structure track. | | **R5** | The implementation is larger than the 2-line fix suggested by the spec | Low | Low | The spec is a guide, not a contract. If the fix is larger (e.g., a larger refactor is needed), the Tier 2 reports and the user decides whether to expand scope. The user's overall plan is 2 more tracks (this + a `send_result``send` rename) before the data structure track. |
--- ---
@@ -331,13 +331,13 @@ The track is DONE when **ALL** of the following are true:
**No external blockers.** This track can start immediately after the Tier 1 review approves the spec. **No external blockers.** This track can start immediately after the Tier 1 review approves the spec.
**Execution order (the plan):** **Execution order (the plan):**
1. Phase 1: Investigation + reproducing test (1-2 hours) 1. Phase 1: Investigation + reproducing test
2. Phase 2: Fix (1-3 hours) 2. Phase 2: Fix
3. Phase 3: Full test suite + batched verification (30 min) 3. Phase 3: Full test suite + batched verification
4. Phase 4: Docs update (15 min) 4. Phase 4: Docs update
5. Phase 5: Metadata + tracks.md (15 min) 5. Phase 5: Metadata + tracks.md
**Total:** 0.5-1 day Tier 2 work (4-8 hours) **Total:** 5 phases, ~10 tasks, 4 atomic commits (1 fix + 1 docs + 1 metadata + 1 final-state); all with git notes.
**Followed by:** the user can do the `send_result``send` mass rename themselves, then start `data_structure_strengthening_20260606` track. **Followed by:** the user can do the `send_result``send` mass rename themselves, then start `data_structure_strengthening_20260606` track.