К основному содержанию
скилл CX Codex

bmad-investigate — скилл для Claude Code: разбор багов

Скилл bmad-investigate для Claude Code расследует баги и оформляет факты в case file. Запускается по запросу найти причину ошибки, разобрать инцидент или обновить расследование.

MIT 102 установок ★ 493 обновлён 2026-06-20

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-investigate -a claude-code
Открыть на GitHub

Что делает bmad-investigate

bmad-investigate собирает симптомы, доказательства и версии причин в файл расследования. Он присваивает доказательствам оценки A, B или C, ранжирует гипотезы и отмечает затронутые компоненты. Результат сохраняется в bmad-output/.

Скилл читает код и проектные документы, ищет упоминания ошибок через Grep и Glob. Он не запускает код и тесты, не меняет приложение и не исправляет баг: результат передаётся внешнему инструменту как история для разработки. Доступны режимы создания дела, добавления новых доказательств и проверки черновика.

Для работы с проектом без bmad-output/project-context.md сначала потребуется описание стека и затронутой области. При расследовании скилл также использует доступные требования, журнал решений, логи и существующие истории из bmad-output/.

Какие задачи решает

  • собрать доказательства по сообщённому багу
  • ранжировать возможные причины сбоя
  • найти связанные компоненты и требования проекта
  • добавить новые факты в открытое расследование
  • проверить черновик дела перед передачей разработчику

Примеры запросов агенту

  • Разберись, почему ломается авторизация, и оформи дело расследования.
  • Добавь эти логи к открытому расследованию и пересмотри версии причин.
  • Проверь черновик расследования на полноту перед передачей разработчику.

Как установить bmad-investigate

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

~/.claude/skills/bmad-investigate/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/bmad-investigate/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о bmad-investigate

Как установить bmad-investigate в Claude Code?

Выполни npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-investigate -a claude-code. Файл скилла находится по пути ~/.claude/skills/bmad-investigate/SKILL.md.

Что делает bmad-investigate?

Он разбирает симптомы и материалы проекта, оценивает доказательства, ранжирует гипотезы и готовит файл расследования. Код не исправляет и тесты не запускает.

Что нужно для работы bmad-investigate?

Если bmad-output/project-context.md отсутствует, нужно описать стек и затронутую область. Для расследования скилл читает доступные проектные документы, логи и истории.

Исходный текст

SKILL.md · MIT
---
name: bmad-investigate
description: |
  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.
allowed-tools: Read, Write, Edit, Glob, Grep, TodoWrite
---

# 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.

---

## Workflow — Create

Use TodoWrite to track progress through these steps.

### Step 1 — Clarify the Symptom

Before investigating, confirm exactly what is observable. Ask (or infer from context):

1. **Symptom** — what behavior is wrong? What is the expected behavior?
2. **Trigger** — when does it occur? Every time? Intermittently? Under load?
3. **Scope** — which users, environments, or configurations are affected?
4. **First seen** — when was the issue introduced or first noticed?
5. **Severity** — data loss, service outage, degraded UX, cosmetic?

Record these as the "Symptom Summary" — this is the anchor for all grading later.

---

### Step 2 — Load Context

Read all available inputs listed above. Extract:

- **Affected components** — which modules/services does the symptom implicate?
  (Cross-reference architecture.md for component responsibilities.)
- **Related requirements** — which FR or NFR does the broken behavior touch?
  (Search prd.md for the area.)
- **Recent decisions** — any ADR or decision-log entry touching the suspected area?
- **Similar stories** — any existing story file referencing the same component?

---

### Step 3 — Gather and Grade Evidence

Collect all available evidence. Assign each item an evidence grade:

| Grade | Meaning |
|-------|---------|
| **A** | Directly observed, reproducible, or confirmed by multiple independent sources. High confidence. |
| **B** | Single-source, inferred from logs, or plausible but not yet reproduced. Medium confidence. |
| **C** | Speculative, based on code reading only, or pattern-matched without direct confirmation. Low confidence. |

Evidence types to gather:
- Error messages and stack traces (paste verbatim; mark as grade A if directly from logs)
- Reproduction steps (grade A if reliably reproduced; B if intermittent)
- Code paths identified via Grep/Glob (grade B — code reading is inference, not proof)
- Configuration or environment differences (grade B unless confirmed in both envs)
- Historical changes — recent commits or PRs that touched the area (grade C without
  reproduction confirmation)
- User reports or support tickets (grade B — external, non-reproducible by default)

