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
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, whichever tracker files findings.
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:
- Write the path as hops, each with file:line and its runtime precondition.
- Check every precondition against today's code.
- List what changed on the path: system-history
analyze.ts --focuswith every file on the path, then read each regression candidate withpr.ts. - Hold at least two explanations, and run the check that separates them.
- Reproduce in the branch browser when the path runs there.
- Check
AGENTS.md, skills, andpackages/corefor 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-foundand what you checked; - the explanations you ruled out, and how;
- the evidence level:
reproduced,traced(a broken hop shown in code), orinferred; - the framework rule involved;
- the sibling sites.