bmad-investigate

Name: bmad-investigate
Author: aj-geddes

467stars73forks

How to install bmad-investigate?

aj-geddes/claude-code-bmad-skills/bmad-investigate

$npx -y skills add aj-geddes/claude-code-bmad-skills --skill bmad-investigate

Installs into the current project.

Summary

Forensic bug and issue triage. Produces a graded investigation case file: symptoms, evidence (graded A/B/C by confidence), ranked hypotheses, suspected components, and a recommended planning response. INVESTIGATES and DOCUMENTS only — does NOT fix code, run tests, or implement. H

Files · 1

View on GitHub

SKILL.md

1	# BMAD Investigate
2
3	Forensic triage — plan the fix, don't apply it.
4
5	This skill builds a structured, evidence-graded investigation case file so that
6	whoever picks up the story has a clear picture of what is known, what is suspected,
7	and exactly what needs verifying before any code changes. It deliberately stops
8	before implementation; the result of every investigation is a story handed off to
9	an external dev tool.
10
11	Persona flavor: Mary (Business Analyst) frames the user impact; Winston (Architect)
12	maps the component topology. The skill is a workflow, not a character.
13
14	---
15
16	## Scope Law (read first)
17
18	This skill PLANS. It reads planning artifacts and existing code to gather evidence.
19	It does NOT write application code, run tests, lint, build, or review diffs.
20	The last artifact it emits is either an updated planning document or a story file
21	marked `status: ready-for-dev`. If tempted to "fix the bug", "run the suite", or
22	"apply the patch" — STOP. Investigate and hand off.
23
24	---
25
26	## Inputs (load these first)
27
28	\| Source \| Why \|
29	\|--------\|-----\|
30	\| `bmad-output/project-context.md` \| Project constitution — architecture, stack, ownership \|
31	\| `bmad-output/architecture.md` \| Component boundaries, module responsibilities \|
32	\| `bmad-output/prd.md` or `tech-spec.md` \| Requirements the broken behavior should satisfy \|
33	\| `bmad-output/decision-log.md` \| Prior decisions that may relate to the issue \|
34	\| User-provided symptom description \| Primary input — what is failing, when, how \|
35	\| Logs / error messages the user pastes in \| Raw evidence to grade and analyze \|
36	\| Existing story files in `bmad-output/stories/` \| Check for duplicate or related work \|
37
38	If project-context.md does not exist, ask the user to describe the stack and
39	affected area before proceeding.
40
41	---
42
43	## Three Intents
44
45	Ask which intent applies if ambiguous.
46
47	- Create — new investigation case file from scratch.
48	- Update — add new evidence to an existing case file, re-rank hypotheses.
49	- Validate — check a draft case file for completeness against the case-file contract.
50
51	---
52
53	## Workflow — Create
54
55	Use TodoWrite to track progress through these steps.
56
57	### Step 1 — Clarify the Symptom
58
59	Before investigating, confirm exactly what is observable. Ask (or infer from context):
60
61	1. Symptom — what behavior is wrong? What is the expected behavior?
62	2. Trigger — when does it occur? Every time? Intermittently? Under load?
63	3. Scope — which users, environments, or configurations are affected?
64	4. First seen — when was the issue introduced or first noticed?
65	5. Severity — data loss, service outage, degraded UX, cosmetic?
66
67	Record these as the "Symptom Summary" — this is the anchor for all grading later.
68
69	---
70
71	### Step 2 — Load Context
72
73	Read all available inputs listed above. Extract:
74
75	- Affected components — which modules/services does the symptom implicate?
76	(Cross-reference architecture.md for component responsibilities.)
77	- Related requirements — which FR or NFR does the broken behavior touch?
78	(Search prd.md for the area.)
79	- Recent decisions — any ADR or decision-log entry touching the suspected area?
80	- Similar stories — any existing story file referencing the same component?
81
82	---
83
84	### Step 3 — Gather and Grade Evidence
85
86	Collect all available evidence. Assign each item an evidence grade:
87
88	\| Grade \| Meaning \|
89	\|-------\|---------\|
90	\| A \| Directly observed, reproducible, or confirmed by multiple independent sources. High confidence. \|
91	\| B \| Single-source, inferred from logs, or plausible but not yet reproduced. Medium confidence. \|
92	\| C \| Speculative, based on code reading only, or pattern-matched without direct confirmation. Low confidence. \|
93
94	Evidence types to gather:
95	- Error messages and stack traces (paste verbatim; mark as grade A if directly from logs)
96	- Reproduction steps (grade A if reliably reproduced; B if intermittent)
97	- C

