troubleshoot

name	troubleshoot
description	Diagnose and plan fixes for errors/bugs with Codex-first multi-agent collaboration (Codex + Opus 4.6 + Agent Teams). Codex CLI is consulted in EVERY phase for deep code reasoning, hypothesis evaluation, and fix validation. Phase 1: Error reproduction & context gathering (Opus subagent 1M context + Codex initial analysis + Claude user interaction). Phase 2: Parallel diagnosis (Agent Teams: Root Cause Analyst [Codex-driven] + Impact Investigator [Opus + Codex risk analysis]). Phase 3: Fix plan synthesis, Codex validation & user approval. Fix implementation is handled separately by /team-execute.
metadata	{"short-description":"Codex-first error/bug diagnosis with Agent Teams (Diagnosis phase)"}

Troubleshoot

Codex-first error/bug diagnosis skill leveraging Codex deep reasoning, Opus 1M context, and Agent Teams.

Preflight: ensure codex CLI is current (see codex-system skill).

Overview

This skill handles the diagnosis phases (Phase 1-3) with a Codex-first approach: Codex CLI is consulted proactively in every phase for pattern recognition, hypothesis evaluation, root cause reasoning, and fix validation. Fix implementation and review are done via /team-execute.

/troubleshoot <error description>   <- This skill (diagnosis & fix planning)
    | After approval
/team-execute                       <- Parallel fix implementation (Phase 1)
    | After completion
    Phase 2 REVIEW                  <- Parallel review (regression check)

Workflow

Phase 1: REPRODUCE & UNDERSTAND (Opus 1M context + Codex Initial Analysis + Claude Lead)
  Opus subagent analyzes the error context, Codex generates initial hypotheses,
  Claude gathers details from the user
    |
Phase 2: DIAGNOSE (Agent Teams -- Parallel, Codex-driven)
  Root Cause Analyst (Codex mandatory) <-> Impact Investigator (Opus + Codex) communicate bidirectionally
  Both teammates consult Codex for deep reasoning throughout analysis
    |
Phase 3: FIX PLAN & APPROVE (Codex Validation + Claude Lead + User)
  Integrate diagnosis results, validate fix plan with Codex, get user approval

---

Phase 1: REPRODUCE & UNDERSTAND (Opus Subagent + Codex + Claude Lead)

Reproduce the error and gather full context with Opus subagent's 1M context, then consult Codex for initial hypothesis generation, while Claude interacts with the user.

Main orchestrator context is precious. Large-scale error context analysis is delegated to Opus subagent (1M context). Codex is consulted early for pattern recognition and hypothesis generation.

Step 0: Resolve Workspace

Resolve this bug's deterministic workspace once. The title becomes file and directory names, so give it a short English descriptor of the bug -- not the user's raw wording, which the Language Protocol keeps out of paths:

python3 .agents/skills/_shared/workspace.py --skill troubleshoot --title "{short English title}" --create

This prints one JSON object: slug, team_name, and paths (bug_report, context, root_cause, impact, diagnosis, state_input, team_dir). Exit 0 resolved/created; 1 bad args; 2 applies only to --verify (used later in Phase 3); 3 the workspace directories could not be created. Use {slug}, {team_name}, and every paths.* value from this JSON verbatim for the rest of this skill -- do not re-derive them by hand in a later phase.

Step 1: Gather Error Details from User

Ask the user to provide:

1. Error message / stack trace: Full error output
2. Reproduction steps: How to trigger the error
3. Expected vs actual behavior: What should happen vs what happens
4. Environment: OS, Python version, dependency versions
5. Recent changes: What changed before the error appeared (if known)

Step 2: Reproduce & Capture Context (repro.py)

First run the bundled script for the mechanical capture — it runs the failing command under a deadline, records stdout/stderr/exit code + extracted traceback to a log file keyed by --label, and gathers recent git history (plus optional last-commit context for a stack-trace file):

python3 .agents/skills/troubleshoot/repro.py "<repro-command>" \
  --label {slug}-initial [--file <path-from-stack-trace>] [--timeout 120]

Always pass --label {slug}-initial here: the log path is .agents/logs/troubleshoot-repro-{label}.log and an unlabelled run reuses one shared file, so the Phase 3 fix-verification run (Step 2 task 3) would otherwise overwrite the original failure evidence this whole diagnosis rests on.

Exit codes: 0 capture completed; 1 bad arguments (including an unusable --label or --bisect-good ref, checked before the command runs); 2 the observed exit code differs from --expect-exit (not used in Phase 1); 3 the repro command timed out or the log could not be written. A failing repro command is the expected case and is still exit 0 — its result is the JSON exit_code.

Read the JSON fields: exit_code, timed_out, stdout_tail, stderr_tail, traceback, traceback_format, git_available, git_error, recent_commits, blame, blame_error, bisect, log_file, artifacts. Two fields exist to stop a null being over-read: traceback is only extracted for CPython tracebacks (traceback_format: "python"), so null there means "no Python traceback" — a Node/Go/pytest-assertion stack is in stderr_tail. And git_available: false with a git_error means history could not be read at all; that is not the same as "no relevant recent history".

On timed_out: true (exit 3) the command has no usable result: raise the --timeout, narrow the repro command, or treat the hang itself as the bug — do not proceed as if the capture succeeded.

To scope a regression, add --bisect-good <last-known-good-ref>. It reports the bisect object (candidate_commits, candidate_count, path_filter, bisect_command) — the commits an actual git bisect would search, plus the command to start it. The script never checks out a commit itself, so driving the bisect stays the Impact Investigator's call in Phase 2.

Then hand that captured context to general-purpose-opus for the judgment part — do NOT re-run the command or re-fetch git history:

Task tool:
  subagent_type: "general-purpose-opus"
  prompt: |
    Analyze this reproduced error (already captured by repro.py):

    Error: {error message / stack trace}
    repro.py JSON: {exit_code, traceback, recent_commits, log_file}

    Tasks:
    1. Read all files mentioned in the traceback; trace the execution flow
       leading to the error and identify the immediate cause (what line fails).
    2. Look for related tests and whether they pass/fail.
    3. Check if similar patterns exist elsewhere in the codebase.

    Use Glob, Grep, and Read tools to investigate thoroughly.

    Save analysis to `{paths.context}` (from Phase 1 Step 0).
    Return concise summary (5-7 key findings).

Step 2.5: Codex Initial Error Pattern Analysis

Consult Codex for initial hypothesis generation before creating the Bug Report. Write the prompt to a file, then invoke the wrapper:

Objective: Analyze this error and generate initial hypotheses for root cause.
Context:
- Error: {error message / stack trace}
- Failing location: {file:line from Opus subagent analysis}
- Execution flow: {call chain from Opus subagent analysis}
Constraints:
- Focus on root cause categories (state mutation, boundary, concurrency, dependency, type/contract)
- Rank hypotheses by likelihood
- Suggest specific code areas to investigate for each hypothesis
Output format:
## Error Pattern Recognition
## Hypotheses (ranked by likelihood)
## Investigation Plan (per hypothesis)
## Known Similar Patterns

python3 .agents/skills/_shared/codex_consult.py --prompt-file .agents/logs/codex/prompt-troubleshoot-initial.md --label troubleshoot-initial

.agents/skills/_shared/codex_consult.py exits 0 when Codex answered normally, 2 if the Codex CLI is not installed, 3 if Codex failed or timed out -- check the JSON ok field and read response_file for the answer (error/stderr_file explain a failure). Every later Codex consultation in this skill follows this same write-prompt-then-invoke pattern without repeating these exit codes.

Use Codex's analysis to strengthen the Initial Hypotheses section of the Bug Report.

Step 3: Create Bug Report

Combine error details + codebase analysis + Codex initial hypotheses into a Bug Report following the template contract in references/bug-report-template.md. Save it to {paths.bug_report} (from Step 0), then validate it:

python3 .agents/skills/_shared/validate_doc.py --contract bug-report --file {paths.bug_report}

