issue-tracer

# Issue Tracer

Use this skill to drive a GitHub issue or bug report from intake to a reviewed closure plan, then, after explicit approval, to a minimal verified fix and PR-ready output.

The default behavior is plan-first. You MUST trace the issue end to end, produce a rock-solid plan, send that plan to an independent critic, incorporate the critic's feedback, present the reviewed plan to the user, and wait for explicit user approval before changing production code.

## Source Policy

Use these sources in this order.

1. GitHub source of truth:
   - If `github_mcp_direct` is available, prefer it for issue fetch, PR metadata, repository metadata, file content, and repository search before falling back to CLI commands.
   - Prefer `gh issue view`, `gh issue list`, `gh pr view`, `gh api`, `git log`, `git blame`, `git diff`, and local repo files.
   - If a GitHub MCP server is available, use it for issue, PR, discussion, and repository metadata.
   - Do not ask the user for GitHub credentials. If GitHub access fails, report the exact blocked operation and fall back to local issue text only.
2. Web source of truth:
   - Use `WebFetch` or equivalent web access for current framework/API behavior, release notes, deprecations, security advisories, and external service semantics.
   - Any plan claim based on external docs must include the URL in the plan.
3. Repository source of truth:
   - Never speculate about code. Open every file before referencing it.
   - Verify every symbol, type, command, test, config entry, and path against the repo.

## Non-Negotiable Rules

1. Quality is the only metric that matters. Time pressure does not exist.
2. Do not implement before the user explicitly approves the reviewed plan.
3. Reproduce or explain non-reproducibility before localizing.
4. Localize before fixing. A plausible patch is not enough.
5. Prefer the smallest patch that fully closes the issue without unwired functionality, untested branches, or hidden regressions.
6. Use parallel reads/searches for independent files and subsystems whenever available.
7. Maintain written artifacts so context compaction or handoff cannot erase the investigation state.
8. If confidence drops below 90%, stop and surface the uncertainty instead of guessing.
9. Do not disable, delete, weaken, or skip tests to make the run green.
10. Do not push, merge, publish, delete data, drop databases, rewrite history, or perform destructive operations without explicit user approval.
11. Evidence-grounded reporting: every claim that a command, build, test, lint, or check "passed" or "was validated" MUST include the exact command and its captured output or exit status. Never assert success you did not observe — show the evidence instead of describing it.
12. Tests passing is "plausible," not "correct." A patch that turns the suite green can still overfit the test and miss the real defect. Before declaring closure you MUST justify, in writing, why the fix is correct against the issue's intended behavior — not merely that tests are green.

## Required Artifacts

Create a trace directory before meaningful investigation:

```text
.claude/issue-traces/<issue-id-or-slug>/
├── 01-issue-summary.md
├── 02-reproduction.md
├── 03-localization-log.md
├── 04-root-cause.md
├── 05-fix-plan.md
├── 06-critic-review.md
├── 07-approved-plan.md
├── 08-test-results.md
├── 08b-implementation-review.md
├── 09-pr-body.md
└── state.md
```

If `.claude/` is not writable or should not be modified in the project, use `tmp/issue-traces/<issue-id-or-slug>/` and say so.

Always update `state.md` at phase boundaries with current phase, completed gates, active hypothesis, selected fix candidate, unresolved risks, and next action.

Detailed templates are in:

- `references/evidence-artifacts.md`
- `references/localization-playbook.md`
- `references/critic-gate.md`
- `assets/pr-template.md`

Read the relevant reference before starting that phase.

## Phase 0: Setup and Scope Control

1. Parse the user request into:
   - issue URL, issue number, or bug description
   - repo path or GitHub owner/repo if provided
   - requested mode: plan-only, plan-then-approval, or approved implementation
2. Check repo state:
   - `git status --short`
   - current branch
   - remotes
   - top-level files such as `CLAUDE.md`, `README*`, package manifests, test configs, CI configs
3. If the worktree has unrelated user changes, do not overwrite them. Continue read-only until you can isolate your changes or ask the user.
4. Create the trace directory and initialize `state.md`.
5. Create a todo list with all phases. Mark only one step in progress at a time, and mark steps complete only after gate verification.

### Phase 0 Gate

Proceed only when:

- repo and issue target are identified or the missing identifier is explicitly documented
- worktree safety is checked
- trace directory exists
- todo list exists
- `state.md` records the starting state

## Phase 1: Intake and Reproduction

Goal: convert the issue into a precise, reproducible engineering problem.

1. Retrieve and read the full issue:
   - `gh issue view <id> --comments --json number,title,body,author,labels,state,comments,createdAt,updatedAt,url`
   - Also read linked PRs, commits, discussions, screenshots, logs, and external docs referenced by the issue.
2. Extract into `01-issue-summary.md`:
   - observed behavior
   - expected behavior
   - exact error messages and stack traces
   - reproduction steps
   - environment, platform, versions, feature flags, config
   - acceptance criteria
   - ambiguity list
3. Identify the project's verification commands by reading actual repo files:
   - `CLAUDE.md`
   - `README*`
   - package manifests
   - Makefiles
   - CI workflow files
   - test configs
4. Attempt reproduction using the smallest faithful command or scenario.
5. Capture exact commands, exit codes, and output in `02-reproduction.md`.
6. If no reproduction exists, create a minimal failing test, script, fixture, or manual repro