Use Grep and Glob to search the codebase for error strings, function names, or
file paths the user mentions. Read code files to trace call paths. Do NOT run the
code — read it.

---

### Step 4 — Form Hypotheses

Based on all grade-A and grade-B evidence, draft 2–5 hypotheses. For each:

- **Hypothesis** — a concise statement of the suspected root cause.
- **Supporting evidence** — which evidence items support it (cite grade).
- **Contradicting evidence** — anything that argues against it.
- **Plausibility rank** — High / Medium / Low (derived from weight of A+B evidence).
- **Verification step** — what a dev agent would need to do to confirm or refute this.

Order hypotheses from most to least plausible.

---

### Step 5 — Map Suspected Components

For each top-2 hypothesis, list:

- **Component** — the module, service, or file suspected.
- **Why suspected** — evidence linkage (grade + description).
- **Blast radius** — what else could be affected if this hypothesis is correct?
- **Confidence** — derived from the highest-grade evidence linking to this component.

---

### Step 6 — Write the Case File

Fill the template:

```
${CLAUDE_PLUGIN_ROOT}/skills/bmad-investigate/templates/investigation.template.md
```

Save to: `bmad-output/investigation-<issue-slug>-<date>.md`

Use Write. Fill every `{{placeholder}}` from your analysis.

---

### Step 7 — Recommend the Planning Response

After completing the case file, determine the planning response:

**Option A — Create a fix story:**
Draft a story file using the standard story contract from bmad-epics-and-stories.
The story Dev Notes MUST cite the investigation case file. Status: `ready-for-dev`.
Naming: `{epic}.{story}.{slug}.story.md` in `bmad-output/stories/`.

**Option B — Update an existing backlog story:**
If a related story exists in backlog, recommend updating its Dev Notes and ACs
to incorporate the investigation findings. Do NOT edit the story yourself unless
asked; describe what needs updating.

**Option C — Escalate to planning:**
If the investigation reveals a systemic issue touching multiple epics, recommend
that the user run `/bmad-planning-orchestrator:bmad-prd` or
`/bmad-planning-orchestrator:bmad-architecture` (Update intent) before a story
is created.

Tell the user which option applies and why. If creating a fix story (Option A),
draft it now unless the user says otherwise.

---

### Step 8 — Log the Decision

Append to `bmad-output/decision-log.md`:

```
## Investigation: [Issue Slug] — [Date]
- Symptom: [one sentence]
- Primary hypothesis: [one sentence]
- Primary suspected component: [name]
- Case file: bmad-output/investigation-<slug>-<date>.md
- Recommended response: [Option A/B/C + story ID if created]
```

---

## Workflow — Update

1. Read the existing case file.
2. Ask: what new evidence has arrived?
3. Add new evidence items with grades; re-rank hypotheses if the weight shifts.
4. Increment the case file version in the header.
5. If the primary hypothesis has changed, note it in the decision-log.

---

## Workflow — Validate

Check the draft case file against this contract checklist:

- [ ] Symptom Summary is concrete and testable (not vague)
- [ ] Every evidence item has a grade (A / B / C)
- [ ] At least two hypotheses are present
- [ ] Each hypothesis has: supporting evidence, contradicting evidence, plausibility rank, verification step
- [ ] Suspected Components section maps each component to specific evidence
- [ ] Recommended Action is stated (Option A / B / C)
- [ ] If Option A: a story draft exists or is clearly specified
- [ ] Decision-log entry exists

Report pass/fail per item. Do not edit unless asked.

---

## Evidence Grading Summary

| Grade | Label | Typical Sources |
|-------|-------|----------------|
| A | Confirmed | Direct logs, reproducible steps, two-source corroboration |
| B | Probable | Single logs, code-read inference, intermittent reproduction, user reports |
| C | Speculative | Educated guess, pattern match, untested hypothesis only |

Never promote a C to an A in the case file — the external dev agent needs to know
what is solid and what is guesswork before they start.

---

## Subagent Strategy

For large-scale investigations spanning multiple suspected components, fan out
parallel read-only agents:

**Agent 1 — Evidence Collector**
```
Read the investigation brief at bmad-output/investigation-scratch/brief.md.
Search the codebase with Grep/Glob for error strings, function names, and file
paths listed. Collect stack-trace context. Write findings (verbatim excerpts +
file paths + line numbers) to bmad-output/investigation-scratch/evidence.md.
Do NOT modify any source files. Grade each item A/B/C.
```