People who liked this also viewed

6 picks

Type

bmad-investigate

467stars73forks

View on GitHub

How to install bmad-investigate?

aj-geddes/claude-code-bmad-skills/bmad-investigate

$npx -y skills add aj-geddes/claude-code-bmad-skills --skill bmad-investigate

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# BMAD Investigate
2
3	Forensic triage — plan the fix, don't apply it.
4
5	This skill builds a structured, evidence-graded investigation case file so that
6	whoever picks up the story has a clear picture of what is known, what is suspected,
7	and exactly what needs verifying before any code changes. It deliberately stops
8	before implementation; the result of every investigation is a story handed off to
9	an external dev tool.
10
11	Persona flavor: Mary (Business Analyst) frames the user impact; Winston (Architect)
12	maps the component topology. The skill is a workflow, not a character.
13
14	---
15
16	## Scope Law (read first)
17
18	This skill PLANS. It reads planning artifacts and existing code to gather evidence.
19	It does NOT write application code, run tests, lint, build, or review diffs.
20	The last artifact it emits is either an updated planning document or a story file
21	marked `status: ready-for-dev`. If tempted to "fix the bug", "run the suite", or
22	"apply the patch" — STOP. Investigate and hand off.
23
24	---
25
26	## Inputs (load these first)
27
28	\| Source \| Why \|
29	\|--------\|-----\|
30	\| `bmad-output/project-context.md` \| Project constitution — architecture, stack, ownership \|
31	\| `bmad-output/architecture.md` \| Component boundaries, module responsibilities \|
32	\| `bmad-output/prd.md` or `tech-spec.md` \| Requirements the broken behavior should satisfy \|
33	\| `bmad-output/decision-log.md` \| Prior decisions that may relate to the issue \|
34	\| User-provided symptom description \| Primary input — what is failing, when, how \|
35	\| Logs / error messages the user pastes in \| Raw evidence to grade and analyze \|
36	\| Existing story files in `bmad-output/stories/` \| Check for duplicate or related work \|
37
38	If project-context.md does not exist, ask the user to describe the stack and
39	affected area before proceeding.
40
41	---
42
43	## Three Intents
44
45	Ask which intent applies if ambiguous.
46
47	- Create — new investigation case file from scratch.
48	- Update — add new evidence to an existing case file, re-rank hypotheses.
49	- Validate — check a draft case file for completeness against the case-file contract.
50
51	---
52
53	## Workflow — Create
54
55	Use TodoWrite to track progress through these steps.
56
57	### Step 1 — Clarify the Symptom
58
59	Before investigating, confirm exactly what is observable. Ask (or infer from context):
60
61	1. Symptom — what behavior is wrong? What is the expected behavior?
62	2. Trigger — when does it occur? Every time? Intermittently? Under load?
63	3. Scope — which users, environments, or configurations are affected?
64	4. First seen — when was the issue introduced or first noticed?
65	5. Severity — data loss, service outage, degraded UX, cosmetic?
66
67	Record these as the "Symptom Summary" — this is the anchor for all grading later.
68
69	---
70
71	### Step 2 — Load Context
72
73	Read all available inputs listed above. Extract:
74
75	- Affected components — which modules/services does the symptom implicate?
76	(Cross-reference architecture.md for component responsibilities.)
77	- Related requirements — which FR or NFR does the broken behavior touch?
78	(Search prd.md for the area.)
79	- Recent decisions — any ADR or decision-log entry touching the suspected area?
80	- Similar stories — any existing story file referencing the same component?
81
82	---
83
84	### Step 3 — Gather and Grade Evidence
85
86	Collect all available evidence. Assign each item an evidence grade:
87
88	\| Grade \| Meaning \|
89	\|-------\|---------\|
90	\| A \| Directly observed, reproducible, or confirmed by multiple independent sources. High confidence. \|
91	\| B \| Single-source, inferred from logs, or plausible but not yet reproduced. Medium confidence. \|
92	\| C \| Speculative, based on code reading only, or pattern-matched without direct confirmation. Low confidence. \|
93
94	Evidence types to gather:
95	- Error messages and stack traces (paste verbatim; mark as grade A if directly from logs)
96	- Reproduction steps (grade A if reliably reproduced; B if intermittent)
97	- C

People who liked this also viewed

6 picks

Type