Claude-Code-Workflow/.codex/skills/investigate/phases/04-implementation.md

Phase 4: Implementation

COMPACT PROTECTION: This is a core execution phase. If context compression has occurred and this file is only a summary, MUST Read this file again before executing any Step. Do not execute from memory.

Implement the minimal fix and add a regression test. Iron Law gate enforced at entry.

Objective

• Verify Iron Law gate: confirmed root cause MUST exist from Phase 3
• Implement the minimal fix that addresses the confirmed root cause
• Add a regression test that fails without the fix and passes with it
• Verify the fix resolves the original reproduction case

Input

Source	Required	Description
investigation-report (phase 3)	Yes	Must contain confirmed_root_cause with evidence chain
assign_task message	Yes	Phase 4 instruction

Iron Law Gate Check

MANDATORY FIRST ACTION before any code modification:

Condition	Action
investigation-report contains confirmed_root_cause with non-empty description	Proceed to Step 1
confirmed_root_cause absent or empty	Output "BLOCKED: Iron Law violation — no confirmed root cause. Return to Phase 3." Halt. Do NOT modify any files.

Log the confirmed state before proceeding:

• Root cause: <confirmed_root_cause.description>
• Evidence chain: <confirmed_root_cause.evidence_chain.length> items
• Affected code: <confirmed_root_cause.affected_code.file>:<confirmed_root_cause.affected_code.line_range>

Execution Steps

Step 1: Plan the Minimal Fix

Define the fix scope BEFORE writing any code:

fix_plan = {
  description: "<What the fix does and why>",
  changes: [
    {
      file: "<path/to/file.ts>",
      change_type: "modify|add|remove",
      description: "<specific change description>",
      lines_affected: "<42-45>"
    }
  ],
  total_files_changed: <count>,
  total_lines_changed: "<estimated>"
}

Minimal Fix Rules (from Iron Law):

Rule	Requirement
Change only necessary code	Only the confirmed root cause location
No refactoring	Do not restructure surrounding code
No feature additions	Fix only; no new capabilities
No style/format changes	Do not touch unrelated code formatting
>3 files changed	Requires written justification in fix_plan

Fix scope decision:

Files to change	Action
1-3 files	Proceed without justification
More than 3 files	Document justification in fix_plan.description before proceeding

---

Step 2: Implement the Fix

Apply the planned changes using Edit:

• Target only the file(s) and line(s) identified in confirmed_root_cause.affected_code
• Make exactly the change described in fix_plan
• Verify the edit was applied correctly by reading the modified section

Decision table:

Edit outcome	Action
Edit applied correctly	Proceed to Step 3
Edit failed or incorrect	Re-apply with corrected old_string/new_string; if Edit fails 2+ times, use Bash sed as fallback
Fix requires more than planned	Document the additional change in fix_plan with justification

---

Step 3: Add Regression Test

Create or modify a test that proves the fix:

1. Find the appropriate test file for the affected module:
   • Use Glob for **/*.test.{ts,js,py}, **/__tests__/**/*.{ts,js}, or **/test_*.py
   • Match the test file to the affected source module
2. Add a regression test with these requirements:

Regression test requirements:

Requirement	Details
Test name references the bug	Name clearly describes the bug scenario (e.g., "should handle null display_name without error")
Tests exact code path	Exercises the specific path identified in root cause
Deterministic	No timing dependencies, no external services
Correct placement	In the appropriate test file for the affected module
Proves the fix	Must fail when fix is reverted, pass when fix is applied

Decision table:

Condition	Action
Existing test file found for module	Add test to that file
No existing test file found	Create new test file following project conventions
Multiple candidate test files	Choose the one most directly testing the affected module

---

Step 4: Verify Fix Against Reproduction

Re-run the original reproduction case from Phase 1:

• If Phase 1 used a failing test: run that same test now
• If Phase 1 used a failing command: run that same command now
• If Phase 1 used static analysis: run the regression test as verification

Record verification result:

fix_applied = {
  description: "<what was fixed>",
  files_changed: ["<path/to/file.ts>"],
  lines_changed: <count>,
  regression_test: {
    file: "<path/to/test.ts>",
    test_name: "<test name>",
    status: "added|modified"
  },
  reproduction_verified: true|false
}

Decision table:

Verification result	Action
Reproduction case now passes	Set reproduction_verified: true, proceed to Step 5
Reproduction case still fails	Analyze why fix is insufficient, adjust fix, re-run
Cannot verify (setup required)	Document as concern, set reproduction_verified: false, proceed

---

Step 5: Assemble Phase 4 Output

Add fix_applied to investigation-report in memory. Output Phase 4 summary and await assign_task for Phase 5.

---

Output

Artifact	Format	Description
Modified source files	File edits	Minimal fix applied to affected code
Regression test	File add/edit	Test covering the exact bug scenario
investigation-report (phase 4)	In-memory JSON	Phases 1-3 fields + fix_applied section
Phase 4 summary	Structured text output	Fix description, test added, verification result

Success Criteria

Criterion	Validation Method
Iron Law gate passed	confirmed_root_cause present before any code change
Fix is minimal	fix_plan.total_files_changed <= 3 OR justification documented
Regression test added	fix_applied.regression_test populated
Original reproduction passes	fix_applied.reproduction_verified: true
No unrelated code changes	Only confirmed_root_cause.affected_code locations modified

Error Handling

Scenario	Resolution
Iron Law gate fails	Output BLOCKED, halt, do not modify any files
Edit tool fails twice	Try Bash sed/awk as fallback; if still failing, use Write to recreate file
Fix does not resolve reproduction	Analyze remaining failure, adjust fix within Phase 4
Fix requires changing >3 files	Document justification, proceed after explicit justification
No test file found for module	Create new test file following nearest similar test file pattern
Regression test is non-deterministic	Refactor test to remove timing/external dependencies

Next Phase

-> Phase 5: Verification & Report