Claude-Code-Workflow/.codex/skills/investigate/phases/05-verification-report.md

# Phase 5: Verification & Report

> **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.

Run full test suite, check for regressions, and generate the structured debug report.

## Objective

- Run the full test suite to verify no regressions were introduced
- Generate a structured debug report for future reference
- Output the report to `.workflow/.debug/` directory

## Input

| Source | Required | Description |
|--------|----------|-------------|
| investigation-report (phases 1-4) | Yes | All phases populated: evidence, root cause, fix_applied |
| assign_task message | Yes | Phase 5 instruction |

## Execution Steps

### Step 1: Detect and Run Full Test Suite

Detect the project's test framework by checking for project files, then run the full suite:

| Detection file | Test command |
|---------------|-------------|
| `package.json` with `test` script | `npm test` |
| `pytest.ini` or `pyproject.toml` | `pytest` |
| `go.mod` | `go test ./...` |
| `Cargo.toml` | `cargo test` |
| `Makefile` with `test` target | `make test` |
| None detected | Try `npm test`, `pytest`, `go test ./...` sequentially |

```
Bash: mkdir -p .workflow/.debug
Bash: <detected test command>
```

Record test results:

```
test_results = {
  total: <count>,
  passed: <count>,
  failed: <count>,
  skipped: <count>,
  regression_test_passed: true|false,
  new_failures: []
}
```

---

### Step 2: Regression Check

Verify specifically:

1. The new regression test passes (check by test name from fix_applied.regression_test.test_name).
2. All tests that were passing before the fix still pass.
3. No new warnings or errors appeared in test output.

**Decision table for new failures**:

| New failure | Assessment | Action |
|-------------|-----------|--------|
| Related to fix (same module, same code path) | Fix introduced regression | Return to Phase 4 to adjust fix |
| Unrelated to fix (different module, pre-existing) | Pre-existing failure | Document in pre_existing_failures, proceed |
| Regression test itself fails | Fix is not working correctly | Return to Phase 4 |

Classify failures:

```
regression_check_result = {
  passed: true|false,
  total_tests: <count>,
  new_failures: ["<test names that newly fail>"],
  pre_existing_failures: ["<tests that were already failing>"]
}
```

---

### Step 3: Generate Structured Debug Report

Compile all investigation data into the final debug report JSON following the schema from `~/.codex/skills/investigate/specs/debug-report-format.md`:

```
debug_report = {
  "bug_description": "<concise one-sentence description of the bug>",
  "reproduction_steps": [
    "<step 1>",
    "<step 2>",
    "<step 3: observe error>"
  ],
  "root_cause": "<confirmed root cause description with technical detail and file:line reference>",
  "evidence_chain": [
    "Phase 1: <error message X observed in module Y>",
    "Phase 2: <pattern analysis found N similar occurrences>",
    "Phase 3: hypothesis H<N> confirmed — <specific condition at file:line>"
  ],
  "fix_description": "<what was changed and why>",
  "files_changed": [
    {
      "path": "<src/module/file.ts>",
      "change_type": "add|modify|remove",
      "description": "<brief description of changes to this file>"
    }
  ],
  "tests_added": [
    {
      "file": "<src/module/__tests__/file.test.ts>",
      "test_name": "<should handle null return from X>",
      "type": "regression|unit|integration"
    }
  ],
  "regression_check_result": {
    "passed": true|false,
    "total_tests": <count>,
    "new_failures": [],
    "pre_existing_failures": []
  },
  "completion_status": "DONE|DONE_WITH_CONCERNS|BLOCKED",
  "concerns": [],
  "timestamp": "<ISO-8601 timestamp>",
  "investigation_duration_phases": 5
}
```

**Field sources**:

| Field | Source Phase | Description |
|-------|-------------|-------------|
| `bug_description` | Phase 1 | User-reported symptom, one sentence |
| `reproduction_steps` | Phase 1 | Ordered steps to trigger the bug |
| `root_cause` | Phase 3 | Confirmed cause with file:line reference |
| `evidence_chain` | Phase 1-3 | Each item prefixed with "Phase N:" |
| `fix_description` | Phase 4 | What code was changed and why |
| `files_changed` | Phase 4 | Each file with change type and description |
| `tests_added` | Phase 4 | Regression tests covering the bug |
| `regression_check_result` | Phase 5 | Full test suite results |
| `completion_status` | Phase 5 | Final status per protocol |
| `concerns` | Phase 5 | Non-blocking issues (if any) |
| `timestamp` | Phase 5 | When report was generated |
| `investigation_duration_phases` | Phase 5 | Always 5 for complete investigation |

---

### Step 4: Write Report File

Compute the filename:
- `<slug>` = bug_description lowercased, non-alphanumeric characters replaced with `-`, truncated to 40 chars
- `<date>` = current date as YYYY-MM-DD

```
Bash: mkdir -p .workflow/.debug
Write: .workflow/.debug/debug-report-<date>-<slug>.json
Content: <debug_report JSON with 2-space indent>
```

---

### Step 5: Output Completion Status

Determine status and output completion block:

**Status determination**:

| Condition | Status |
|-----------|--------|
| Regression test passes, no new failures, all quality checks met | DONE |
| Fix applied but partial test coverage, minor warnings, or non-critical concerns | DONE_WITH_CONCERNS |
| New test failures introduced by fix (unresolvable), or critical concern | BLOCKED |

**DONE output**:

```
## STATUS: DONE

**Summary**: Fixed <bug_description> — root cause was <root_cause_summary>

### Details
- Phases completed: 5/5
- Root cause: <confirmed_root_cause.description>
- Fix: <fix_description>
- Regression test: <test_name> in <test_file>

### Outputs
- Debug report: .workflow/.debug/debug-report-<date>-<slug>.json
- Files changed: <list>
- Tests added: <list>
```

**DONE_WITH_CONCERNS output**:

```
## STATUS: DONE_WITH_CONCERNS

**Summary**: Fixed <bug_description> with concerns

### Details
- Phases completed: 5/5
- Concerns:
  1. <concern> — Impact: low|medium — Suggested fix: <action>

### Outputs
- Debug report: .workflow/.debug/debug-report-<date>-<slug>.json
- Files changed: <list>
- Tests added: <list>
```

---

## Output

| Artifact | Format | Description |
|----------|--------|-------------|
| `.workflow/.debug/debug-report-<date>-<slug>.json` | JSON file | Full structured investigation report |
| Completion status block | Structured text output | Final status per Completion Status Protocol |

## Success Criteria

| Criterion | Validation Method |
|-----------|-------------------|
| Full test suite executed | Test command ran and produced output |
| Regression test passes | test_results.regression_test_passed: true |
| No new failures introduced | regression_check_result.new_failures is empty (or documented as pre-existing) |
| Debug report written | File exists at `.workflow/.debug/debug-report-<date>-<slug>.json` |
| Completion status output | Status block follows protocol format |

## Error Handling

| Scenario | Resolution |
|----------|------------|
| Test framework not detected | Try common commands in order; document uncertainty in concerns |
| New failures related to fix | Return to Phase 4 to adjust; do not write report until resolved |
| New failures unrelated | Document as pre_existing_failures, set DONE_WITH_CONCERNS if impactful |
| Report directory not writable | Try alternate path `.workflow/debug/`; document in output |
| Test suite takes >5 minutes | Run regression test only; note full suite skipped in concerns |
| Regression test was not added in Phase 4 | Document as DONE_WITH_CONCERNS concern |