ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity
Files
db7d94de886eb8246fac5e2b66d33af2f6e032a1
manual_slop/conductor/tracks/exception_handling_audit_20260616/plan.md
T

12 KiB
Raw Blame History

Plan: Exception Handling Audit Track

Track: exception_handling_audit_20260616 Date: 2026-06-16 Owner: Tier 2 Tech Lead Base commit: ba043630 (conductor(track): mark rag_test_failures_20260615 as completed) Final commit: (this track's last commit)

Phase 1: Spec + Plan + Metadata (Setup)

Focus: Establish the track artifacts. The audit script and the doc updates come in later phases.

  • Task 1.1: Write spec.md (per spec template)

    • WHERE: conductor/tracks/exception_handling_audit_20260616/spec.md
    • WHAT: 9-section spec with TL;DR, current state audit, 5 gaps, 10-category classification taxonomy, 5 doc-update sections, 9 verification criteria, 5 risks
    • HOW: Follow the spec template from conductor/workflow.md; use 1-space indentation; no comments
    • SAFETY: None (track artifact, not code)
    • COMMIT: conductor(track): spec for exception_handling_audit_20260616 (audit + doc clarification)
    • GIT NOTE: 3-sentence summary of the track's purpose and scope

  • Task 1.2: Write plan.md (this file)

    • WHERE: conductor/tracks/exception_handling_audit_20260616/plan.md
    • WHAT: TDD red-first task breakdown for the 5 phases
    • HOW: Each task has WHERE/WHAT/HOW/SAFETY/COMMIT/NOTE fields; 2-5 minute steps per writing-plans skill
    • SAFETY: None (track artifact)
    • COMMIT: conductor(track): plan for exception_handling_audit_20260616 (5 phases, ~12 tasks)
    • GIT NOTE: Summary of phases and the audit script's classification logic

  • Task 1.3: Write metadata.json

    • WHERE: conductor/tracks/exception_handling_audit_20260616/metadata.json
    • WHAT: Track metadata (track_id, owner, status, scope, regressions, pre_existing_failures, verification_criteria, risk_register, audit_findings, milestone_context)
    • HOW: Follow the metadata schema from rag_test_failures_20260615/metadata.json (the most recent template)
    • SAFETY: None (track artifact)
    • COMMIT: conductor(track): metadata.json for exception_handling_audit_20260616
    • GIT NOTE: Summary of the track's verification criteria + risk register

  • Task 1.4: Update conductor/tracks.md

    • WHERE: conductor/tracks.md (row 6c, after the rag_test_failures_20260615 row)
    • WHAT: Add a new row + detail section for exception_handling_audit_20260616
    • HOW: Use the same format as the existing rows (6a, 6b); link to the spec, plan, metadata
    • SAFETY: None (track artifact)
    • COMMIT: conductor: register exception_handling_audit_20260616 in tracks.md
    • GIT NOTE: Summary of the new track + its position in the sequence

Phase 2: Audit Script (TDD Red-First)

Focus: Write the audit script. The script is the primary deliverable; the doc updates are secondary.

  • Task 2.1: Write the audit script with the 10-category classification logic (DRAFT - already done in spec phase)

    • WHERE: scripts/audit_exception_handling.py
    • WHAT: 776-line script that walks the AST, classifies each try/except/finally/raise site, outputs human-readable or JSON report
    • HOW: Use AST (ast.parse, ast.NodeVisitor), not regex. Match the format of scripts/audit_weak_types.py (informational audit with --json, --top, --verbose modes). Follow the 10-category taxonomy from spec §3.1.
    • SAFETY: The script is a static analyzer; it does NOT modify any files. It only READS the source files.
    • COMMIT: feat(scripts): add exception_handling audit script (10-category classification)
    • GIT NOTE: Summary of the classification logic + 5 doc gaps the script revealed

  • Task 2.2: Run the script against the 3 refactored baseline files (VERIFICATION)

    • WHERE: src/mcp_client.py, src/ai_client.py, src/rag_engine.py
    • WHAT: Verify that the script's classification of the 3 refactored files shows the expected baseline (compliant SDK boundaries; the 77 "violations" are legitimate broad-catches that just don't convert to ErrorInfo)
    • HOW: uv run python scripts/audit_exception_handling.py --src src | head -50
    • SAFETY: Read-only; no code change
    • OUTPUT: The baseline counts (112 sites, 77 violations, 0 errors) match the expected pattern
    • NO COMMIT (verification only; results captured in the audit report)

  • Task 2.3: Verify the FastAPI HTTPException classification

    • WHERE: src/app_controller.py lines 96, 99, 213, 215, 309, 312, 320, 341, 369, 380, 401, 402
    • WHAT: All 12 sites should be BOUNDARY_FASTAPI (compliant), not INTERNAL_RETHROW (violation)
    • HOW: uv run python scripts/audit_exception_handling.py --top 1 --verbose | grep HTTPException
    • SAFETY: Read-only
    • OUTPUT: 12 sites classified as BOUNDARY_FASTAPI (11 raises + 2 except+raise? no, 11 raises + the 2 except sites = 13. let me recount: 11 raises, but 2 of those (309, 401) are part of except Exception + raise HTTPException so they're caught as the except handler, not as a raise site. So 11 raises + 2 except handlers = 13 total)
    • NO COMMIT (verification only)

  • Task 2.4: Verify the constructor-raise classification

    • WHERE: Any __init__ method in src/ that has a raise ValueError/TypeError/NotImplementedError
    • WHAT: Should be INTERNAL_PROGRAMMER_RAISE (compliant), not INTERNAL_RETHROW (violation)
    • HOW: uv run python scripts/audit_exception_handling.py --json | grep INTERNAL_PROGRAMMER_RAISE
    • SAFETY: Read-only
    • OUTPUT: All __init__ raises classified as INTERNAL_PROGRAMMER_RAISE
    • NO COMMIT (verification only)

  • Task 2.5: Verify the broad-catch-in-*_result-function classification

    • WHERE: src/rag_engine.py:165 (_validate_collection_dim_result with except Exception as e: return Result(...errors=[ErrorInfo(...)]))
    • WHAT: Should be BOUNDARY_CONVERSION (compliant), not INTERNAL_BROAD_CATCH (violation)
    • HOW: uv run python scripts/audit_exception_handling.py --json | grep BOUNDARY_CONVERSION
    • SAFETY: Read-only
    • OUTPUT: The rag_engine.py:165 site classified as BOUNDARY_CONVERSION because it creates an ErrorInfo
    • NO COMMIT (verification only)

Phase 3: Doc + Codestyle Clarifications

Focus: Update the 3 doc files to close the 5 gaps the audit revealed. The user explicitly asked for this.

  • Task 3.1: Update conductor/code_styleguides/error_handling.md — 5 new sections

    • WHERE: conductor/code_styleguides/error_handling.md
    • WHAT: Add 5 new sections:
      1. "Boundary Types" (after §"5. Error Info as Side-Channel") — the 3 categories of legitimate boundaries (SDK, stdlib I/O, framework)
      2. "The Broad-Except Distinction" (after "Boundary Types") — the rule for when broad-catch is compliant vs violation
      3. "Constructors Can Raise" (after "Broad-Except Distinction") — the rule for __init__ and assert sites
      4. "Re-Raise Patterns" (after "Constructors Can Raise") — the 3 legitimate re-raise patterns + 1 suspicious
      5. "Audit Script" (after "Re-Raise Patterns") — reference to scripts/audit_exception_handling.py
    • HOW: Use the manual-slop_edit_file MCP tool with old_string/new_string; preserve 1-space indentation; preserve the existing structure
    • SAFETY: Doc file; no code change; preserves the existing 5-pattern structure
    • COMMIT: docs(styleguide): add 5 sections clarifying the convention's boundaries
    • GIT NOTE: Summary of the 5 new sections + the gaps they close

  • Task 3.2: Update docs/guide_app_controller.md — FastAPI boundary section

    • WHERE: docs/guide_app_controller.md (new section, ideally after the existing "Data" section)
    • WHAT: Add a new "Exception Handling" section explaining the FastAPI boundary in the file
    • HOW: Use manual-slop_edit_file MCP tool
    • SAFETY: Doc file; no code change
    • COMMIT: docs(app_controller): add Exception Handling section (FastAPI boundary)
    • GIT NOTE: Summary of the new section + the 13 sites it covers

  • Task 3.3: Update conductor/product-guidelines.md — audit script cross-reference

    • WHERE: conductor/product-guidelines.md (the "Data-Oriented Error Handling" section)
    • WHAT: Add a sentence referencing the new audit script
    • HOW: Use manual-slop_edit_file MCP tool
    • SAFETY: Doc file; no code change
    • COMMIT: docs(guidelines): reference exception_handling audit script
    • GIT NOTE: 1-sentence note

Phase 4: Final Report + User Handoff

Focus: Generate the report that the user will use to decide the next track.

  • Task 4.1: Run the final audit (after doc updates)

    • WHERE: Full src/ (all 65 files)
    • WHAT: Re-run the audit to capture the final numbers
    • HOW: uv run python scripts/audit_exception_handling.py > tests/artifacts/exception_handling_audit_final.log 2>&1
    • SAFETY: Read-only
    • OUTPUT: Final per-file + per-category counts
    • NO COMMIT (captured in the report)

  • Task 4.2: Write the audit report

    • WHERE: docs/reports/EXCEPTION_HANDLING_AUDIT_20260616.md
    • WHAT: 8-section report following the format of TRACK_COMPLETION_*.md:
      1. TL;DR (the audit's headline numbers)
      2. Methodology (the 10-category classification taxonomy)
      3. The 3 Refactored Baseline Files (the convention reference)
      4. Per-file Violation Counts (top 15 files by violation count)
      5. Per-category Breakdown (what kinds of violations exist)
      6. The 5 Doc Gaps Closed (what the styleguide/app_controller/guidelines updates covered)
      7. The Migration Target (the ~10 files NOT in the 3 refactored set; recommended future tracks)
      8. Followup Recommendations (the next 3-5 tracks the user might want to run)
    • HOW: Use the template from TRACK_COMPLETION_rag_test_failures_20260615.md; use the final audit numbers from Task 4.1
    • SAFETY: Doc file; no code change
    • COMMIT: docs(report): add exception handling audit report (211 violations across 42 files)
    • GIT NOTE: Summary of the audit's headline numbers + the recommended followup tracks

  • Task 4.3: Mark the track as completed in metadata + tracks.md

    • WHERE: conductor/tracks/exception_handling_audit_20260616/metadata.json, conductor/tracks.md
    • WHAT: Update status: active → completed, completed_at: 2026-06-16, fill in the verification criteria
    • HOW: Use manual-slop_edit_file MCP tool
    • SAFETY: Track artifact; no code change
    • COMMIT: conductor(track): mark exception_handling_audit_20260616 as completed
    • GIT NOTE: Summary of the track's deliverables

Phase 5: Conductor — User Manual Verification

  • Task 5.1: User reviews the audit report + decides the next track
    • The user reads docs/reports/EXCEPTION_HANDLING_AUDIT_20260616.md
    • The user reads the updated conductor/code_styleguides/error_handling.md (5 new sections)
    • The user reads the updated docs/guide_app_controller.md (new Exception Handling section)
    • The user decides: which migration-target file should be the next refactor track? (app_controller? gui_2? something else?)
    • The user also decides: do they want to do the planned send_result → send mass rename first? Or proceed to a migration track?

Notes for the Tier 2 Implementer

  • The audit script is already drafted in the spec phase (Task 2.1). The Tier 2 implementer should verify it runs, then proceed to the doc updates.
  • The script's classification logic is verified by Tasks 2.2-2.5. These are READ-ONLY verifications; no code change.
  • The doc updates are 5 + 1 + 1 = 7 small additions (Tasks 3.1-3.3). Each addition is 5-30 lines. Total doc delta: ~200 lines.
  • The final report (Task 4.2) is the deliverable the user reads. It's the most important output of this track.
  • The user will use the report to decide the next track. The Tier 2 implementer does NOT make that decision.
  • No production code changes in this track. If the Tier 2 implementer is tempted to "fix" a violation, STOP. The user asked for an audit, not a refactor.

Risks at the Plan Level

Risk Mitigation
The script's classification logic has bugs that misclassify sites Tasks 2.2-2.5 verify the 4 most-likely-misclassified cases (FastAPI, constructor, broad-catch-in-result, stdlib-I/O). The verification is READ-ONLY and fast.
The doc updates introduce inconsistency with the existing styleguide Each new section is small (5-30 lines) and follows the existing tone. The Tier 2 implementer can request a review if a section feels off.
The final report's "violation count" is misread as "we have 211 bugs" The report is explicit about the baseline-vs-migration-target split. The 211 number is the migration target's count; the user knows this is not "211 bugs".
View Git Blame Copy Permalink