**Agent 2 — Component Mapper**
```
Read bmad-output/architecture.md and the brief at
bmad-output/investigation-scratch/brief.md. For each suspected component,
extract its responsibilities, dependencies, and API contracts.
Write findings to bmad-output/investigation-scratch/components.md.
```

After agents complete, synthesize evidence.md + components.md into the final
case file using the template. Delete scratch files after synthesis.

---

## Reference

- [templates/investigation.template.md](templates/investigation.template.md)
- `bmad-output/decision-log.md` — threaded decision record
- `bmad-output/project-context.md` — project constitution
- `/bmad-planning-orchestrator:bmad-epics-and-stories` — creates the fix story
- `/bmad-planning-orchestrator:bmad-readiness-check` — if investigation reveals
  systemic planning gaps before the fix story is safe to hand off

> ---
> Part of the **BMAD Planning & Orchestrator** plugin — a Claude Code harness for the **BMAD Method** by the **BMAD Code Organization** (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of `bmad-investigate`. All methodology credit belongs to the BMAD Code Organization.

© aj-geddes · MIT · aj-geddes/claude-code-bmad-skills

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
bmad-review bmad-code-org Скилл bmad-review для Claude Code проверяет код и документы через выбранные линзы ревью. Запускается только по явной просьбе провести ревью. CX Codex +1 17 400установок bmad-agent-pm bmad-code-org Скилл bmad-agent-pm для Claude Code и Cursor выступает в роли менеджера продуктов Джона для написания, обновления и проверки планов проектов. CX Codex +1 17 800установок investigate-anything UseOSINT Скилл investigate-anything задаёт правила и структуру для OSINT-расследований по людям, компаниям или доменам. Помогает составить план сбора данных и выбрать подходящий воркфлоу до первых запросов. CX Codex +1 1 800установок bmad-marketing-growth-module reason-machines Скилл bmad-marketing-growth-module для Claude Code объединяет 14 агентов и 6 воркфлоу BMAD Framework для маркетинга SaaS: от стратегии до постов для отдельных площадок. CX Codex +1 910установок bmad-idea akillness Скилл bmad-idea превращает сырую идею в один концепт-артефакт и подсказывает, к какому скиллу идти дальше. Нужен до PRD и спринт-планов. CX Codex +1 368установок bmad-auto bmad-labs Скилл bmad-auto оркеструет реализацию задач по методологии BMAD: ведёт конвейер историй Phase 4 либо переключается на Quick Flow для точечных правок. CX Codex +1 145установок

Из того же набора11

Весь набор →
bmad-brainstorm Скилл bmad-brainstorm запускает структурированные мозговые штурмы по методикам вроде SCAMPER, SWOT и «5 почему». Формирует отчёт с выводами для дальнейшего планирования. CX Codex +1 130установок bmad-tech-spec Скилл bmad-tech-spec для Claude Code создаёт компактный техспек для небольших фич вместо полного PRD и архитектуры. Он собирает один артефакт перед разработкой историй. CX Codex +1 114установок bmad-spec Скилл bmad-spec для Claude Code превращает заметки, PRD или расшифровку в короткий файл SPEC.md с пятью разделами. Он включается, когда нужно сформулировать задачу и границы проекта. CX Codex +1 108установок bmad-readiness-check Скилл bmad-readiness-check для Claude Code сверяет документы планирования перед началом разработки. Запускается по просьбе проверить готовность требований, архитектуры и эпиков к реализации. CX Codex +1 107установок bmad-document-project Скилл bmad-document-project для Claude Code сканирует готовый репозиторий в режиме чтения и сохраняет файл project-documentation.md. Документ фиксирует стек и архитектуру перед планированием дальнейших задач. CX Codex +1 104установок bmad-sprint-planning Скилл bmad-sprint-planning для Claude Code раскладывает истории по зависимостям и формирует план передачи в разработку. Запускается по просьбе упорядочить истории, составить волны или создать sprint-status.yaml. CX Codex +1 104установок bmad-builder Скилл bmad-builder для Claude Code создаёт и проверяет новые скиллы планирования в плагине BMAD. Генерирует структуру каталогов и следит, чтобы логика не выходила за рамки оркестрации. CX Codex +1 102установок bmad-init Скилл bmad-init для Claude Code разворачивает рабочую область планирования BMAD. Запускается при старте нового проекта, чтобы выбрать масштаб и создать стартовые документы. CX Codex +1 100установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой