# Plan: Result Migration — Sub-Track 1 (Review Pass)

**Sub-track:** `result_migration_review_pass_20260617`
**Umbrella:** [`result_migration_20260616`](../../result_migration_20260616/spec.md)
**Owner:** Tier 2 Tech Lead
**Base commit:** `b6caca40` (test(theme_nerv): align alert test with kwargs call signature)
**Audit-data commit:** see `git log scripts/audit_exception_handling.py` (the audit script's most recent change is the post-report heuristic update; the 24+19 inventory is the live state)

---

## Phase 1: Setup

- [ ] **Task 1.1: Initialize the sub-track folder**
  - WHERE: `conductor/tracks/result_migration_review_pass_20260617/` (already created)
  - WHAT: `spec.md`, `plan.md`, `metadata.json`, `state.toml` (this file)
  - HOW: Read the umbrella spec; the sub-track spec mirrors the umbrella's sub-track 1 plan
  - COMMIT: `conductor(track): spec for result_migration_review_pass (sub-track 1 of 5)`
  - GIT NOTE: Sub-track 1 scope (43 sites across 11 files; 24 UNCLEAR + 19 INTERNAL_RETHROW); dependency on the umbrella

- [ ] **Task 1.2: Update `conductor/tracks.md`**
  - WHERE: `conductor/tracks.md` (after the umbrella row 6d)
  - WHAT: Add a row for sub-track 1
  - HOW: Same pattern as the umbrella row; reference the umbrella and parent audit
  - COMMIT: `conductor: register result_migration_review_pass_20260617 in tracks.md`
  - GIT NOTE: 1-sentence note pointing to the sub-track folder

---

## Phase 2: Review the 24 UNCLEAR sites (6 files)

For each site, the Tier 2 implementer reads the snippet + 2-3 lines of context and decides:
- **Compliant** — the site matches a pattern the audit script SHOULD recognize; document the pattern; add a heuristic
- **Migration-target** — the site should be converted to Result-based in sub-tracks 2-4; record the line + file + decision in the report

The 24 UNCLEAR sites are in (per the live audit JSON, 2026-06-17):

- `src/gui_2.py`: 13 sites (lines 65, 69, 684, 806, 1349, 2401, 2411, 2533, 2561, 2759, 4106, 4159, 6830)
- `src/mcp_client.py`: 4 sites (lines 126, 152, 177, 987) — BASELINE
- `src/ai_client.py`: 2 sites (lines 828, 2813) — BASELINE
- `src/app_controller.py`: 2 sites (lines 1842, 3740)
- `src/models.py`: 2 sites (lines 452, 457)
- `src/multi_agent_conductor.py`: 1 site (line 236)

- [ ] **Task 2.1: Review `src/gui_2.py` UNCLEAR sites (13)**
  - WHERE: `src/gui_2.py`
  - WHAT: For each of the 13 sites, classify compliant-or-migration
  - HOW: `manual-slop_get_file_slice` on each line; read 2-3 lines of context
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/gui_2.py UNCLEAR`
  - GIT NOTE: Per-site decisions for gui_2 UNCLEAR

- [ ] **Task 2.2: Review `src/mcp_client.py` UNCLEAR sites (4, baseline)**
  - WHERE: `src/mcp_client.py`
  - WHAT: Same as 2.1; note the baseline status (refactored 2026-06-12; remaining sites are Path C deferred work)
  - HOW: Same as 2.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/mcp_client.py UNCLEAR`
  - GIT NOTE: Per-site decisions for mcp_client UNCLEAR

- [ ] **Task 2.3: Review `src/ai_client.py` UNCLEAR sites (2, baseline)**
  - WHERE: `src/ai_client.py`
  - WHAT: Same as 2.2
  - HOW: Same as 2.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/ai_client.py UNCLEAR`
  - GIT NOTE: Per-site decisions for ai_client UNCLEAR

- [ ] **Task 2.4: Review `src/app_controller.py` UNCLEAR sites (2)**
  - WHERE: `src/app_controller.py`
  - WHAT: Same as 2.1
  - HOW: Same as 2.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/app_controller.py UNCLEAR`
  - GIT NOTE: Per-site decisions for app_controller UNCLEAR

- [ ] **Task 2.5: Review `src/models.py` UNCLEAR sites (2)**
  - WHERE: `src/models.py`
  - WHAT: Same as 2.1
  - HOW: Same as 2.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/models.py UNCLEAR`
  - GIT NOTE: Per-site decisions for models UNCLEAR

- [ ] **Task 2.6: Review `src/multi_agent_conductor.py` UNCLEAR sites (1)**
  - WHERE: `src/multi_agent_conductor.py`
  - WHAT: Same as 2.1
  - HOW: Same as 2.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/multi_agent_conductor.py UNCLEAR`
  - GIT NOTE: Per-site decisions for multi_agent_conductor UNCLEAR

---

## Phase 3: Classify the 19 INTERNAL_RETHROW sites (7 files)

For each site, classify as one of:
- **PATTERN 1** (catch + convert + raise as different type): legitimate
- **PATTERN 2** (catch + log + re-raise): legitimate
- **PATTERN 3** (catch + cleanup + re-raise): legitimate
- **Migration-target** (catch + re-raise same exception OR no good reason): queue for sub-tracks 2-4

See `conductor/code_styleguides/error_handling.md` §"Re-Raise Patterns" for the canonical pattern definitions.

The 19 INTERNAL_RETHROW sites are in (per the live audit JSON):

- `src/ai_client.py`: 6 sites (lines 277, 801, 802, 1234, 1529, 2520) — BASELINE, all `RAISE` kind
- `src/rag_engine.py`: 4 sites (lines 29, 36, 57, 75) — BASELINE
- `src/app_controller.py`: 3 sites (lines 1224, 1250, 2982) — all `RAISE` in `__getattr__` + 1 `RAISE` in `load_context_preset`
- `src/gui_2.py`: 2 sites (lines 757, 760) — both `RAISE` in `__getattr__`
- `src/api_hooks.py`: 2 sites (lines 938, 941) — 1 EXCEPT + 1 RAISE in `main`
- `src/models.py`: 1 site (line 268) — `RAISE` in `__getattr__`
- `src/warmup.py`: 1 site (line 85) — `RAISE` in `submit`

- [ ] **Task 3.1: Review `src/ai_client.py` INTERNAL_RETHROW sites (6, baseline)**
  - WHERE: `src/ai_client.py`
  - WHAT: Apply the 4 classifications to each of the 6 RAISE sites
  - HOW: For each line, read the surrounding 5-10 lines to determine if it's PATTERN 1/2/3 or migration-target
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/ai_client.py INTERNAL_RETHROW`
  - GIT NOTE: Per-site classifications for ai_client INTERNAL_RETHROW

- [ ] **Task 3.2: Review `src/rag_engine.py` INTERNAL_RETHROW sites (4, baseline)**
  - WHERE: `src/rag_engine.py`
  - WHAT: Same as 3.1; lines 29+36 are in `_get_sentence_transformers` (lazy import pattern), lines 57+75 are in `embed`
  - HOW: Same as 3.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/rag_engine.py INTERNAL_RETHROW`
  - GIT NOTE: Per-site classifications for rag_engine INTERNAL_RETHROW

- [ ] **Task 3.3: Review `src/app_controller.py` INTERNAL_RETHROW sites (3)**
  - WHERE: `src/app_controller.py`
  - WHAT: Same as 3.1; lines 1224+1250 are in `__getattr__` (defer-not-catch guard)
  - HOW: Same as 3.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/app_controller.py INTERNAL_RETHROW`
  - GIT NOTE: Per-site classifications for app_controller INTERNAL_RETHROW

- [ ] **Task 3.4: Review `src/gui_2.py` INTERNAL_RETHROW sites (2)**
  - WHERE: `src/gui_2.py`
  - WHAT: Same as 3.1; lines 757+760 are in `__getattr__` (defer-not-catch guard, likely)
  - HOW: Same as 3.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/gui_2.py INTERNAL_RETHROW`
  - GIT NOTE: Per-site classifications for gui_2 INTERNAL_RETHROW

- [ ] **Task 3.5: Review `src/api_hooks.py` INTERNAL_RETHROW sites (2)**
  - WHERE: `src/api_hooks.py`
  - WHAT: Same as 3.1; lines 938+941 in `main`
  - HOW: Same as 3.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/api_hooks.py INTERNAL_RETHROW`
  - GIT NOTE: Per-site classifications for api_hooks INTERNAL_RETHROW

- [ ] **Task 3.6: Review `src/models.py` INTERNAL_RETHROW site (1)**
  - WHERE: `src/models.py`
  - WHAT: Same as 3.1; line 268 in `__getattr__`
  - HOW: Same as 3.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/models.py INTERNAL_RETHROW`
  - GIT NOTE: Per-site classifications for models INTERNAL_RETHROW

- [ ] **Task 3.7: Review `src/warmup.py` INTERNAL_RETHROW site (1)**
  - WHERE: `src/warmup.py`
  - WHAT: Same as 3.1; line 85 in `submit`
  - HOW: Same as 3.1
  - COMMIT: `docs(track): result_migration_review_pass decisions for src/warmup.py INTERNAL_RETHROW`
  - GIT NOTE: Per-site classifications for warmup INTERNAL_RETHROW

---

## Phase 4: Update the audit script's heuristics

For each site that turned out to be compliant (a common pattern the script doesn't recognize), add a heuristic to `_classify_except` or `_classify_raise` in `scripts/audit_exception_handling.py`.

- [ ] **Task 4.1: Add heuristics for the 5-10 most common compliant patterns**
  - WHERE: `scripts/audit_exception_handling.py`
  - WHAT: Add new classification logic for the patterns the review pass found to be compliant
  - HOW: Use the AST inspection patterns the script already has; add to the `_classify_except` / `_classify_raise` functions
  - SAFETY: The script is a static analyzer; the changes don't affect runtime behavior. Run the audit before and after each heuristic change to verify the new heuristic doesn't misclassify existing sites.
  - COMMIT: `feat(scripts): add heuristics to audit_exception_handling for review pass patterns`
  - GIT NOTE: Heuristics added; per-site rationale

- [ ] **Task 4.2: Verify the updated classification**
  - WHERE: `scripts/audit_exception_handling.py`
  - WHAT: Re-run the audit; the UNCLEAR count should drop to 0 (or close to it; ±2 acceptable per the spec); the INTERNAL_RETHROW count should drop to whatever the 3 legitimate patterns don't cover
  - HOW: `uv run python scripts/audit_exception_handling.py --json` and compare before/after counts
  - SAFETY: If the new heuristic misclassifies a known site, the audit will show a different breakdown — re-check the per-site decisions in the report
  - COMMIT: `docs(track): verify audit heuristic update` (only if a doc change is needed; otherwise rolled into 4.1)

---

## Phase 5: Report

- [ ] **Task 5.1: Write the review pass report**
  - WHERE: `docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md`
  - WHAT: Per-site decision table (43 rows); updated migration scope for the later sub-tracks; updated audit script heuristics; per-sub-track site-count adjustments
  - HOW: Use the format of the `EXCEPTION_HANDLING_AUDIT_20260616.md` report
  - COMMIT: `docs(report): add result_migration_review_pass report`
  - GIT NOTE: Summary of the review pass + updated migration scope

- [ ] **Task 5.2: Update the umbrella spec's per-sub-track plan**
  - WHERE: `conductor/tracks/result_migration_20260616/spec.md` (the per-sub-track plan section)
  - WHAT: Reflect the updated migration scope (some UNCLEAR sites may be compliant; the site count per sub-track changes)
  - HOW: Edit the spec; commit as a docs update
  - COMMIT: `docs(track): update result_migration_20260616 with post-review scope`
  - GIT NOTE: 1-sentence note about the scope change

---

## Phase 6: Verification

- [ ] **Task 6.1: Verify the updated audit script**
  - WHERE: `scripts/audit_exception_handling.py`
  - WHAT: Re-run with `--by-size`; verify the UNCLEAR count is now 0 (±2); verify the per-bucket totals reflect the updated scope
  - HOW: `uv run python scripts/audit_exception_handling.py --by-size`
  - COMMIT: rolled into 5.1 (the report captures the verification command + output)

- [ ] **Task 6.2: Verify the test pass count is unchanged**
  - WHERE: `tests/`
  - WHAT: This sub-track is informational; the test pass count should stay at 1288 + 4 + 0
  - HOW: `uv run python scripts/run_tests_batched.py` (the tier-2 standard, per `conductor/workflow.md` §"Tier 2 Autonomous Sandbox")
  - NOTE: The batched runner is the canonical verification for tier-2; isolated `pytest` is forbidden per the Isolated-Pass Verification Fallacy rule
  - COMMIT: rolled into 5.1

- [ ] **Task 6.3: Mark the sub-track as completed**
  - WHERE: `conductor/tracks/result_migration_review_pass_20260617/metadata.json` + `state.toml`, `conductor/tracks.md`
  - WHAT: Update `status: active → completed`; `current_phase: "complete"`
  - HOW: Edit the files; commit
  - COMMIT: `conductor(track): mark result_migration_review_pass_20260617 as completed`
  - GIT NOTE: 1-sentence note

---

## Risks at the Plan Level

| Risk | Mitigation |
|---|---|
| The review pass reveals more UNCLEAR sites than expected (the heuristics miss patterns) | Task 4.2 verifies the post-heuristic UNCLEAR count is ~0; if not, iterate |
| The user disagrees with a classification on a disputed case | The plan defers to the user as the final arbiter (per the spec §"Notes for the Tier 2 Implementer") |
| Audit script updates introduce regressions | Task 4.1 includes a safety step: run the audit before and after each heuristic change; compare counts |
| The post-review scope changes invalidate the umbrella spec's per-sub-track plan | Task 5.2 updates the umbrella spec with the new scope |
| The test pass count drops unexpectedly | Task 6.2 catches this; investigate the test failure per the standard process |

---

## Verification Snapshot (capture in the report)

After the review pass + heuristic update, capture in `docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md`:

- `audit_exception_handling.py` count before: 24 UNCLEAR + 19 INTERNAL_RETHROW = 43
- `audit_exception_handling.py` count after: 0 UNCLEAR (±2) + N INTERNAL_RETHROW (where N = total - 3-pattern-matches)
- Per-site decision table (43 rows)
- Per-file migration-target delta (the change in sub-tracks 2-4 site counts)
- Audit script heuristics added (count + 1-line summary per heuristic)
