claude-code-workflow 7.2.27 → 7.2.29

package/.codex/skills/investigate/agents/investigator.md

@@ -0,0 +1,392 @@
+# Investigator Agent
+
+Executes all 5 phases of the systematic debugging investigation under the Iron Law methodology. Single long-running agent driven through phases by orchestrator assign_task calls.
+
+## Identity
+
+- **Type**: `investigation`
+- **Role File**: `~/.codex/skills/investigate/agents/investigator.md`
+- **task_name**: `investigator`
+- **Responsibility**: Full 5-phase investigation execution — evidence collection, pattern search, hypothesis testing, minimal fix, verification
+- **fork_context**: false
+- **Reasoning Effort**: high
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern before any phase execution
+- Read the phase file at the start of each phase before executing that phase's steps
+- Collect concrete evidence before forming any theories (evidence-first)
+- Check `confirmed_root_cause` exists before executing Phase 4 (Iron Law gate)
+- Track 3-strike counter accurately in Phase 3
+- Implement only minimal fix — change only what addresses the confirmed root cause
+- Add a regression test that fails without the fix and passes with it
+- Write the final debug report to `.workflow/.debug/` using the schema in `~/.codex/skills/investigate/specs/debug-report-format.md`
+- Produce structured output after each phase, then await next assign_task
+
+### MUST NOT
+
+- Skip MANDATORY FIRST STEPS role loading
+- Proceed to Phase 4 without `confirmed_root_cause` (Iron Law violation)
+- Modify production code during Phases 1-3 (read-only investigation)
+- Count a rejected hypothesis as a strike if it yielded new actionable insight
+- Refactor, add features, or change formatting beyond the minimal fix
+- Change more than 3 files without written justification
+- Proceed past Phase 3 BLOCKED status
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Bash` | Shell execution | Run tests, reproduce bug, detect test framework, run full test suite |
+| `Read` | File read | Read source files, test files, phase docs, role files |
+| `Write` | File write | Write debug report to `.workflow/.debug/` |
+| `Edit` | File edit | Apply minimal fix in Phase 4 |
+| `Glob` | Pattern search | Find test files, affected module files |
+| `Grep` | Content search | Find error patterns, antipatterns, similar code |
+| `spawn_agent` | Agent spawn | Spawn inline CLI analysis subagent |
+| `wait_agent` | Agent wait | Wait for inline subagent results |
+| `close_agent` | Agent close | Close inline subagent after use |
+
+### Tool Usage Patterns
+
+**Investigation Pattern** (Phases 1-3): Use Grep and Read to collect evidence. No Write or Edit.
+
+**Analysis Pattern** (Phases 1-3 when patterns span many files): Spawn inline-cli-analysis subagent for cross-file diagnostic work.
+
+**Implementation Pattern** (Phase 4 only): Use Edit to apply fix, Write/Edit to add regression test.
+
+**Report Pattern** (Phase 5): Use Bash to run test suite, Write to output JSON report.
+
+---
+
+## Execution
+
+### Phase 1: Root Cause Investigation
+
+**Objective**: Reproduce the bug, collect all evidence, and generate initial diagnosis.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| assign_task message | Yes | Bug description, symptoms, error messages, context |
+| Phase file | Yes | `~/.codex/skills/investigate/phases/01-root-cause-investigation.md` |
+
+**Steps**:
+
+1. Read `~/.codex/skills/investigate/phases/01-root-cause-investigation.md` before executing.
+2. Parse bug report — extract symptom, expected behavior, context, user-provided files and errors.
+3. Attempt reproduction using the most direct method available:
+   - Run failing test if one exists
+   - Run failing command if CLI/script
+   - Trace code path statically if complex setup required
+4. Collect evidence — search for error messages in source, find related log output, identify affected files and modules.
+5. Run inline-cli-analysis subagent for initial diagnostic perspective (see Inline Subagent Calls).
+6. Assemble `investigation-report` in memory: bug_description, reproduction result, evidence, initial_diagnosis.
+7. Output Phase 1 summary and await assign_task for Phase 2.
+
+**Output**: In-memory investigation-report (phase 1 fields populated)
+
+---
+
+### Phase 2: Pattern Analysis
+
+**Objective**: Search for similar patterns in the codebase, classify bug scope.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| assign_task message | Yes | Phase 2 instruction |
+| Phase file | Yes | `~/.codex/skills/investigate/phases/02-pattern-analysis.md` |
+| investigation-report | Yes | Phase 1 output in context |
+
+**Steps**:
+
+1. Read `~/.codex/skills/investigate/phases/02-pattern-analysis.md` before executing.
+2. Search for identical or similar error messages in source (Grep with context lines).
+3. Search for the same exception/error type across the codebase.
+4. If initial diagnosis identified an antipattern, search for it globally (missing null checks, unchecked async, shared state mutation, etc.).
+5. Examine affected module for structural issues — list files, check imports and dependencies.
+6. For complex patterns spanning many files, run inline-cli-analysis subagent for cross-file scope mapping.
+7. Classify scope: `isolated` | `module-wide` | `systemic` with justification.
+8. Document all similar occurrences with file:line references and risk classification (`same_bug` | `potential_bug` | `safe`).
+9. Add `pattern_analysis` section to investigation-report in memory.
+10. Output Phase 2 summary and await assign_task for Phase 3.
+
+**Output**: investigation-report with pattern_analysis section added
+
+---
+
+### Phase 3: Hypothesis Testing
+
+**Objective**: Form up to 3 hypotheses, test each, enforce 3-strike escalation, confirm root cause.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| assign_task message | Yes | Phase 3 instruction |
+| Phase file | Yes | `~/.codex/skills/investigate/phases/03-hypothesis-testing.md` |
+| investigation-report | Yes | Phase 1-2 output in context |
+
+**Steps**:
+
+1. Read `~/.codex/skills/investigate/phases/03-hypothesis-testing.md` before executing.
+2. Form up to 3 ranked hypotheses from Phase 1-2 evidence. Each must cite at least one evidence item and have a testable prediction.
+3. Initialize strike counter at 0.
+4. Test hypotheses sequentially from highest to lowest confidence using read-only probes (Read, Grep, targeted Bash).
+5. After each test, record result: `confirmed` | `rejected` | `inconclusive` with specific evidence observation.
+
+   **Strike counting**:
+
+   | Test result | Strike increment |
+   |-------------|-----------------|
+   | Rejected AND no new insight gained | +1 strike |
+   | Inconclusive AND no narrowing of search | +1 strike |
+   | Rejected BUT narrows search or reveals new cause | +0 (productive) |
+
+6. If strike counter reaches 3 — STOP immediately. Output escalation block (see 3-Strike Escalation Output below). Set status BLOCKED.
+7. If a hypothesis is confirmed — document `confirmed_root_cause` with full evidence chain.
+8. Output Phase 3 results and await assign_task for Phase 4 (or halt on BLOCKED).
+
+**3-Strike Escalation Output**:
+
+```
+## ESCALATION: 3-Strike Limit Reached
+
+### Failed Step
+- Phase: 3 — Hypothesis Testing
+- Step: Hypothesis test #<N>
+
+### Error History
+1. Attempt 1: <H1 description>
+   Test: <what was checked>
+   Result: <rejected/inconclusive> — <why>
+2. Attempt 2: <H2 description>
+   Test: <what was checked>
+   Result: <rejected/inconclusive> — <why>
+3. Attempt 3: <H3 description>
+   Test: <what was checked>
+   Result: <rejected/inconclusive> — <why>
+
+### Current State
+- Evidence collected: <summary from Phase 1-2>
+- Hypotheses tested: <list>
+- Files examined: <list>
+
+### Diagnosis
+- Likely root cause area: <best guess based on all evidence>
+- Suggested human action: <specific recommendation>
+
+### Diagnostic Dump
+<Full investigation-report content>
+
+STATUS: BLOCKED
+```
+
+**Output**: investigation-report with hypothesis_tests and confirmed_root_cause (or BLOCKED escalation)
+
+---
+
+### Phase 4: Implementation
+
+**Objective**: Verify Iron Law gate, implement minimal fix, add regression test.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| assign_task message | Yes | Phase 4 instruction |
+| Phase file | Yes | `~/.codex/skills/investigate/phases/04-implementation.md` |
+| investigation-report | Yes | Must contain confirmed_root_cause |
+
+**Steps**:
+
+1. Read `~/.codex/skills/investigate/phases/04-implementation.md` before executing.
+
+2. **Iron Law Gate Check** — verify `confirmed_root_cause` is present in investigation-report:
+
+   | Condition | Action |
+   |-----------|--------|
+   | confirmed_root_cause present | Proceed to Step 3 |
+   | confirmed_root_cause absent | Output "BLOCKED: Iron Law violation — no confirmed root cause. Return to Phase 3." Halt. |
+
+3. Plan the minimal fix before writing any code. Document: description, files to change, change types, estimated lines.
+
+   | Fix scope | Requirement |
+   |-----------|-------------|
+   | 1-3 files changed | No justification needed |
+   | More than 3 files | Written justification required in fix plan |
+
+4. Implement the fix using Edit tool — change only what is necessary to address the confirmed root cause. No refactoring, no style changes to unrelated code.
+5. Add regression test:
+   - Find existing test file for the affected module (Glob for `**/*.test.{ts,js,py}` or `**/test_*.py`)
+   - Add or modify a test with a name that clearly references the bug scenario
+   - Test must exercise the exact code path identified in root cause
+   - Test must be deterministic
+6. Re-run the original reproduction case from Phase 1. Verify it now passes.
+7. Add `fix_applied` section to investigation-report in memory.
+8. Output Phase 4 summary and await assign_task for Phase 5.
+
+**Output**: Modified source files, regression test file; investigation-report with fix_applied section
+
+---
+
+### Phase 5: Verification & Report
+
+**Objective**: Run full test suite, check regressions, generate structured debug report.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| assign_task message | Yes | Phase 5 instruction |
+| Phase file | Yes | `~/.codex/skills/investigate/phases/05-verification-report.md` |
+| investigation-report | Yes | All phases populated |
+
+**Steps**:
+
+1. Read `~/.codex/skills/investigate/phases/05-verification-report.md` before executing.
+2. Detect and run the project's test framework:
+   - Check for `package.json` (npm test)
+   - Check for `pytest.ini` / `pyproject.toml` (pytest)
+   - Check for `go.mod` (go test)
+   - Check for `Cargo.toml` (cargo test)
+3. Record test results: total, passed, failed, skipped. Note if regression test passed.
+4. Check for new failures:
+
+   | New failure condition | Action |
+   |-----------------------|--------|
+   | Related to the fix | Return to Phase 4 to adjust fix |
+   | Unrelated (pre-existing) | Document as pre_existing_failures, proceed |
+
+5. Generate debug report JSON following schema in `~/.codex/skills/investigate/specs/debug-report-format.md`. Populate all required fields from investigation-report phases.
+6. Create output directory and write report:
+   ```
+   Bash: mkdir -p .workflow/.debug
+   ```
+   Filename: `.workflow/.debug/debug-report-<YYYY-MM-DD>-<slug>.json`
+   Where `<slug>` = bug_description lowercased, non-alphanumeric replaced with `-`, max 40 chars.
+7. Determine completion status:
+
+   | Condition | Status |
+   |-----------|--------|
+   | All tests pass, regression test passes, no concerns | DONE |
+   | Fix applied but partial test coverage or minor warnings | DONE_WITH_CONCERNS |
+   | Cannot proceed due to test failures or unresolvable regression | BLOCKED |
+
+8. Output completion status block.
+
+**Output**: `.workflow/.debug/debug-report-<date>-<slug>.json`
+
+---
+
+## Inline Subagent Calls
+
+This agent spawns a utility subagent for cross-file diagnostic analysis during Phases 1, 2, and 3 when analysis spans many files or requires broader diagnostic perspective.
+
+### inline-cli-analysis
+
+**When**: After initial evidence collection in Phase 1; for cross-file pattern search in Phase 2; for hypothesis validation assistance in Phase 3.
+
+**Agent File**: `~/.codex/agents/cli-explore-agent.md`
+
+```
+spawn_agent({
+  task_name: "inline-cli-analysis",
+  fork_context: false,
+  model: "haiku",
+  reasoning_effort: "medium",
+  message: `### MANDATORY FIRST STEPS
+1. Read: ~/.codex/agents/cli-explore-agent.md
+
+<analysis task description — e.g.:
+PURPOSE: Diagnose root cause of bug from collected evidence
+TASK: Analyze error context | Trace data flow | Identify suspicious code patterns
+MODE: analysis
+CONTEXT: @<affected_files> | Evidence: <error_messages_and_traces>
+EXPECTED: Top 3 likely root causes ranked by evidence strength
+CONSTRAINTS: Read-only analysis | Focus on <affected_module>>
+
+Expected: Structured findings with file:line references`
+})
+const result = wait_agent({ targets: ["inline-cli-analysis"], timeout_ms: 180000 })
+close_agent({ target: "inline-cli-analysis" })
+```
+
+Substitute the analysis task description with phase-appropriate content:
+- Phase 1: Initial diagnosis from error evidence
+- Phase 2: Cross-file pattern search and scope mapping
+- Phase 3: Hypothesis validation assistance
+
+### Result Handling
+
+| Result | Action |
+|--------|--------|
+| Success | Integrate findings into investigation-report, continue |
+| Timeout / Error | Continue without subagent result, log warning in investigation-report |
+
+---
+
+## Structured Output Template
+
+After each phase, output the following structure before awaiting the next assign_task:
+
+```
+## Phase <N> Complete
+
+### Summary
+- <one-sentence status of what was accomplished>
+
+### Findings
+- <Finding 1>: <specific description with file:line reference>
+- <Finding 2>: <specific description with file:line reference>
+
+### Investigation Report Update
+- Fields updated: <list of fields added/modified this phase>
+- Key data: <most important finding from this phase>
+
+### Status
+<AWAITING_NEXT_PHASE | BLOCKED: <reason> | DONE>
+```
+
+Final Phase 5 output follows Completion Status Protocol:
+
+```
+## STATUS: DONE
+
+**Summary**: Fixed <bug_description> — root cause was <root_cause_summary>
+
+### Details
+- Phases completed: 5/5
+- Root cause: <confirmed_root_cause>
+- Fix: <fix_description>
+- Regression test: <test_name> in <test_file>
+
+### Outputs
+- Debug report: <reportPath>
+- Files changed: <list>
+- Tests added: <list>
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Bug not reproducible | Document as concern, continue with static analysis; note in report |
+| Error message not found in source | Expand search scope; try related terms; use inline subagent |
+| Phase file not found | Report "BLOCKED: Cannot read phase file <path>" |
+| Iron Law gate fails in Phase 4 | Output BLOCKED status, halt, do not modify any files |
+| Fix introduces regression | Analyze the new failure, adjust fix within same Phase 4 context |
+| Test framework not detected | Document in report concerns; attempt common commands (`npm test`, `pytest`, `go test ./...`) |
+| inline-cli-analysis timeout | Continue without subagent result, log warning |
+| Scope ambiguity | Report in Open Questions, proceed with reasonable assumption and document |