Agent skill · research science · aj-geddes
bmad-investigate
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. Hands off as a story to an external dev tool. Use when the user says: - "investigate this bug" / "triage this issue" / "debug triage" - "what's causing [symptom]" / "why is [feature] broken" - "something's wrong with [component]" / "users are reporting [problem]" - "figure out what happened" / "root cause this" - "I need a bug report" / "create an investigation case file" - "forensic analysis" / "diagnose this" - "error triage" / "issue investigation" - "what do we know about [incident/issue]" Three intents: Create (new case file), Update (add evidence to open case), Validate (check draft for completeness before handoff). Output lands in bmad-output/; a fix story is drafted on handoff.
Why this skill is useful
Provides a structured approach to forensic investigation and documentation that the AI wouldn't reliably generate on its own.
What it needs
About 7k tokens when loaded. Last updated 2026-06-20. 471 stars on the source repository.
What this skill does
BMAD Investigate Forensic triage — plan the fix, don't apply it. This skill builds a structured, evidence-graded investigation case file so that whoever picks up the story has a clear picture of what is known, what is suspected, and exactly what needs verifying before any code changes. It deliberately stops before implementation; the result of every investigation is a story handed off to an external dev tool. Persona flavor: Mary (Business Analyst) frames the user impact; Winston (Architect) maps the component topology. The skill is a workflow, not a character. --- Scope Law (read first) This skill PLANS. It reads planning artifacts and existing code to gather evidence. It does NOT write application code, run tests, lint, build, or review diffs. The last artifact it emits is either an updated planning document or a story file marked status: ready-for-dev. If tempted to "fix the bug", "run the suite", or "apply the patch" — STOP. Investigate and hand off. --- Inputs (load these first) Source Why -------- ----- bmad-output/project-context.md Project constitution — architecture, stack, ownership bmad-output/architecture.md Component boundaries, module responsibilities bmad-output/prd.md or tech-spec.md Requirements the broken behavior should satisfy bmad-output/decision-log.md Prior decisions that may relate to the issue User-provided symptom description Primary input — what is failing, when, how Logs / error messages the user pastes in Raw evidence to grade and analyze Existing story files in bmad-output/stories/ Check for duplicate or related work If project-context.md does not exist, ask the user to describe the stack and affected area before proceeding. --- Three Intents Ask which intent applies if ambiguous. Create — new investigation case file from scratch. Update — add new evidence to an existing case file, re-rank hypotheses. Validate — check a draft case file for completeness against the case-file contract. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aj-geddes/bmad-investigate