bug-trace

# Bug trace This skill finds a root cause. It doesn't judge whether the cause is systemic; `investigate-bug` adds that judgment on top. Never change product code while tracing. ## 1. Take in the report ```bash pnpm exec tsx .agents/skills/bug-trace/scripts/bug-intake.ts \ --issue <N|url> | --jira <KEY|url> | --file <path> | --text "<report>" \ [--title "<line>"] [--run <id>] ``` It writes `bug.json` to the run directory and prints the run id (`bug-gh-123`, `bug-eng-456`, or `bug-<date>-<hash>`). Re-running with the same report reuses the run. Jira intake uses `jira-refactor-findings`' client and credentials. ## 2. Split symptoms A report often lists several. Treat each one on its own, with a short label. ## 3. Trace each symptom Follow `references/bug-investigation.md`: 1. Write the path as hops, each with file:line and its runtime precondition. 2. Check every precondition against today's code. 3. List what changed on the path: system-history `analyze.ts --focus` with every file on the path, then read each regression candidate with `pr.ts`. 4. Hold at least two explanations, and run the check that separates them. 5. Reproduce in the branch browser when the path runs there. 6. Check `AGENTS.md`, skills, and `packages/core` for a rule or primitive the code bypasses. When fanning out to sub-agents, give each one the symptom, its entry point, and the whole brief. Don't give it a theory or a short list of files: that list becomes the boundary of its search. ## Output For each symptom: - the hop list, and the broken hop; - the trigger commit, or `none-found` and what you checked; - the explanations you ruled out, and how; - the evidence level: `reproduced`, `traced` (a broken hop shown in code), or `inferred`; - the framework rule involved; - the sibling sites.