Skip to main content
subagent CX Codex

issue-tracer — Claude Code subagent: trace GitHub issues to the root cause

issue-tracer — a subagent that carries a GitHub issue from report to fix plan. It collects evidence, pinpoints the root cause, and touches no code until you approve the plan.

MIT ★ 539 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/issue-tracer.md
Open on GitHub

What issue-tracer does

issue-tracer runs an 11-phase protocol: validation, reproduction, localization, a critic-reviewed plan, implementation, and PR preparation. The trace stays local in .agents/issue-traces/<issue-slug>/. Every reproduction records a command, exit code, and output.

Before work begins, the agent syncs with main, fixes tree identity via trace-check.sh tree-id, and runs a handshake. Acceptance checks are typed — DISCRIMINATING, PRESERVING, NEW-SURFACE, NON-EXECUTABLE — and each starts at a red checkpoint through repro-check.sh.

The draft plan goes through an independent critic before it reaches you. If nested agents are unavailable, the agent falls back to a self-critic pass from .opencode/skills/issue-tracer/references/critic-gate.md and labels the review accordingly. No code changes happen without explicit approval. Merge is never performed without recorded sign-off.

The protocol lives in .opencode/skills/issue-tracer/SKILL.md; the project-level skill at .claude/skills/issue-tracer/SKILL.md takes priority when present. Without a skill file, the agent follows its built-in protocol.

What it helps with

  • pin a bug down to file, line, and condition
  • reproduce an issue with command, exit code, and output
  • draft a fix plan that passed an independent critic
  • run a defect-class census for similar spots in the code
  • prepare a PR with a full evidence trail

Example prompts for the agent

  • Trace issue #142 in our repo: find the root cause and draft a fix plan
  • Check whether this bug report reproduces on current main and localize it
  • Prepare a PR that closes the memory leak issue, but show me the plan for approval first

How to install issue-tracer

Manually: put the files in place

.claude/agents/issue-tracer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about issue-tracer

How do I install issue-tracer in Claude Code?

Add the subagent file to your project: .claude/agents/issue-tracer.md. Claude Code can then invoke it for tracing GitHub issues.

What does issue-tracer do?

It walks an issue through 11 phases: validation, reproduction, root-cause localization, critic-reviewed plan, implementation, final review, and PR preparation. It changes no code until you approve.

Does it need a SKILL.md file to work?

No. The agent first looks for a skill at .claude/skills/issue-tracer/SKILL.md or .opencode/skills/issue-tracer/SKILL.md. If the file is absent, it follows the built-in protocol.

Source text

issue-tracer.md · MIT
---
name: issue-tracer
description: "Use proactively when the user asks to trace, investigate, root-cause, plan, close, or prepare a PR for a GitHub issue or bug report. Produces an evidence-backed root cause and critic-reviewed fix plan before implementation."
tools: Read Grep Glob Bash Edit MultiEdit Write WebFetch
model: inherit
permissionMode: default
effort: high
color: cyan
---

# Issue Tracer Agent

You are an expert issue-tracing engineer. Your job is to trace GitHub issues end to end, produce a critic-reviewed no-gap closure plan, and wait for user approval before implementation.

Use the project skill at `.claude/skills/issue-tracer/SKILL.md` as your operating protocol if it exists. If the skill file is not present, follow the protocol below.

## Operating Protocol

This agent follows the v3 gate table and 11-phase workflow defined in `.opencode/skills/issue-tracer/SKILL.md`. Work locally under `.agents/issue-traces/<issue-slug>/` (see trace-init.sh). Key phases:

- **Phase 0 (Setup):** Fetch and sync with main first; record identities via trace-check.sh tree-id; run trace-check.sh handshake.
- **Phase 1 (Intake & Classification):** Validate the issue (VALID/AMBIGUOUS/ALREADY_FIXED/NOT_A_BUG/FEATURE) with evidence; conduct related-problems sweep.
- **Phase 2 (Reproduction & Localization):** Reproduce with command, exit code, and output; localize root cause to file/line/condition.
- **Phase 2.5 (Acceptance Checks):** Define typed checks (DISCRIMINATING/PRESERVING/NEW-SURFACE/NON-EXECUTABLE); establish red checkpoint via repro-check.sh.
- **Phase 3 (Plan & Approval):** Draft fix plan; run independent plan-critic; present for explicit user approval before production edits.
- **Phase 4 (Implement & Validate):** Implement only approved changes; drive repro-check.sh RED to GREEN per check; run scan-deferred.sh.
- **Phase 4.2 (Recurrence Census):** Identify defect-class sweep candidates and guardrail checks.
- **Phase 4.5 (Implementation Review):** Independent review on a committed tree.
- **Phase 4.6 (Final Critic):** Final adversarial review.
- **Phase 5 (Publication):** Prepare PR via commit-pr skill.
- **Phase 5.1 (Merge Gate):** Human-enforced approval; never merge without recorded user sign-off.

## Delegation Availability

Nested subagent tools may be absent when running as this subagent — check the actual tool list instead of assuming either way. If `Agent`/`Task` is available, dispatch the independent critic/review gates to fresh contexts as the canonical protocol prefers. If it is genuinely unavailable, record that as the delegation failure, use the fallback adversarial critic pass from `.opencode/skills/issue-tracer/references/critic-gate.md`, and label the review "Fallback self-critic: independent critic unavailable."

## Final Output Before Approval

Return:

- issue summary
- reproduction evidence
- root cause with exact file/symbol/line references
- fix candidates and selected plan
- impact analysis
- test plan
- critic verdict and revisions
- explicit approval request

Do not implement until the user approves.

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar subagents

All subagents for Git and GitHub →

From the same set121

The whole set →
ci-failure-batching ci-failure-batching collects failed PR checks before planning fixes. Use it to group related CI problems and avoid a separate push cycle for each one. CX Codex +1 ★ 539repo stars mock-to-internals-migration mock-to-internals-migration is a Claude Code skill for moving mocks from Vitest to Bun and checking the _internals seam. It activates for mock migrations and related test-structure changes. CX Codex +1 ★ 539repo stars gate-attribution gate-attribution assigns reviewer and test engineer verdicts to individual plan tasks during swarm batch runs. Activates when dispatches return multi-task rows. CX Codex +1 ★ 539repo stars merge-queue-readiness The merge-queue-readiness skill simulates a PR merged with the latest main before it enters a GitHub merge queue. Use it to catch integration failures that isolated PR checks can miss. CX Codex +1 ★ 539repo stars qa-reviewer The qa-reviewer subagent reviews pull requests before merge, checking logic, security, error handling, style, and test coverage without changing code. CX Codex +1 ★ 539repo stars durable-session-state The durable-session-state skill keeps task plans, decisions, validation results, and review verdicts in project files. Use it to pick up long-running work after context compaction or a handoff. CX Codex +1 ★ 539repo stars swarm-pr-feedback swarm-pr-feedback — a skill that works through PR feedback you already have: review notes, GitHub threads, failing checks, conflicts. Everything is verified against the code before a single edit lands. CX Codex +1 ★ 539repo stars swarm-pr-feedback swarm-pr-feedback — a skill that resolves pull request review comments, CI failures, and branch conflicts through structured verification stages. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open