diagnose

Name: diagnose
Author: tranhieutt

69stars41forks

How to install diagnose?

tranhieutt/software_development_department/diagnose

$npx -y skills add tranhieutt/software_development_department --skill diagnose

Installs into the current project.

Summary

Diagnostic pipeline for complex/intermittent bugs. Uses diagnostics roles for Investigation, Verification, and Solution before Lead Programmer handoff. Use ONLY for non-obvious failures (root cause unclear, reproduction unstable, fixes reverted). NOT for trivial bugs with known c

Files · 1

View on GitHub

SKILL.md

1	# Skill: /diagnose — Complex Bug Diagnostic Pipeline
2
3	## When to invoke (and when NOT to)
4
5	### Use `/diagnose` when:
6	- Bug reproduces but root cause is unclear after one read-pass of the failing code
7	- Previous fix attempts have been reverted ≥ 2 times (symptoms return)
8	- Failure is intermittent (flaky test, race condition, timing-dependent)
9	- Failure occurs in unfamiliar code (agent has no prior context)
10	- User has explicitly requested `/diagnose` or "deep investigation"
11	- Circuit Breaker (Rule 14) tripped on the specialist agent that normally handles this domain
12
13	### Do NOT use `/diagnose` when:
14	- Cause is obvious (null ref, typo, missing import, incorrect import path)
15	- Fix is < 10 LOC and has a clear success check
16	- Bug is in code you just wrote this session (read-pass + local reasoning is faster)
17	- User wants a quick patch and has accepted the tradeoff
18
19	## Pipeline overview
20
21	```
22	Feedback Loop -> Investigation -> Verification -> Solution -> Lead Programmer
23	(signal) (hypothesis) (devil's adv.) (tradeoffs) (assign + exec)
24
25	repro/check command investigation.json verification.json solution.json implementation
26	(fast deterministic (root_cause, (status: confirmed \| (3 options: (delegates to
27	pass/fail signal) evidence[], refuted \| inconclusive, Quick/Strategic/ backend-developer,
28	confidence) reproduction_steps) Future-Proof) qa-engineer, etc.)
29	```
30
31	Each stage produces a required artifact saved to `.investigations/<task_id>/` and a handoff contract (per Rule 16) to the next agent.
32
33	## Stage 0 — Feedback Loop
34
35	Goal: Build the fastest reliable pass/fail signal for the exact symptom
36	before explaining the cause.
37
38	The feedback loop is the highest-leverage part of diagnosis. Do not proceed to
39	root-cause analysis until there is a loop that can reproduce the user's symptom
40	or a documented reason why no loop is possible.
41
42	Try these in roughly this order:
43
44	1. Failing test at the seam that reaches the bug.
45	2. CLI or script invocation with fixture input and expected output.
46	3. Curl/HTTP request against a running service.
47	4. Headless browser script with DOM, console, or network assertions.
48	5. Replay of a captured payload, event, HAR, log, or trace.
49	6. Throwaway harness that calls the affected code path in isolation.
50	7. Property/fuzz loop for broad wrong-output symptoms.
51	8. Bisection or differential loop between known-good and known-bad states.
52
53	Improve the loop before investigating:
54
55	- Faster: remove unrelated setup and narrow the command.
56	- Sharper: assert the specific symptom, not merely "does not crash".
57	- More deterministic: pin time, seed randomness, isolate filesystem/network, or
58	raise intermittent reproduction frequency with stress runs.
59
60	Do not treat Stage 0 as warm-up. It is the main leverage point. A bad loop
61	produces fake certainty, weak hypotheses, and symptom-only fixes.
62
63	If no credible loop can be built, stop and report what was tried. Ask for access
64	to the reproducing environment, a captured artifact, or permission to add
65	temporary instrumentation. Do not proceed on a vibe.
66
67	## Stage 1 — Investigation
68
69	Agent: `diagnostics` (Investigation role)
70	Goal: Produce ranked falsifiable root-cause hypotheses backed by empirical evidence.
71
72	### Inputs
73	- Symptom description (from user or TODO.md bug ID)
74	- Reproduction steps (or "cannot reproduce" + environment)
75	- Relevant log lines, stack traces, error IDs
76	- Feedback loop command/check from Stage 0, or a documented reason no loop can
77	currently be built
78
79	### Required output — `investigation.json`
80	```json
81	{
82	"task_id": "BUG-417",
83	"symptom": "POST /api/orders returns 500 when cart has ≥10 items",
84	"reproduction": {
85	"steps": ["...", "..."],
86	"frequency": "100% \| intermittent (~30%) \| once",
87	"environment": "staging-eu-west-1"
88	},
89	"feedback_loop": {
90	"command": "npm test -- checkout.e2e.test.ts",
91	"signal": "Fails with timeout before hydration marker appears",
92	"reliable": true
93	},
94	"ranked_hypotheses": [
95	{
96	"rank": 1,
97	"cause": "Test clicks #submit before React hydration completes on slow CI runners",
98	"prediction": "Waiting for the hydration marker will make the failure disappear without

People who liked this also viewed

6 picks

Type

diagnose

69stars41forks

View on GitHub

How to install diagnose?

tranhieutt/software_development_department/diagnose

$npx -y skills add tranhieutt/software_development_department --skill diagnose

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Skill: /diagnose — Complex Bug Diagnostic Pipeline
2
3	## When to invoke (and when NOT to)
4
5	### Use `/diagnose` when:
6	- Bug reproduces but root cause is unclear after one read-pass of the failing code
7	- Previous fix attempts have been reverted ≥ 2 times (symptoms return)
8	- Failure is intermittent (flaky test, race condition, timing-dependent)
9	- Failure occurs in unfamiliar code (agent has no prior context)
10	- User has explicitly requested `/diagnose` or "deep investigation"
11	- Circuit Breaker (Rule 14) tripped on the specialist agent that normally handles this domain
12
13	### Do NOT use `/diagnose` when:
14	- Cause is obvious (null ref, typo, missing import, incorrect import path)
15	- Fix is < 10 LOC and has a clear success check
16	- Bug is in code you just wrote this session (read-pass + local reasoning is faster)
17	- User wants a quick patch and has accepted the tradeoff
18
19	## Pipeline overview
20
21	```
22	Feedback Loop -> Investigation -> Verification -> Solution -> Lead Programmer
23	(signal) (hypothesis) (devil's adv.) (tradeoffs) (assign + exec)
24
25	repro/check command investigation.json verification.json solution.json implementation
26	(fast deterministic (root_cause, (status: confirmed \| (3 options: (delegates to
27	pass/fail signal) evidence[], refuted \| inconclusive, Quick/Strategic/ backend-developer,
28	confidence) reproduction_steps) Future-Proof) qa-engineer, etc.)
29	```
30
31	Each stage produces a required artifact saved to `.investigations/<task_id>/` and a handoff contract (per Rule 16) to the next agent.
32
33	## Stage 0 — Feedback Loop
34
35	Goal: Build the fastest reliable pass/fail signal for the exact symptom
36	before explaining the cause.
37
38	The feedback loop is the highest-leverage part of diagnosis. Do not proceed to
39	root-cause analysis until there is a loop that can reproduce the user's symptom
40	or a documented reason why no loop is possible.
41
42	Try these in roughly this order:
43
44	1. Failing test at the seam that reaches the bug.
45	2. CLI or script invocation with fixture input and expected output.
46	3. Curl/HTTP request against a running service.
47	4. Headless browser script with DOM, console, or network assertions.
48	5. Replay of a captured payload, event, HAR, log, or trace.
49	6. Throwaway harness that calls the affected code path in isolation.
50	7. Property/fuzz loop for broad wrong-output symptoms.
51	8. Bisection or differential loop between known-good and known-bad states.
52
53	Improve the loop before investigating:
54
55	- Faster: remove unrelated setup and narrow the command.
56	- Sharper: assert the specific symptom, not merely "does not crash".
57	- More deterministic: pin time, seed randomness, isolate filesystem/network, or
58	raise intermittent reproduction frequency with stress runs.
59
60	Do not treat Stage 0 as warm-up. It is the main leverage point. A bad loop
61	produces fake certainty, weak hypotheses, and symptom-only fixes.
62
63	If no credible loop can be built, stop and report what was tried. Ask for access
64	to the reproducing environment, a captured artifact, or permission to add
65	temporary instrumentation. Do not proceed on a vibe.
66
67	## Stage 1 — Investigation
68
69	Agent: `diagnostics` (Investigation role)
70	Goal: Produce ranked falsifiable root-cause hypotheses backed by empirical evidence.
71
72	### Inputs
73	- Symptom description (from user or TODO.md bug ID)
74	- Reproduction steps (or "cannot reproduce" + environment)
75	- Relevant log lines, stack traces, error IDs
76	- Feedback loop command/check from Stage 0, or a documented reason no loop can
77	currently be built
78
79	### Required output — `investigation.json`
80	```json
81	{
82	"task_id": "BUG-417",
83	"symptom": "POST /api/orders returns 500 when cart has ≥10 items",
84	"reproduction": {
85	"steps": ["...", "..."],
86	"frequency": "100% \| intermittent (~30%) \| once",
87	"environment": "staging-eu-west-1"
88	},
89	"feedback_loop": {
90	"command": "npm test -- checkout.e2e.test.ts",
91	"signal": "Fails with timeout before hydration marker appears",
92	"reliable": true
93	},
94	"ranked_hypotheses": [
95	{
96	"rank": 1,
97	"cause": "Test clicks #submit before React hydration completes on slow CI runners",
98	"prediction": "Waiting for the hydration marker will make the failure disappear without

People who liked this also viewed

6 picks

Type