references/bug-report-template.md is the single source of truth for the required sections; the bug-report contract is pinned to that template by tests/test_validate_doc.py. Do not work from a section list retyped here -- that drift is exactly what this fix removed. Exit 0 means every required section is present; exit 2 means one is missing, and the JSON sections_missing names it. Fill the gap before proceeding; exit 1 means the file does not exist.

Both Phase 2 teammates read this file, and Phase 3's --verify gate requires it, so it must exist on disk -- not only in this conversation.

---

Phase 2: DIAGNOSE (Agent Teams — Parallel)

Launch Root Cause Analyst and Impact Investigator in parallel via Agent Teams with bidirectional communication. Both teammates MUST consult Codex for deep reasoning tasks.

Key difference from subagents: Teammates can communicate with each other. Root Cause Analyst's findings change Impact Investigator's scope, and Impact Investigator's context informs root cause analysis.

Team Setup

Create an agent team named `{team_name}` for troubleshooting: {slug}

Spawn two teammates:

1. **Root Cause Analyst** — Uses Codex CLI as PRIMARY analysis engine for deep code reasoning
   Prompt: "You are the Root Cause Analyst for bug: {slug}.

   Your job: Identify the definitive root cause of this error through deep code analysis.
   Codex CLI is your PRIMARY tool for reasoning about code behavior.

   Bug Report: read `{paths.bug_report}` (written and validated in Phase 1 Step 3).

   Tasks:
   1. Trace the execution flow step by step from entry point to error
   2. Evaluate each hypothesis from the Bug Report:
      - Gather evidence FOR and AGAINST each hypothesis
      - Eliminate hypotheses that contradict the evidence
   3. Identify the root cause (not just the symptom):
      - What is the underlying defect?
      - Why does it manifest as this specific error?
      - Under what conditions does it trigger?
   4. Propose fix approaches (at least 2 alternatives):
      - Approach A: {description, pros, cons}
      - Approach B: {description, pros, cons}
      - Recommended approach with rationale

   ## Codex Analysis Protocol (MANDATORY)

   You MUST consult Codex for EACH of the following analysis tasks.
   Do NOT skip Codex consultation — it is the primary reasoning engine for this role.
   Each consultation below follows the same shape: write the prompt to a file,
   then run `python3 .agents/skills/_shared/codex_consult.py --prompt-file <path> --label <label>`
   and read the JSON `response_file`.

   ### 1. Execution Flow Tracing
   For complex control flow, write the prompt below to a file, then consult Codex:

   Objective: Trace the execution flow from {entry point} to {error location}.
   Context:
   - Entry point: {file:function}
   - Error location: {file:line}
   - Key intermediate functions: {list}
   Constraints:
   - Track state transformations at each step
   - Identify where assumptions are violated
   Output format:
   ## Execution Flow (step by step)
   ## State Transformations
   ## Assumption Violations
   ## Critical Decision Points

   python3 .agents/skills/_shared/codex_consult.py --prompt-file .agents/logs/codex/prompt-troubleshoot-flow.md --label troubleshoot-flow

   ### 2. Hypothesis Evaluation
   For each hypothesis, write the prompt below to a file, then consult Codex to evaluate evidence:

   Objective: Evaluate hypothesis "{hypothesis}" against collected evidence.
   Context:
   - Hypothesis: {description}
   - Evidence FOR: {list}
   - Evidence AGAINST: {list}
   - Code context: {relevant code snippets}
   Constraints:
   - Apply logical reasoning, not pattern matching
   - Consider alternative explanations for the evidence
   Output format:
   ## Verdict (CONFIRMED / ELIMINATED / INCONCLUSIVE)
   ## Reasoning
   ## Remaining Unknowns

   python3 .agents/skills/_shared/codex_consult.py --prompt-file .agents/logs/codex/prompt-troubleshoot-hypothesis.md --label troubleshoot-hypothesis

   ### 3. Fix Approach Design
   Write the prompt below to a file, then consult Codex for trade-off analysis of fix alternatives:

   Objective: Design and compare fix approaches for root cause: {root cause description}.
   Context:
   - Root cause: {description}
   - Affected code: {file:line}
   - Current behavior: {description}
   - Desired behavior: {description}
   Constraints:
   - Propose at least 2 approaches
   - Evaluate: correctness, minimal invasiveness, maintainability, performance
   - Consider backward compatibility
   Output format:
   ## Approach A: {name}
   ## Approach B: {name}
   ## Comparison Matrix
   ## Recommendation with Rationale

   python3 .agents/skills/_shared/codex_consult.py --prompt-file .agents/logs/codex/prompt-troubleshoot-fix-design.md --label troubleshoot-fix-design

   ### 4. Fix Correctness Verification
   Before finalizing, write the prompt below to a file, then consult Codex to verify the proposed fix:

   Objective: Verify that the proposed fix correctly resolves the root cause.
   Context:
   - Root cause: {description}
   - Proposed fix: {description}
   - Edge cases identified: {list}
   Constraints:
   - Check that the fix addresses the root cause, not just symptoms
   - Verify behavior under all identified trigger conditions
   - Check for new failure modes introduced by the fix
   Output format:
   ## Correctness Assessment (CORRECT / INCOMPLETE / INCORRECT)
   ## Edge Case Coverage
   ## New Failure Modes (if any)
   ## Confidence Level

   python3 .agents/skills/_shared/codex_consult.py --prompt-file .agents/logs/codex/prompt-troubleshoot-fix-verify.md --label troubleshoot-fix-verify

   Save analysis to `{paths.root_cause}` (from Phase 1 Step 0).

   Communicate with Impact Investigator teammate:
   - Share root cause findings that expand the affected scope
   - Request context about specific code paths or history
   - Confirm or refute hypotheses based on shared evidence

   IMPORTANT — Work Log:
   When ALL your tasks are complete, write your work log to
   {paths.team_dir}root-cause-analyst.md per the shared
   format: .agents/skills/_shared/work-log-format.md
   Keep all five core sections, `## Tasks Completed` included -- the Lead
   validates this log with `validate_doc.py --contract work-log`, which
   rejects a log that drops it.
   Role-specific sections (between Tasks Completed and Communication with
   Teammates) for this role:
   ## Hypotheses Evaluated
   - [confirmed/eliminated] {hypothesis}: {evidence}
   ## Root Cause
   - Defect: {description}
   - Location: {file:line}
   - Trigger condition: {when it occurs}
   ## Proposed Fixes
   - Approach A: {description} — {pros/cons}
   - Approach B: {description} — {pros/cons}
   - Recommended: {which and why}
   ## Codex Consultations
   - {question asked to Codex}: {key insight from response}
   "

