{"id":"3ce39e10-a412-42d5-9fc7-c5236d4c0aac","shortId":"eADVhD","kind":"skill","title":"investigate","tagline":"Systematically investigate bugs, test failures, build errors, performance issues, or unexpected behavior by cycling through characterize-isolate-hypothesize-test steps. Use when the user asks to \"investigate this bug\", \"debug this\", \"figure out why this fails\", \"find the root cau","description":"# Investigate\n\nSystematic methodology for finding the root cause of bugs, failures, and unexpected behavior. Cycle through characterize-isolate-hypothesize-test steps, with oracle escalation for hard problems. Diagnose the root cause — do not apply fixes.\n\nOptional: `$ARGUMENTS` contains the problem description or error message.\n\n## Step 1: Characterize\n\nGather the symptom and establish what is actually happening:\n\n1. **Collect evidence** — error message, stack trace, test output, log entries, or user description of unexpected behavior\n2. **Classify the problem type**:\n\n| Signal | Type |\n|--------|------|\n| Stack trace / exception | Runtime error |\n| Test assertion failure | Test failure |\n| Compilation / bundler / build error | Build failure |\n| Type checker error (tsc, mypy, pyright) | Type error |\n| Slow response / high CPU / memory growth | Performance |\n| \"It does X instead of Y\" / no error | Unexpected behavior |\n\n3. **Establish reproduction** — run the failing command, test, or operation. If the problem cannot be reproduced (intermittent, environment-specific), document the constraints and proceed with historical evidence.\n\nRecord the exact reproduction command and its output for verification. For intermittent or long-running reproductions, use the Monitor tool to tail logs filtered for relevant signals (errors, stack traces, specific identifiers) so failures surface live while you work.\n\n## Step 2: Isolate\n\nNarrow from \"something is wrong\" to \"the problem is in this area.\" Read [references/problem-type-playbooks.md](references/problem-type-playbooks.md) for type-specific first moves and tool sequences.\n\n### Git Archeology\n\nFor all problem types, check what changed recently near the failure point:\n\n```bash\ngit log --oneline -20 -- <file>\ngit blame -L <start>,<end> <file>\n```\n\nIf a known-good state exists (e.g., \"this worked yesterday\"), consider `git bisect` to pinpoint the breaking commit.\n\n### Scope Narrowing\n\n- **Stack traces**: Read the throwing function and its callers — full functions, not just the flagged line\n- **Test failures**: Read both the test and the system under test\n- **Build errors**: Read the config file and the referenced source\n- **Unexpected behavior**: Trace the data flow from input to the unexpected output\n\n## Step 3: Hypothesize\n\nGenerate 2-4 hypotheses ranked by likelihood. Each hypothesis must be **falsifiable** — specify what evidence would confirm or refute it.\n\nFormat:\n\n```\nH1 (most likely): [description] — confirmed if [X], refuted if [Y]\nH2: [description] — confirmed if [X], refuted if [Y]\nH3: [description] — confirmed if [X], refuted if [Y]\n```\n\n### Parallel Investigation\n\nFor complex problems with 3+ hypotheses and a non-obvious root cause, spawn parallel investigators simultaneously.\n\n**Spawn condition**: 3+ hypotheses AND the problem is not a simple typo, missing import, or syntax error.\n\n**Skip** when 1-2 hypotheses are obvious (e.g., stack trace points directly to the bug).\n\nLaunch in parallel (`model: \"opus\"`, do not set `run_in_background`):\n\n1. **One subagent per hypothesis** — each receives the hypothesis, relevant file paths, what evidence to look for, and instructions to report **confirmed** / **refuted** / **inconclusive** with evidence. Budget: max 5 tool calls per subagent.\n2. **Codex consultation** (read-only) — launch an agent that runs the `/consult-codex` skill with a focused prompt describing the problem, reproduction, and files examined. The multi-turn conversation allows it to dig deeper into patterns the hypothesis-driven subagents miss. Run the `/evaluate-findings` skill on its output.\n\nAfter all investigators complete, merge results. Codex findings that overlap with a subagent's confirmed hypothesis reinforce confidence. Novel codex findings become additional hypotheses to test in Step 4.\n\n## Step 4: Test\n\nVerify each hypothesis with minimal, targeted actions:\n\n| Action Type | Tool |\n|-------------|------|\n| Find usage or pattern | Grep |\n| Read surrounding code | Read |\n| Check recent changes | Bash (`git log`, `git blame`, `git diff`) |\n| Run isolated test | Bash (specific test command) |\n| Check dependency version | Bash (`npm ls`, `pip3 show`, etc.) |\n| Inspect runtime state | Bash (add temporary logging, run, check output) |\n\nRecord each result:\n\n| Hypothesis | Verdict | Evidence |\n|------------|---------|----------|\n| H1 | confirmed / refuted / inconclusive | [what was found] |\n| H2 | confirmed / refuted / inconclusive | [what was found] |\n\n### Iteration\n\nIf all hypotheses are refuted or inconclusive:\n\n1. Document what was learned — each refuted hypothesis eliminates a possibility and narrows the search\n2. Return to Step 2 with the new information to re-isolate\n3. Generate new hypotheses in Step 3 based on updated understanding\n\n**Cycle budget**: maximum 2 full cycles (hypothesize → test → learn → repeat) before escalating.\n\n## Escalation\n\nAfter 2 failed hypothesis cycles, offer escalation to `/consult-oracle` via `AskUserQuestion`:\n\n```\nInvestigation stalled after [N] hypothesis cycles.\n\nTested: [summary of hypotheses and evidence]\nRemaining unknowns: [what is still unclear]\n\nEscalate to Oracle? (consults external model with full context)\n```\n\nProceed only if the user approves.\n\n## Investigation Report\n\nOutput results as text:\n\n```\nInvestigation Report:\n\nProblem: [one-line description]\nType: [runtime error | test failure | build failure | type error | performance | unexpected behavior]\nRoot cause: [confirmed cause, or \"unresolved\" with best hypothesis]\n\nEvidence:\n- [what confirmed the root cause]\n\nSuggested fix: [description of what to change, or \"needs further investigation\"]\nReproduction command: [command to verify the fix once applied]\n\nHypotheses tested:\n1. [hypothesis] — [confirmed/refuted/inconclusive] — [evidence]\n2. [hypothesis] — [confirmed/refuted/inconclusive] — [evidence]\n\nEscalation: [none | oracle]\n```\n\nThen use the TaskList tool and proceed to any remaining task.\n\n## Rules\n\n- If the problem turns out to be environmental (wrong Node version, missing dependency, OS-specific), report that clearly — it may not require a code fix.\n- If the problem is in a dependency (not the project's code), document the dependency issue and suggest workaround options rather than patching the dependency.","tags":["investigate","turbo","tobihagemann","agent-skills","claude-code","claude-skills","developer-tools","skills"],"capabilities":["skill","source-tobihagemann","skill-investigate","topic-agent-skills","topic-claude-code","topic-claude-skills","topic-developer-tools","topic-skills"],"categories":["turbo"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/tobihagemann/turbo/investigate","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add tobihagemann/turbo","source_repo":"https://github.com/tobihagemann/turbo","install_from":"skills.sh"}},"qualityScore":"0.590","qualityRationale":"deterministic score 0.59 from registry signals: · indexed on github topic:agent-skills · 280 github stars · SKILL.md body (6,284 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T00:54:10.338Z","embedding":null,"createdAt":"2026-04-18T22:03:51.163Z","updatedAt":"2026-04-22T00:54:10.338Z","lastSeenAt":"2026-04-22T00:54:10.338Z","tsv":"'-2':441 '-20':278 '-4':357 '/consult-codex':509 '/consult-oracle':722 '/evaluate-findings':542 '1':89,100,440,464,662,820 '2':117,234,356,497,677,681,704,715,824 '3':165,353,408,423,690,696 '4':575,577 '5':492 'action':585,586 'actual':98 'add':628 'addit':569 'agent':505 'allow':527 'appli':77,817 'approv':757 'archeolog':261 'area':247 'argument':80 'ask':27 'askuserquest':724 'assert':130 'background':463 'base':697 'bash':274,601,611,618,627 'becom':568 'behavior':13,56,116,164,341,782 'best':790 'bisect':295 'blame':280,605 'break':299 'budget':490,702 'bug':4,31,52,452 'build':7,136,138,330,776 'bundler':135 'call':494 'caller':311 'cannot':178 'cau':42 'caus':50,74,416,784,786,797 'chang':268,600,804 'character':18,60,90 'characterize-isolate-hypothesize-test':17,59 'check':266,598,615,632 'checker':141 'classifi':118 'clear':861 'code':596,867,880 'codex':498,553,566 'collect':101 'command':171,197,614,810,811 'commit':300 'compil':134 'complet':550 'complex':405 'condit':422 'confid':564 'config':334 'confirm':371,380,388,396,485,561,641,648,785,794 'confirmed/refuted/inconclusive':822,826 'consid':293 'constraint':187 'consult':499,746 'contain':81 'context':751 'convers':526 'cpu':151 'cycl':15,57,701,706,718,730 'data':344 'debug':32 'deeper':531 'depend':616,855,875,883,893 'describ':515 'descript':84,113,379,387,395,770,800 'diagnos':71 'diff':607 'dig':530 'direct':449 'document':185,663,881 'driven':537 'e.g':289,445 'elimin':670 'entri':110 'environ':183 'environment':850 'environment-specif':182 'error':8,86,103,128,137,142,147,162,221,331,437,773,779 'escal':67,712,713,720,743,828 'establish':95,166 'etc':623 'evid':102,192,369,477,489,639,736,792,823,827 'exact':195 'examin':521 'except':126 'exist':288 'extern':747 'fail':38,170,716 'failur':6,53,131,133,139,227,272,320,775,777 'falsifi':366 'figur':34 'file':335,474,520 'filter':217 'find':39,47,554,567,589 'first':255 'fix':78,799,815,868 'flag':317 'flow':345 'focus':513 'format':375 'found':646,653 'full':312,705,750 'function':308,313 'gather':91 'generat':355,691 'git':260,275,279,294,602,604,606 'good':286 'grep':593 'growth':153 'h1':376,640 'h2':386,647 'h3':394 'happen':99 'hard':69 'high':150 'histor':191 'hypothes':20,62,354,358,409,424,442,570,657,693,707,734,818 'hypothesi':363,468,472,536,562,581,637,669,717,729,791,821,825 'hypothesis-driven':535 'identifi':225 'import':434 'inconclus':487,643,650,661 'inform':685 'input':347 'inspect':624 'instead':158 'instruct':482 'intermitt':181,204 'investig':1,3,29,43,403,419,549,725,758,764,808 'isol':19,61,235,609,689 'issu':10,884 'iter':654 'known':285 'known-good':284 'l':281 'launch':453,503 'learn':666,709 'like':378 'likelihood':361 'line':318,769 'live':229 'log':109,216,276,603,630 'long':207 'long-run':206 'look':479 'ls':620 'max':491 'maximum':703 'may':863 'memori':152 'merg':551 'messag':87,104 'methodolog':45 'minim':583 'miss':433,539,854 'model':456,748 'monitor':212 'move':256 'multi':524 'multi-turn':523 'must':364 'mypi':144 'n':728 'narrow':236,302,674 'near':270 'need':806 'new':684,692 'node':852 'non':413 'non-obvi':412 'none':829 'novel':565 'npm':619 'obvious':414,444 'offer':719 'one':465,768 'one-lin':767 'onelin':277 'oper':174 'option':79,888 'opus':457 'oracl':66,745,830 'os':857 'os-specif':856 'output':108,200,351,546,633,760 'overlap':556 'parallel':402,418,455 'patch':891 'path':475 'pattern':533,592 'per':467,495 'perform':9,154,780 'pinpoint':297 'pip3':621 'point':273,448 'possibl':672 'problem':70,83,120,177,243,264,406,427,517,766,845,871 'proceed':189,752,837 'project':878 'prompt':514 'pyright':145 'rank':359 'rather':889 're':688 're-isol':687 'read':248,305,321,332,501,594,597 'read-on':500 'receiv':470 'recent':269,599 'record':193,634 'referenc':338 'references/problem-type-playbooks.md':249,250 'refut':373,383,391,399,486,642,649,659,668 'reinforc':563 'relev':219,473 'remain':737,840 'repeat':710 'report':484,759,765,859 'reproduc':180 'reproduct':167,196,209,518,809 'requir':865 'respons':149 'result':552,636,761 'return':678 'root':41,49,73,415,783,796 'rule':842 'run':168,208,461,507,540,608,631 'runtim':127,625,772 'scope':301 'search':676 'sequenc':259 'set':460 'show':622 'signal':122,220 'simpl':431 'simultan':420 'skill':510,543 'skill-investigate' 'skip':438 'slow':148 'someth':238 'sourc':339 'source-tobihagemann' 'spawn':417,421 'specif':184,224,254,612,858 'specifi':367 'stack':105,124,222,303,446 'stall':726 'state':287,626 'step':22,64,88,233,352,574,576,680,695 'still':741 'subag':466,496,538,559 'suggest':798,886 'summari':732 'surfac':228 'surround':595 'symptom':93 'syntax':436 'system':327 'systemat':2,44 'tail':215 'target':584 'task':841 'tasklist':834 'temporari':629 'test':5,21,63,107,129,132,172,319,324,329,572,578,610,613,708,731,774,819 'text':763 'throw':307 'tool':213,258,493,588,835 'topic-agent-skills' 'topic-claude-code' 'topic-claude-skills' 'topic-developer-tools' 'topic-skills' 'trace':106,125,223,304,342,447 'tsc':143 'turn':525,846 'type':121,123,140,146,253,265,587,771,778 'type-specif':252 'typo':432 'unclear':742 'understand':700 'unexpect':12,55,115,163,340,350,781 'unknown':738 'unresolv':788 'updat':699 'usag':590 'use':23,210,832 'user':26,112,756 'verdict':638 'verif':202 'verifi':579,813 'version':617,853 'via':723 'work':232,291 'workaround':887 'would':370 'wrong':240,851 'x':157,382,390,398 'y':160,385,393,401 'yesterday':292","prices":[{"id":"5ee419d9-eb72-42df-a5eb-bf9e0e501f44","listingId":"3ce39e10-a412-42d5-9fc7-c5236d4c0aac","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"tobihagemann","category":"turbo","install_from":"skills.sh"},"createdAt":"2026-04-18T22:03:51.163Z"}],"sources":[{"listingId":"3ce39e10-a412-42d5-9fc7-c5236d4c0aac","source":"github","sourceId":"tobihagemann/turbo/investigate","sourceUrl":"https://github.com/tobihagemann/turbo/tree/main/skills/investigate","isPrimary":false,"firstSeenAt":"2026-04-18T22:03:51.163Z","lastSeenAt":"2026-04-22T00:54:10.338Z"}],"details":{"listingId":"3ce39e10-a412-42d5-9fc7-c5236d4c0aac","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"tobihagemann","slug":"investigate","github":{"repo":"tobihagemann/turbo","stars":280,"topics":["agent-skills","claude-code","claude-skills","developer-tools","skills"],"license":"mit","html_url":"https://github.com/tobihagemann/turbo","pushed_at":"2026-04-21T12:22:12Z","description":"A composable dev process for Claude Code, packaged as modular skills.","skill_md_sha":"d9f0fdd19545bf6e085867b67148be7f3a9d6d77","skill_md_path":"skills/investigate/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/tobihagemann/turbo/tree/main/skills/investigate"},"layout":"multi","source":"github","category":"turbo","frontmatter":{"name":"investigate","description":"Systematically investigate bugs, test failures, build errors, performance issues, or unexpected behavior by cycling through characterize-isolate-hypothesize-test steps. Use when the user asks to \"investigate this bug\", \"debug this\", \"figure out why this fails\", \"find the root cause\", \"why is this broken\", \"troubleshoot this\", \"diagnose the issue\", \"what's causing this error\", \"look into this failure\", \"why is this test failing\", or \"track down this bug\"."},"skills_sh_url":"https://skills.sh/tobihagemann/turbo/investigate"},"updatedAt":"2026-04-22T00:54:10.338Z"}}