investigate

Name: investigate
Author: tobihagemann

25installs29forks

How to install investigate?

tobihagemann/turbo/investigate

$npx -y skills add tobihagemann/turbo --skill investigate

Installs into the current project.

Summary

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 r

Files · 1

View on GitHub

SKILL.md

1	# Investigate
2
3	Systematic 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.
4
5	Optional: `$ARGUMENTS` contains the problem description or error message.
6
7	## Step 1: Characterize
8
9	Gather the symptom and establish what is actually happening:
10
11	1. Collect evidence — error message, stack trace, test output, log entries, or user description of unexpected behavior
12	2. Classify the problem type:
13
14	\| Signal \| Type \|
15	\|--------\|------\|
16	\| Stack trace / exception \| Runtime error \|
17	\| Test assertion failure \| Test failure \|
18	\| Compilation / bundler / build error \| Build failure \|
19	\| Type checker error (tsc, mypy, pyright) \| Type error \|
20	\| Slow response / high CPU / memory growth \| Performance \|
21	\| "It does X instead of Y" / no error \| Unexpected behavior \|
22
23	3. 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.
24
25	Record 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.
26
27	## Step 2: Isolate
28
29	Narrow 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.
30
31	### Git Archeology
32
33	For all problem types, check what changed recently near the failure point:
34
35	```bash
36	git log --oneline -20 -- <file>
37	git blame -L <start>,<end> <file>
38	```
39
40	If a known-good state exists (e.g., "this worked yesterday"), consider `git bisect` to pinpoint the breaking commit.
41
42	### Scope Narrowing
43
44	- Stack traces: Read the throwing function and its callers — full functions, not just the flagged line
45	- Test failures: Read both the test and the system under test
46	- Build errors: Read the config file and the referenced source
47	- Unexpected behavior: Trace the data flow from input to the unexpected output
48
49	## Step 3: Hypothesize
50
51	Generate 2-4 hypotheses ranked by likelihood. Each hypothesis must be falsifiable — specify what evidence would confirm or refute it.
52
53	Format:
54
55	```
56	H1 (most likely): [description] — confirmed if [X], refuted if [Y]
57	H2: [description] — confirmed if [X], refuted if [Y]
58	H3: [description] — confirmed if [X], refuted if [Y]
59	```
60
61	### Parallel Investigation
62
63	For complex problems with 3+ hypotheses and a non-obvious root cause, spawn parallel investigators simultaneously.
64
65	Spawn condition: 3+ hypotheses AND the problem is not a simple typo, missing import, or syntax error.
66
67	Skip when 1-2 hypotheses are obvious (e.g., stack trace points directly to the bug).
68
69	Use the Agent tool to launch all agents below in a single assistant message so they run concurrently. Run them in the foreground so all their results return in this turn. Each Agent call uses `model: "opus"`. Expect (one Agent per hypothesis + one Codex Agent) total. State the count explicitly when emitting the calls.
70
71	- Hypothesis Agent (one 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.
72	- Codex Agent: Launch one Agent whose prompt instructs the subagent to invoke `/consult-codex` via the Skill tool 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 after the Agent returns.
73
74	After 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.
75
76	## Step 4: Test
77
78	Verify each hypothesis with minimal, targeted actions:
79
80	\| Action Type \| Tool \|
81	\|-------------\|------\|
82	\| Find usage or pattern \| Grep \|
83	\| Read surrounding code \| Read \|
84	\| Check recent changes \| Bash (`git log`, `git blame`, `git diff`) \|
85	\| Run isolated test \| Bash (specific test command) \|
86	\| Check dependency version \| Bash (`npm l

People who liked this also viewed

6 picks

Type

investigate

25installs29forks

View on GitHub

How to install investigate?

tobihagemann/turbo/investigate

$npx -y skills add tobihagemann/turbo --skill investigate

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Investigate
2
3	Systematic 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.
4
5	Optional: `$ARGUMENTS` contains the problem description or error message.
6
7	## Step 1: Characterize
8
9	Gather the symptom and establish what is actually happening:
10
11	1. Collect evidence — error message, stack trace, test output, log entries, or user description of unexpected behavior
12	2. Classify the problem type:
13
14	\| Signal \| Type \|
15	\|--------\|------\|
16	\| Stack trace / exception \| Runtime error \|
17	\| Test assertion failure \| Test failure \|
18	\| Compilation / bundler / build error \| Build failure \|
19	\| Type checker error (tsc, mypy, pyright) \| Type error \|
20	\| Slow response / high CPU / memory growth \| Performance \|
21	\| "It does X instead of Y" / no error \| Unexpected behavior \|
22
23	3. 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.
24
25	Record 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.
26
27	## Step 2: Isolate
28
29	Narrow 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.
30
31	### Git Archeology
32
33	For all problem types, check what changed recently near the failure point:
34
35	```bash
36	git log --oneline -20 -- <file>
37	git blame -L <start>,<end> <file>
38	```
39
40	If a known-good state exists (e.g., "this worked yesterday"), consider `git bisect` to pinpoint the breaking commit.
41
42	### Scope Narrowing
43
44	- Stack traces: Read the throwing function and its callers — full functions, not just the flagged line
45	- Test failures: Read both the test and the system under test
46	- Build errors: Read the config file and the referenced source
47	- Unexpected behavior: Trace the data flow from input to the unexpected output
48
49	## Step 3: Hypothesize
50
51	Generate 2-4 hypotheses ranked by likelihood. Each hypothesis must be falsifiable — specify what evidence would confirm or refute it.
52
53	Format:
54
55	```
56	H1 (most likely): [description] — confirmed if [X], refuted if [Y]
57	H2: [description] — confirmed if [X], refuted if [Y]
58	H3: [description] — confirmed if [X], refuted if [Y]
59	```
60
61	### Parallel Investigation
62
63	For complex problems with 3+ hypotheses and a non-obvious root cause, spawn parallel investigators simultaneously.
64
65	Spawn condition: 3+ hypotheses AND the problem is not a simple typo, missing import, or syntax error.
66
67	Skip when 1-2 hypotheses are obvious (e.g., stack trace points directly to the bug).
68
69	Use the Agent tool to launch all agents below in a single assistant message so they run concurrently. Run them in the foreground so all their results return in this turn. Each Agent call uses `model: "opus"`. Expect (one Agent per hypothesis + one Codex Agent) total. State the count explicitly when emitting the calls.
70
71	- Hypothesis Agent (one 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.
72	- Codex Agent: Launch one Agent whose prompt instructs the subagent to invoke `/consult-codex` via the Skill tool 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 after the Agent returns.
73
74	After 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.
75
76	## Step 4: Test
77
78	Verify each hypothesis with minimal, targeted actions:
79
80	\| Action Type \| Tool \|
81	\|-------------\|------\|
82	\| Find usage or pattern \| Grep \|
83	\| Read surrounding code \| Read \|
84	\| Check recent changes \| Bash (`git log`, `git blame`, `git diff`) \|
85	\| Run isolated test \| Bash (specific test command) \|
86	\| Check dependency version \| Bash (`npm l

People who liked this also viewed

6 picks

Type