2. **Impact Investigator** — Uses Opus with Git history, codebase search, WebSearch, and Codex for risk analysis
   Prompt: "You are the Impact Investigator for bug: {slug}.

   Your job: Determine the full scope and impact of this bug, and gather context for the fix.
   Consult Codex for regression risk reasoning and fix safety analysis.

   Bug Report: read `{paths.bug_report}` (written and validated in Phase 1 Step 3).

   Tasks:
   1. Trace the bug's origin in git history:
      - git log / git bisect to find the introducing commit
      - What change caused this? Was it intentional?
   2. Assess blast radius:
      - What other code paths call the affected function?
      - What features/users are impacted?
      - Are there related bugs or similar patterns elsewhere?
   3. Research external context:
      - Is this a known issue in a dependency? (WebSearch)
      - Are there upstream fixes or workarounds?
      - Check issue trackers, changelogs, migration guides
   4. Evaluate regression risk:
      - What tests cover the affected area?
      - What could break if we change this code?
      - Are there downstream consumers to consider?

   How to research:
   - Use Git commands (git log, git blame, git bisect) for history
   - Use Grep/Glob for codebase impact analysis
   - Use WebSearch for external known issues:
     WebSearch: '{library} {error message} issue fix'

   ## Codex Risk Analysis Protocol (MANDATORY)

   You MUST consult Codex for regression risk reasoning and fix safety analysis.
   Each consultation below follows the same shape: write the prompt to a file,
   then run `python3 .agents/skills/_shared/codex_consult.py --prompt-file <path> --label <label>`
   and read the JSON `response_file`.

   ### Regression Risk Reasoning
   Write the prompt below to a file, then consult Codex to evaluate what could break if the proposed change is applied:

   Objective: Evaluate regression risk if {proposed change} is applied to {file:line}.
   Context:
   - Current behavior: {description}
   - Proposed change: {description}
   - Callers of affected function: {list}
   - Existing test coverage: {description}
   Constraints:
   - Consider all callers and downstream consumers
   - Identify implicit contracts that may be violated
   - Assess backward compatibility impact
   Output format:
   ## Risk Assessment (HIGH / MEDIUM / LOW)
   ## Affected Code Paths
   ## Implicit Contracts at Risk
   ## Recommended Safeguards

   python3 .agents/skills/_shared/codex_consult.py --prompt-file .agents/logs/codex/prompt-troubleshoot-regression.md --label troubleshoot-regression

   ### Fix Safety Analysis
   Write the prompt below to a file, then consult Codex to verify the proposed fix does not introduce new issues:

   Objective: Analyze whether the proposed fix introduces new issues or side effects.
   Context:
   - Root cause: {from Root Cause Analyst}
   - Proposed fix: {description}
   - Blast radius: {affected code paths}
   - Dependencies: {upstream/downstream}
   Constraints:
   - Check for new edge cases created by the fix
   - Verify thread safety if applicable
   - Check for performance implications
   Output format:
   ## Safety Assessment (SAFE / CAUTION / UNSAFE)
   ## New Issues Identified
   ## Side Effects
   ## Mitigation Recommendations

   python3 .agents/skills/_shared/codex_consult.py --prompt-file .agents/logs/codex/prompt-troubleshoot-fix-safety.md --label troubleshoot-fix-safety

   Save findings to `{paths.impact}` (from Phase 1 Step 0).

   Communicate with Root Cause Analyst teammate:
   - Share git history context that informs root cause
   - Share external findings (known issues, upstream fixes)
   - Request clarification on which code paths to investigate

   IMPORTANT — Work Log:
   When ALL your tasks are complete, write your work log to
   {paths.team_dir}impact-investigator.md per the shared
   format: .agents/skills/_shared/work-log-format.md
   Keep all five core sections, `## Tasks Completed` included -- the Lead
   validates this log with `validate_doc.py --contract work-log`, which
   rejects a log that drops it.
   Role-specific sections (between Tasks Completed and Communication with
   Teammates) for this role:
   ## Git History
   - Introducing commit: {hash} — {description}
   - Related commits: {list}
   ## Blast Radius
   - Affected code paths: {list}
   - Affected features/users: {list}
   ## External Research
   - {source}: {finding and relevance}
   ## Regression Risk
   - Existing test coverage: {description}
   - Risk areas: {what could break}
   ## Codex Risk Analysis
   - Regression risk assessment: {Codex's verdict and reasoning}
   - Fix safety assessment: {Codex's verdict and reasoning}
   "

Wait for both teammates to complete their tasks.

Why Bidirectional Communication Matters for Debugging

Example interaction flow:

Root Cause Analyst: "The error occurs because parse_config() returns None when key is missing"
    -> Impact Investigator: "Checking git blame -- this was changed in commit abc123"
    -> Impact Investigator: "Found 5 other callers of parse_config() that don't handle None"
    -> Root Cause Analyst: "Expanding fix scope -- need to either fix callers or fix parse_config()"
    -> Root Cause Analyst: "Codex recommends: fix parse_config() to raise KeyError instead of returning None"
    -> Impact Investigator: "Codex risk analysis confirms: all 5 callers already have try/except for KeyError"
    -> Root Cause Analyst: "Root cause confirmed. Codex verified fix correctness. Fix approach: restore KeyError in parse_config()"

Without Agent Teams, this discovery loop would require multiple sequential subagent rounds.

---

Phase 3: FIX PLAN & APPROVE (Codex Validation + Claude Lead)

Integrate Agent Teams diagnosis results, validate the fix plan with Codex, and request user approval.

Step 1: Synthesize Diagnosis

Gate Phase 3 on the Phase 1/2 artifacts before reading anything, so a teammate that stopped early cannot be mistaken for one that finished:

python3 .agents/skills/_shared/workspace.py --skill troubleshoot --slug {slug} --verify
python3 .agents/skills/_shared/validate_doc.py --contract work-log \
  --dir {paths.team_dir} --expect-files 2

The first call exits 0 when bug_report, context, root_cause, and impact are all present and non-trivial; exit 2 means one is missing or empty (read verify.missing / verify.empty). The second exits 0 only when both teammate logs exist and satisfy the work-log contract; exit 2 means a log is missing (error: "expected 2 files, found N") or malformed (files_failed > 0, with sections_missing per file). "Wait for both teammates to complete" is a self-report; these two commands are the check. Resolve every gap before continuing.

Read outputs from Phase 2:

• {paths.root_cause} -- Root cause analysis
• {paths.impact} -- Impact assessment

Step 1.5: Codex Fix Plan Validation

Before presenting to the user, validate the fix plan with Codex. Write the prompt to a file, then invoke the wrapper:

Objective: Validate this fix plan for completeness and correctness.
Context:
- Root cause: {from Root Cause Analyst}
- Proposed fix: {recommended approach}
- Blast radius: {from Impact Investigator}
- Fix tasks: {task list}
Constraints:
- Check for missing edge cases
- Verify the fix addresses the root cause (not just symptoms)
- Identify potential new issues the fix could introduce
- Suggest additional test cases if needed
Output format:
## Validation Result (PASS / NEEDS_REVISION)
## Missing Coverage
## Potential New Issues
## Additional Test Cases Recommended
## Revised Task List (if needed)

python3 .agents/skills/_shared/codex_consult.py --prompt-file .agents/logs/codex/prompt-troubleshoot-plan-validation.md --label troubleshoot-plan-validation

If Codex returns NEEDS_REVISION, update the fix plan before presenting to user.

Step 2: Create Fix Plan

Create task list using TodoWrite:

{
    "content": "Fix {specific task}",
    "activeForm": "Fixing {specific task}",
    "status": "pending"
}

Task breakdown should follow references/debug-patterns.md.

Typical fix task structure:

1. Write failing test -- Reproduce the bug as a test case

2. Apply fix -- Implement the root cause fix

3. Verify fix -- Re-run the original repro command with the expectation asserted by the script rather than read by eye, and with its own label so the Phase 1 failure log survives:

   python3 .agents/skills/troubleshoot/repro.py "<repro-command>" \
     --label {slug}-fix-verify --expect-exit 0
   

   Exit 0 is the verification. Exit 2 means the fix is not verified (error: "expected exit 0, got N"); exit 3 means it timed out and nothing was verified at all. Do not report a verified fix on any exit code but 0.

4. Check regressions -- Run the quality gates:

   bash .agents/skills/_shared/verify.sh
   

   Read the JSON: overall is pass / fail / no_gates. Exit 0 is a pass; exit 2 is a gate failure or no_gates -- inspect log_file and the per-tool tools object. no_gates means zero gates actually ran, which is a contract violation, not a pass: fall back to the project's own verification commands and confirm manually, and pass --allow-no-gates only when you have done so deliberately. Quote the tools object rather than re-typing each status, so a skipped gate is never reported as a pass.

5. Fix collateral damage -- Address blast radius items (if any)

Step 3: Update Shared State

Add bug context to .agents/STATE.md for cross-session persistence using the shared writer script and .agents/rules/agent-state.md.

Gather these fields from the diagnosis:

• Context: Error summary, Root cause, Affected files
• Fix Approach: Recommended approach from Root Cause Analyst
• Codex Validation: Result + additional test cases
• Regression Risks: Key risks from Impact Investigator + Codex assessment
• Decisions with rationale

Write the input JSON to {paths.state_input} (from Phase 1 Step 0):

{
  "title": "{slug}",
  "sections": [
    {"heading": "Context", "content": "- Error: ...\n- Root cause: ...\n- Affected files: ..."},
    {"heading": "Fix Approach", "content": "- {approach}"},
    {"heading": "Regression Risks", "content": "- {risks}"},
    {"heading": "Decisions", "content": "- {Decision 1}: {rationale}"}
  ]
}

Run dry-run, review the preview, then apply:

python3 .agents/skills/_shared/append_state_block.py \
  --type bug-fix --input {paths.state_input}
# Review the preview file path in the JSON output, then:
python3 .agents/skills/_shared/append_state_block.py \
  --type bug-fix --input {paths.state_input} --apply

Verify "ok": true and "progress_tracker_preserved": true in the output. Exit code 2 means the state structure is invalid; stop before writing.

Step 4: Present to User

Compose the diagnosis and fix plan following the template contract in references/diagnosis-template.md. Write the composed presentation to {paths.diagnosis} (resolved in Phase 1 Step 0, never hand-built) and validate its structure before presenting it:

python3 .agents/skills/_shared/validate_doc.py --contract diagnosis \
  --file {paths.diagnosis}
python3 .agents/skills/_shared/workspace.py --skill troubleshoot \
  --slug {slug} --verify --require diagnosis

references/diagnosis-template.md is the section source of truth (the diagnosis contract is pinned to it by tests/test_validate_doc.py). Exit 0 means every required section is present; exit 2 means one is missing and sections_missing names it -- most often Alternative Approaches Considered, the section a rushed presentation drops. Then present the validated document to the user. Structure is all this gate checks: whether the diagnosis is correct remains the Codex validation in Step 1.5 plus the user's approval.

---

Output Files

Paths resolved once in Phase 1 Step 0 (.agents/skills/_shared/workspace.py --skill troubleshoot):

File	Author	Purpose
{paths.bug_report}	Lead	Bug Report (Phase 1 synthesis)
{paths.context}	Opus Subagent	Initial error context analysis
{paths.root_cause}	Root Cause Analyst	Root cause analysis (Codex-driven)
{paths.impact}	Impact Investigator	Impact assessment (with Codex risk analysis)
.agents/STATE.md (updated)	Lead	Cross-session bug fix context
Task list (internal)	Lead	Fix implementation tracking

Run artifacts under .agents/logs/, keyed by {slug} so successive runs do not overwrite each other. The repro logs are not part of --verify; the diagnosis is checkable on demand with --require diagnosis (it is not a default required key, because in Phases 1-2 it does not exist yet):

File	Author	Purpose
.agents/logs/troubleshoot-repro-{slug}-initial.log	repro.py	Phase 1 failure capture
.agents/logs/troubleshoot-repro-{slug}-fix-verify.log	repro.py	Phase 3 fix-verification capture
{paths.diagnosis}	Lead	Phase 3 presentation, validated with --contract diagnosis and --require diagnosis

---

Tips

• Codex-first: Every phase consults Codex. This is intentional -- Codex excels at deep code reasoning and pattern recognition that complements Opus's broad context analysis
• Codex for hypothesis testing: When hypotheses conflict, ask Codex to evaluate evidence for each. Codex is better at logical reasoning about code behavior than pattern matching
• Phase 1: Opus subagent (1M context) reproduces the error and gathers full context, then Codex generates initial hypotheses, while Claude collects details from the user
• Phase 2: Agent Teams bidirectional communication allows Root Cause Analyst (Codex-driven) and Impact Investigator (Opus + Codex) to converge on the true root cause
• Phase 3: Codex validates the fix plan before presenting to user. After approval, proceed to implementation with /team-execute
• Competing Hypotheses: If Phase 2 yields inconclusive results, consider spawning additional teammates with adversarial hypotheses (see the /team-execute Phase 2 competing hypotheses pattern)
• Quick bugs: For obvious single-file bugs, skip this skill and fix directly -- use this skill for non-trivial bugs where root cause is unclear
• Ctrl+T: Toggle task list display
• Shift+Up/Down: Navigate between teammates (when using Agent Teams)