fix(bmm): tighten bmad-investigate per review and quality findings
Maintainer review (PR #2364): - shorten frontmatter description - add customize.toml for case-file template, output subdir, filename, persistent_facts, prepend/append steps, on_complete - subagent delegation discipline for context-heavy investigation steps - replace ambiguous "Halt" closer at each outcome with self-documenting "Pause for user with the recap above; wait for direction." Workflow-builder quality findings: - move case-file-template.md to references/ (path standards) - align activation with sibling 4-implementation skills (customize.toml resolution, persistent_facts, greet) - operationalize promised flows: existing-case resume (Outcome 0), evidence-light branch (Outcome 1), refutation pass (Outcome 3), trivial-fix hand-off (Outcome 4) - define High/Medium/Low confidence in Outcome 5 - name concrete next-step skills at Outcome 5 (bmad-quick-dev, bmad-correct-course, bmad-create-story, bmad-code-review) - add Hand-off Brief and Side Findings to case-file template
This commit is contained in:
AJ Côté
parent
7b590b0a90
commit
697d92e355
|
|
@ -87,7 +87,8 @@ Try to discover the following:
|
||||||
- Research Documents (`/*research*.md`)
|
- Research Documents (`/*research*.md`)
|
||||||
- Project Documentation (generally multiple documents might be found for this in the `{project_knowledge}` or `docs` folder.)
|
- Project Documentation (generally multiple documents might be found for this in the `{project_knowledge}` or `docs` folder.)
|
||||||
- Project Context (`**/project-context.md`)
|
- Project Context (`**/project-context.md`)
|
||||||
- Investigation Files (`{implementation_artifacts}/investigations/*-investigation.md`) — `bmad-investigate` case files when the PRD is being driven by a forensic investigation rather than greenfield ideation.
|
- Investigation Files (`{implementation_artifacts}/investigations/*-investigation.md`) — `bmad-investigate` case files
|
||||||
|
when the PRD is being driven by a forensic investigation rather than greenfield ideation.
|
||||||
|
|
||||||
<critical>Confirm what you have found with the user, along with asking if the user wants to provide anything else. Only after this confirmation will you proceed to follow the loading rules</critical>
|
<critical>Confirm what you have found with the user, along with asking if the user wants to provide anything else. Only after this confirmation will you proceed to follow the loading rules</critical>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,204 +1,196 @@
|
||||||
---
|
---
|
||||||
name: bmad-investigate
|
name: bmad-investigate
|
||||||
description: Forensic case investigation with evidence-graded findings, calibrated to the input. Use when the user asks to investigate a bug, trace what caused an incident, walk through unfamiliar code, or build a mental model of a code area before working on it. Accepts a ticket ID, log file path, diagnostic archive, error message, code area name, problem description, or a path to an existing case file.
|
description: Forensic case investigation with evidence-graded findings, calibrated to the input. Use when the user asks
|
||||||
|
to investigate a bug, trace what caused an incident, walk through unfamiliar code, or build a mental model
|
||||||
|
of a code area before working on it.
|
||||||
---
|
---
|
||||||
|
|
||||||
**Language:** Use `{communication_language}` for all output.
|
|
||||||
|
|
||||||
# Investigate
|
# Investigate
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
Reconstruct what's happening, or what an unfamiliar area does, from the available evidence. Produce a structured case
|
Reconstruct what's happening, or what an unfamiliar area does, from the available evidence. Produce a structured case
|
||||||
file another engineer can pick up cold.
|
file another engineer can pick up cold. Calibrate continuously between defect-chasing (symptom-driven) and
|
||||||
|
area-exploration (no symptom); the same discipline applies on both ends.
|
||||||
|
|
||||||
The skill calibrates how much defect-chasing versus how much area-exploration the input demands, on a continuous scale.
|
**Args:** A ticket ID, log file path, diagnostic archive, error message, code area name, problem description, or a path
|
||||||
A vague "how does X work" question leans toward source-reading and mental-model building. A crash log leans toward
|
to an existing case file. The last form resumes a prior investigation; everything else opens a new case.
|
||||||
hypothesis tracking, timeline reconstruction, and a fix direction. Most real cases sit somewhere in between, and the
|
|
||||||
case-file output reflects whatever balance the evidence required.
|
|
||||||
|
|
||||||
The discipline below applies regardless of where on that scale the case lands.
|
**Output:** `{implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}`. Reference inputs
|
||||||
|
are recorded; raw content is not read into the parent context until an outcome calls for it.
|
||||||
|
|
||||||
**Args:** Accepts a ticket ID, log file path, diagnostic archive, error message, code area name, problem description, or
|
`{slug}` is the ticket ID when one is provided, otherwise a short descriptive name agreed with the user, sanitized to
|
||||||
a path to an existing case file.
|
lowercase alphanumeric with hyphens. On collision with an existing case file at the resolved path, ask whether to
|
||||||
|
rename to `slug-YYYY-MM-DD.md` or resume the existing file (resuming routes to Outcome 0).
|
||||||
|
|
||||||
**Your output:** A structured investigation file at `{implementation_artifacts}/investigations/{slug}-investigation.md`.
|
After every outcome, present what was learned and pause for the user before continuing.
|
||||||
Evidence-cited, hypothesis-tracked, hand-off-ready. Sections that don't apply to a given case can stay empty or be
|
|
||||||
omitted; the template covers the union.
|
|
||||||
|
|
||||||
## Principles
|
## Principles
|
||||||
|
|
||||||
- **Evidence grading.** Every finding is one of three things and the grade is explicit in the output:
|
- **Evidence grading.**
|
||||||
- **Confirmed.** Directly observed in logs, code, or dumps. Cited with a specific reference (`path:line`, log
|
- **Confirmed.** Directly observed; cite `path:line`, log timestamp, or commit hash.
|
||||||
timestamp, commit hash).
|
- **Deduced.** Logically follows from Confirmed evidence; show the chain.
|
||||||
- **Deduced.** Logically follows from confirmed evidence. The reasoning chain is shown.
|
- **Hypothesized.** Plausible but unconfirmed; state what would confirm or refute it.
|
||||||
- **Hypothesized.** Plausible but unconfirmed. States what evidence would confirm or refute it.
|
- **Stronghold first.** Anchor in one Confirmed piece of evidence and expand outward. Never start from a theory and
|
||||||
- **Stronghold first.** Anchor in one confirmed piece of evidence and expand outward. Never start from a theory and hunt
|
hunt for support. When evidence is sparse, switch to evidence-light mode (Outcome 1 branch).
|
||||||
for supporting evidence. When evidence is sparse, say so explicitly and switch to hypothesis-driven exploration with a
|
- **Challenge the premise.** The user's description is a hypothesis, not a fact. Verify independently; if evidence
|
||||||
prioritized data-collection list.
|
contradicts, say so.
|
||||||
- **Challenge the premise.** The user's description is a hypothesis, not a fact. Verify technical claims independently.
|
- **Follow the evidence, not the narrative.** When evidence contradicts the working theory, update the theory — never
|
||||||
If evidence contradicts the premise, say so directly.
|
the other way around. Resist confirmation bias even when the user is convinced.
|
||||||
- **Hypotheses are never deleted.** When evidence confirms or refutes a hypothesis, update its **Status** field
|
- **Hypotheses are never deleted.** Update Status (Open / Confirmed / Refuted) and add a Resolution. Wrong turns are
|
||||||
(Open / Confirmed / Refuted) and add a **Resolution**. The full reasoning history, including wrong turns, is part of
|
part of the deliverable.
|
||||||
the deliverable.
|
|
||||||
- **Missing evidence is itself a finding.** Document the gap, what it would resolve, and how to obtain it.
|
- **Missing evidence is itself a finding.** Document the gap, what it would resolve, and how to obtain it.
|
||||||
- **Write it down early and update continuously.** The case file is the persistent state that survives session
|
- **Write it down early.** Initialize the case file as soon as the slug is agreed; it is the persistent state across
|
||||||
interruptions. Initialize it as soon as the case slug is agreed.
|
interruptions.
|
||||||
- **Path:line citations.** Every code reference uses CWD-relative `path:line` format, no leading `/`, so the citation is
|
- **Path:line citations** use CWD-relative format, no leading `/`, so they're clickable in IDE-embedded terminals.
|
||||||
clickable in IDE-embedded terminals (e.g., `src/auth/middleware.ts:42`).
|
- **Delegation discipline.** When a step requires reading 5+ files or any file >10K tokens, delegate to a subagent
|
||||||
|
that returns structured JSON only. Cite `path:line` from the result; don't re-read in the parent.
|
||||||
## Communication Style
|
- **Issue independent operations in parallel** (multi-grep, multi-read, parallel inventories) — one message, multiple
|
||||||
|
tool calls.
|
||||||
- **Clinical precision with detective instinct.** Findings come as a case file: evidence first, deductions second,
|
- **Communication.** Evidence-first language ("the evidence shows", "unconfirmed, requires X to verify"). No hedging,
|
||||||
hypotheses clearly labeled. Never state speculation as fact.
|
no narrative.
|
||||||
- **Evidence-first language.** Speak in "the evidence shows", "this is consistent with", "unconfirmed, requires X to
|
|
||||||
verify". When evidence contradicts a working theory, update the theory and say so.
|
|
||||||
- **No hedging, no narrative.** Prefer "I don't have enough evidence to conclude X" over vague disclaimers. Do not pad
|
|
||||||
findings with story.
|
|
||||||
- **Brief the grading model when presenting the case file.** A first-time reader needs to know what
|
|
||||||
Confirmed / Deduced / Hypothesized mean before they can read the report correctly.
|
|
||||||
|
|
||||||
## On Activation
|
## On Activation
|
||||||
|
|
||||||
1. Load config from `{project-root}/_bmad/bmm/config.yaml`. Resolve `{user_name}`, `{communication_language}`,
|
### Step 1: Resolve the workflow block
|
||||||
`{document_output_language}`, `{implementation_artifacts}`, `{project_knowledge}`. If
|
|
||||||
`{project_knowledge}/project-context.md` exists, read it. Acknowledge the case input briefly without committing to a
|
|
||||||
diagnosis.
|
|
||||||
|
|
||||||
2. Begin the procedure below. Calibrate as the case unfolds.
|
Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
|
||||||
|
|
||||||
|
If the script fails, stop and surface the error.
|
||||||
|
|
||||||
|
### Step 2: Execute prepend steps
|
||||||
|
|
||||||
|
Run each entry in `{workflow.activation_steps_prepend}` in order.
|
||||||
|
|
||||||
|
### Step 3: Load persistent facts
|
||||||
|
|
||||||
|
Treat each entry in `{workflow.persistent_facts}` as foundational context. `file:` prefixes are paths or globs under
|
||||||
|
`{project-root}` (load contents); other entries are facts verbatim.
|
||||||
|
|
||||||
|
### Step 4: Load config
|
||||||
|
|
||||||
|
Load `{project-root}/_bmad/bmm/config.yaml` and resolve `{user_name}`, `{communication_language}`,
|
||||||
|
`{document_output_language}`, `{implementation_artifacts}`, `{project_knowledge}`. If `{implementation_artifacts}` is
|
||||||
|
unresolved, fall back to `./investigations/` and surface the fallback before initializing.
|
||||||
|
|
||||||
|
### Step 5: Greet
|
||||||
|
|
||||||
|
Greet `{user_name}` in `{communication_language}`.
|
||||||
|
|
||||||
|
### Step 6: Execute append steps
|
||||||
|
|
||||||
|
Run each entry in `{workflow.activation_steps_append}` in order.
|
||||||
|
|
||||||
|
### Step 7: Acknowledge and route
|
||||||
|
|
||||||
|
Acknowledge the input as a reference (record paths and IDs; don't read raw content). Path to an existing case file →
|
||||||
|
Outcome 0. Otherwise → Outcome 1.
|
||||||
|
|
||||||
## Procedure
|
## Procedure
|
||||||
|
|
||||||
`{case_file}` resolves to `{implementation_artifacts}/investigations/{slug}-investigation.md`. `{slug}` is the issue
|
### Outcome 0: Existing case is loaded and surfaced
|
||||||
tracker ticket ID when one is provided, otherwise a short descriptive name agreed with the user.
|
|
||||||
|
|
||||||
The procedure is five outcomes that apply with varying weight depending on the input:
|
Read the case file. Surface, in order: open hypotheses (Status = Open) with their confirm/refute criteria; open
|
||||||
|
backlog (Status ≠ Done); missing-evidence rows; last Conclusion with confidence. Ask which thread to pull. New
|
||||||
- A symptom-driven case (bug, incident, error) leans into hypothesis tracking, timeline reconstruction, and a fix
|
evidence opens a new `## Follow-up: {YYYY-MM-DD}` block (append `#2`, `#3` on same-day reentry). Pause for user with the recap above; wait for direction.
|
||||||
direction.
|
|
||||||
- A no-symptom case (understanding an unfamiliar area) leans into I/O mapping, control-flow filtering, and a mental
|
|
||||||
model.
|
|
||||||
- An existing case file is read in full, identified open hypotheses and backlog items are surfaced, and new findings
|
|
||||||
land under a new dated `## Follow-up: {date}` block.
|
|
||||||
|
|
||||||
After every outcome, update the case file, present what was learned, and stop for human input before continuing.
|
|
||||||
|
|
||||||
### Outcome 1: Scope and stronghold are established
|
### Outcome 1: Scope and stronghold are established
|
||||||
|
|
||||||
Establish the case from whatever the user provides. Possible inputs:
|
Acknowledge each input shape — record location, scope, time window only; bulk reads happen in Outcome 2.
|
||||||
|
|
||||||
- **Issue tracker ticket.** Fetch full details via available MCP tools.
|
- **Issue tracker ticket.** Fetch full details via available MCP tools.
|
||||||
- **Diagnostic archive.** Inventory contents.
|
- **Diagnostic archive.** Record path, file count, time window.
|
||||||
- **Log files or stack traces.** Note the time window covered.
|
- **Log file or stack trace.** Record path and time window; only the stack frame already in the user's message is in
|
||||||
- **Free-text description.** Capture verbatim. Treat as hypothesis.
|
scope here.
|
||||||
- **Code area name** (no symptom). Identify the entry point.
|
- **Free-text description.** Capture verbatim; treat as hypothesis.
|
||||||
- **Recent commit area** to scan for likely culprits.
|
- **Code area name** (no symptom). Record entry point.
|
||||||
|
- **Recent commit area.** Record commit range.
|
||||||
|
|
||||||
If the user arrives with a hypothesis, register it as Hypothesis #1 and target evidence collection at confirming or
|
If the user arrived with a hypothesis, register it as Hypothesis #1. Find the stronghold *independently*; the user's
|
||||||
refuting it, while still scanning broadly for the unexpected.
|
hypothesis is one of the things the stronghold validates or refutes.
|
||||||
|
|
||||||
Find a stronghold: a confirmed piece of evidence (an error message, a function name, an HTTP route, a configuration
|
Find a stronghold: a Confirmed piece of evidence (error message, function name, HTTP route, config parameter, test
|
||||||
parameter, a test case). Anchor the case here.
|
case). Anchor here.
|
||||||
|
|
||||||
Initialize `{case_file}` from `case-file-template.md`. Fill in: Case Info, Problem Statement, initial Evidence
|
**Initialize `{case_file}` before branching.** The path is
|
||||||
Inventory.
|
`{implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}` with `{slug}` substituted (slug
|
||||||
|
and collision rules in Overview). Create the file from `{workflow.case_file_template}` and fill Hand-off Brief
|
||||||
|
(rough), Case Info, Problem Statement, initial Evidence Inventory.
|
||||||
|
|
||||||
Present scope, stronghold, file path, proposed approach. Halt.
|
**Evidence-light branch.** When no Confirmed evidence is reachable: mark the case evidence-light in the Hand-off
|
||||||
|
Brief; populate the Investigation Backlog with prioritized data-collection items; record "to make progress, I need one
|
||||||
|
of: …"; pause for the user to provide evidence or authorize Outcome 2 to scan more broadly.
|
||||||
|
|
||||||
|
Otherwise present scope, stronghold, file path, proposed approach. Pause for user with the recap above; wait for direction.
|
||||||
|
|
||||||
### Outcome 2: Evidence perimeter is mapped
|
### Outcome 2: Evidence perimeter is mapped
|
||||||
|
|
||||||
Map all available evidence before analyzing.
|
Survey the scene: inventory available evidence in parallel across these independent categories: diagnostic archives;
|
||||||
|
issue tracker; version control; test results; static analysis; source code. For any category exceeding ~10K tokens,
|
||||||
|
delegate to a subagent that returns a JSON manifest (paths, sizes, time windows, key fragments cited as `path:line`).
|
||||||
|
|
||||||
- **Diagnostic archives.** Log files, crash dumps, configuration snapshots, system info.
|
Classify each Available, Partial, or Missing — Missing is itself a finding. Update Evidence Inventory and Investigation
|
||||||
- **Issue tracker.** Description, comments, linked issues, attachments.
|
Backlog. Pause for user with the recap above; wait for direction.
|
||||||
- **Version control history.** Recent changes in the affected area.
|
|
||||||
- **Test results.** Existing test coverage, recent regressions.
|
|
||||||
- **Static analysis.** Known defects.
|
|
||||||
- **Source code.** The codebase as reference material.
|
|
||||||
|
|
||||||
Classify each as Available, Partial, or Missing. Missing evidence is itself a finding.
|
|
||||||
|
|
||||||
Update Evidence Inventory and Investigation Backlog. Present the inventory and any data gaps. Halt.
|
|
||||||
|
|
||||||
### Outcome 3: Cause is reasoned about with discipline
|
### Outcome 3: Cause is reasoned about with discipline
|
||||||
|
|
||||||
Apply the methodology systematically. Let the evidence guide where to dig.
|
- **Trace causality.** Symptom-driven: trace backward from the symptom to producing conditions and the state that
|
||||||
|
emerged. Exploration: trace backward from outputs (returns, side effects, messages sent) to producing conditions.
|
||||||
- **Establish a beachhead.** Find the first confirmed piece of evidence. Anchor here.
|
Same technique, different anchor.
|
||||||
- **Trace causality.** Symptom-driven: trace backward from the symptom (what produced this error? what condition
|
- **Reconstruct the timeline** by cross-referencing logs, system events, version control, user observations.
|
||||||
triggers this code path? what state would cause that condition? when did that state emerge?). Exploration: trace
|
- **Form and test hypotheses.** State, identify confirming/refuting evidence, search, grade
|
||||||
backward from outputs (return statements, side effects, messages sent) to producing conditions. Same technique,
|
(Confirmed / Refuted / Open). Update Status. Never delete.
|
||||||
different anchor.
|
- **Refutation pass.** Each time a hypothesis transitions toward Confirmed, actively look for refuting evidence first.
|
||||||
- **Reconstruct the timeline.** Cross-reference timestamps across application logs, system events, version control
|
Record the attempt in Resolution.
|
||||||
history, user-reported observations.
|
- **Verify the user's premise.** If evidence contradicts, say so explicitly.
|
||||||
- **Form and test hypotheses.** For each: state it, identify confirming evidence, identify refuting evidence, search,
|
|
||||||
and grade the outcome (Confirmed / Refuted / remains Open). Update Status. Never delete a hypothesis.
|
|
||||||
- **Verify the user's premise.** Verify technical claims independently. If evidence contradicts, say so explicitly.
|
|
||||||
- **Add discovered paths to the backlog.** Stay focused on the current thread.
|
- **Add discovered paths to the backlog.** Stay focused on the current thread.
|
||||||
|
|
||||||
Update Confirmed Findings (with citations), Deduced Conclusions, Hypothesized Paths, Investigation Backlog, Timeline.
|
Update Confirmed Findings, Deduced Conclusions, Hypothesized Paths, Backlog, Timeline. Highlight contradictions to the
|
||||||
|
original premise. Pause for user with the recap above; wait for direction.
|
||||||
Present key findings, active hypotheses, updated backlog. Highlight anything that contradicts the original premise.
|
|
||||||
Recommend the next action with rationale. Halt.
|
|
||||||
|
|
||||||
### Outcome 4: Source has been traced where it matters
|
### Outcome 4: Source has been traced where it matters
|
||||||
|
|
||||||
Once the procedure points at specific behaviors or an area, trace into the source.
|
Issue these first-pass scans as parallel tool calls in one message: grep for exact error strings; glob the affected
|
||||||
|
directory for parallel implementations; `git log` for recent changes.
|
||||||
|
|
||||||
- Grep for exact error strings to find the originating function.
|
Then sequentially: read the surrounding code; follow the caller chain; watch for language and process boundary
|
||||||
- Read the surrounding code to understand the triggering condition.
|
crossings (compiled→scripts, IPC, host→device, configuration flow).
|
||||||
- Check for parallel implementations in different directories.
|
|
||||||
- Follow the caller chain to understand the execution context.
|
|
||||||
- Check version control history for recent changes.
|
|
||||||
- Watch for language and process boundary crossings (compiled code calling scripts, IPC, host-to-device, configuration
|
|
||||||
flow). Boundaries hide bugs because each side assumes the other behaved as documented.
|
|
||||||
|
|
||||||
For exploration cases, lean heavier into:
|
Lean by case type:
|
||||||
|
|
||||||
- **I/O mapping.** Triggers, outputs, external dependencies of the area.
|
- **Exploration:** I/O mapping (triggers, outputs, dependencies); frequent-terms scan; control-flow filtering
|
||||||
- **Frequent-terms scan.** Recurring objects, variables, identifiers.
|
(branches, loops, error handling, state-machine transitions).
|
||||||
- **Control-flow filtering.** Skeleton: branching, loops, error handling, state-machine transitions. Bugs hide in the
|
- **Symptom-driven:** depth assessment — is the root cause reachable from local context, or is a broader area model
|
||||||
structure, not the syntax.
|
required? Surface escalations; never silently expand scope. Trivial-fix assessment — off-by-one, missing null check,
|
||||||
|
swapped argument → one-line code suggestion or draft diff in the report; non-trivial → stop at the root cause area.
|
||||||
|
|
||||||
For symptom-driven cases, lean heavier into:
|
Investigation stops at the diagnosis; implementation is out of scope. Update Source Code Trace (Error origin, Trigger,
|
||||||
|
Condition, Related files; area model when broader). Pause for user with the recap above; wait for direction.
|
||||||
- **Depth assessment.** After the narrow trace, decide whether the root cause is reachable from local context or
|
|
||||||
whether a broader area model is required. Surface the decision when escalating. Never silently expand scope.
|
|
||||||
- **Trivial-fix assessment.** If the fix is obviously trivial (off-by-one, missing null check, swapped argument), note
|
|
||||||
the direction in the report. For anything non-trivial, stop at identifying the root cause area. Investigation stops
|
|
||||||
at the diagnosis; implementation is a separate concern handled outside this skill.
|
|
||||||
|
|
||||||
Update Source Code Trace section (Error origin, Trigger, Condition, Related files; plus area model when broader
|
|
||||||
exploration was applied).
|
|
||||||
|
|
||||||
Present the trace findings. Recommend the next step. Halt.
|
|
||||||
|
|
||||||
### Outcome 5: Report is finalized and the hand-off is clean
|
### Outcome 5: Report is finalized and the hand-off is clean
|
||||||
|
|
||||||
Update `{case_file}` with:
|
Update `{case_file}`:
|
||||||
|
|
||||||
- Final Conclusion with confidence level (High / Medium / Low).
|
- **Hand-off Brief** rewritten to final form (3 sentences, 15-second read).
|
||||||
- Fix direction (when applicable; categorize by mechanism when multiple issues combine).
|
- **Final Conclusion** with confidence: **High** (Confirmed root cause, deterministic repro), **Medium** (Deduced;
|
||||||
- Diagnostic steps to confirm the root cause if any uncertainty remains.
|
minor uncertainty), **Low** (Hypothesized; clear data gap).
|
||||||
- Reproduction Plan (when applicable; setup, trigger, expected results) or a verification plan for exploration cases
|
- **Fix direction** when applicable (categorize by mechanism if multiple combine).
|
||||||
(small set of operations or tests that would confirm the mental model).
|
- **Diagnostic steps** if uncertainty remains.
|
||||||
- Status: Active, Concluded, or Blocked on evidence.
|
- **Reproduction Plan** when applicable, or a verification plan for exploration cases.
|
||||||
|
- **Status:** Active / Concluded / Blocked on evidence.
|
||||||
|
|
||||||
Present the conclusion summary. Recommend the highest-value next action with specifics. Halt.
|
Present the conclusion, then a concrete next-steps menu: trivial fix → `bmad-quick-dev`; scope/plan adjustment →
|
||||||
|
`bmad-correct-course`; tracked story → `bmad-create-story`; fresh review → `bmad-code-review`. Recommend the
|
||||||
|
highest-value action. Mitigations and workarounds are generated only on explicit request — investigation stops at the
|
||||||
|
diagnosis. Execute `{workflow.on_complete}` if non-empty. Pause for user with the recap above; wait for direction.
|
||||||
|
|
||||||
## Follow-up Iterations
|
## Follow-up Iterations
|
||||||
|
|
||||||
When the user chooses to continue, execute the requested action and update `{case_file}` with new findings. When
|
Continue work by appending to `{case_file}` under a new `## Follow-up: {YYYY-MM-DD}` block (`#2`, `#3` on same-day
|
||||||
extending an existing case across sessions, append findings under a new or current `## Follow-up: {date}` block to
|
reentry). The investigation is complete when:
|
||||||
preserve the original reasoning.
|
|
||||||
|
|
||||||
The investigation is complete when:
|
- Root cause is Confirmed.
|
||||||
|
- Root cause is Hypothesized with a clear data gap.
|
||||||
- A root cause is Confirmed with evidence.
|
|
||||||
- The most likely root cause is Hypothesized with a clear data gap.
|
|
||||||
- The mental model is sufficient for the user's stated goal (exploration cases).
|
- The mental model is sufficient for the user's stated goal (exploration cases).
|
||||||
- The backlog contains only items requiring evidence not currently available.
|
- The backlog contains only items requiring unavailable evidence.
|
||||||
- The user explicitly concludes.
|
- The user explicitly concludes.
|
||||||
|
|
||||||
## Case File Structure
|
|
||||||
|
|
||||||
The output file uses the structure defined in `case-file-template.md`. Initialize it once at the start of the case from
|
|
||||||
that template, then update sections as evidence accumulates.
|
|
||||||
|
|
|
||||||
|
|
@ -1,158 +0,0 @@
|
||||||
<!-- Case file template. Copy this structure into a new case file at the start of an investigation.
|
|
||||||
Update sections as evidence accumulates. Never delete a hypothesis: update its Status and add a Resolution.
|
|
||||||
Append follow-up sessions under dated `## Follow-up: {date}` blocks instead of overwriting earlier reasoning. -->
|
|
||||||
|
|
||||||
# Investigation: {title}
|
|
||||||
|
|
||||||
## Case Info
|
|
||||||
|
|
||||||
| Field | Value |
|
|
||||||
| ---------------- | -------------------------------------------------------------------------------------- |
|
|
||||||
| Ticket | {ticket-id or "N/A"} |
|
|
||||||
| Date opened | {date} |
|
|
||||||
| Status | Active |
|
|
||||||
| System | {system description, OS, version, relevant environment details} |
|
|
||||||
| Evidence sources | {diagnostic archive, logs, crash dump, code, version control history, etc.} |
|
|
||||||
|
|
||||||
## Problem Statement
|
|
||||||
|
|
||||||
{User-reported problem description. This is the initial claim. It may be refined or contradicted by evidence during the
|
|
||||||
investigation.}
|
|
||||||
|
|
||||||
## Evidence Grading Legend
|
|
||||||
|
|
||||||
- **Confirmed.** Directly observed in logs, code, or dumps. Cited with specific evidence.
|
|
||||||
- **Deduced.** Logically follows from confirmed evidence. Reasoning chain shown.
|
|
||||||
- **Hypothesized.** Plausible but unconfirmed. States what evidence would confirm or refute.
|
|
||||||
|
|
||||||
## Evidence Inventory
|
|
||||||
|
|
||||||
| Source | Status | Notes |
|
|
||||||
| -------- | ------------------------------- | --------- |
|
|
||||||
| {source} | {Available / Partial / Missing} | {details} |
|
|
||||||
|
|
||||||
## Investigation Backlog
|
|
||||||
|
|
||||||
Paths to explore, ordered by priority. Updated throughout the investigation.
|
|
||||||
|
|
||||||
| # | Path to Explore | Priority | Status | Notes |
|
|
||||||
| - | --------------- | --------------------- | ------------------------------------------ | --------- |
|
|
||||||
| 1 | {description} | {High / Medium / Low} | {Open / In Progress / Done / Blocked} | {context} |
|
|
||||||
|
|
||||||
## Timeline of Events
|
|
||||||
|
|
||||||
Chronological reconstruction from multiple evidence sources. Each entry cites its source.
|
|
||||||
|
|
||||||
| Time | Event | Source | Confidence |
|
|
||||||
| ----------- | ------------------- | ---------------------- | ----------------------- |
|
|
||||||
| {timestamp} | {event description} | {log file, commit, …} | {Confirmed / Deduced} |
|
|
||||||
|
|
||||||
## Confirmed Findings
|
|
||||||
|
|
||||||
Directly observed in logs, code, or dumps. Each finding includes a citation: `path:line`, log timestamp, commit hash.
|
|
||||||
|
|
||||||
### Finding 1: {title}
|
|
||||||
|
|
||||||
**Evidence:** {citation}
|
|
||||||
|
|
||||||
**Detail:** {description}
|
|
||||||
|
|
||||||
## Deduced Conclusions
|
|
||||||
|
|
||||||
Logically follows from confirmed findings. Each deduction shows the reasoning chain from confirmed evidence to
|
|
||||||
conclusion.
|
|
||||||
|
|
||||||
### Deduction 1: {title}
|
|
||||||
|
|
||||||
**Based on:** {which confirmed findings}
|
|
||||||
|
|
||||||
**Reasoning:** {logical chain}
|
|
||||||
|
|
||||||
**Conclusion:** {what follows}
|
|
||||||
|
|
||||||
## Hypothesized Paths
|
|
||||||
|
|
||||||
All hypotheses ever formed during the investigation. Hypotheses are NEVER removed. Only their Status is updated. This
|
|
||||||
preserves the full reasoning history.
|
|
||||||
|
|
||||||
### Hypothesis 1: {title}
|
|
||||||
|
|
||||||
**Status:** {Open / Confirmed / Refuted}
|
|
||||||
|
|
||||||
**Theory:** {description}
|
|
||||||
|
|
||||||
**Supporting indicators:** {what makes this plausible}
|
|
||||||
|
|
||||||
**Would confirm:** {specific evidence that would prove this}
|
|
||||||
|
|
||||||
**Would refute:** {specific evidence that would disprove this}
|
|
||||||
|
|
||||||
**Resolution:** {when status changes from Open, explain what evidence settled it}
|
|
||||||
|
|
||||||
## Missing Evidence
|
|
||||||
|
|
||||||
Data gaps identified during investigation. Each gap describes what is missing and what it would resolve if available.
|
|
||||||
|
|
||||||
| Gap | Impact | How to Obtain |
|
|
||||||
| -------------- | ------------------------------------- | -------------- |
|
|
||||||
| {what's missing} | {what it would confirm or eliminate} | {how to get it} |
|
|
||||||
|
|
||||||
## Source Code Trace
|
|
||||||
|
|
||||||
If source code was traced during the investigation.
|
|
||||||
|
|
||||||
| Element | Detail |
|
|
||||||
| ------------- | -------------------------------------------- |
|
|
||||||
| Error origin | {file:line, function name} |
|
|
||||||
| Trigger | {what causes this code to execute} |
|
|
||||||
| Condition | {what state produces the observed behavior} |
|
|
||||||
| Related files | {other files in the same code path} |
|
|
||||||
|
|
||||||
## Conclusion
|
|
||||||
|
|
||||||
**Confidence:** {High / Medium / Low}
|
|
||||||
|
|
||||||
{Summary of what happened based on the evidence. Clearly states what is Confirmed versus what remains Hypothesized. If
|
|
||||||
the root cause is identified, states it. If not, states the most promising hypothesized paths and what would resolve the
|
|
||||||
remaining uncertainty.}
|
|
||||||
|
|
||||||
## Recommended Next Steps
|
|
||||||
|
|
||||||
### Fix direction
|
|
||||||
|
|
||||||
{High-level description of what needs to change and why. Categorize by mechanism when multiple issues combine to produce
|
|
||||||
the bug.}
|
|
||||||
|
|
||||||
### Diagnostic
|
|
||||||
|
|
||||||
{Steps to confirm the root cause. Additional logging, targeted tests, data to collect.}
|
|
||||||
|
|
||||||
## Reproduction Plan
|
|
||||||
|
|
||||||
{How to reproduce the issue in a controlled environment. Include setup, trigger, and expected results. Scale from
|
|
||||||
isolated proof to full system reproduction when applicable.}
|
|
||||||
|
|
||||||
## Follow-up: {date}
|
|
||||||
|
|
||||||
Append a new dated block when new findings extend an existing case across sessions. One block per session. Never
|
|
||||||
overwrite earlier blocks.
|
|
||||||
|
|
||||||
### New Evidence
|
|
||||||
|
|
||||||
{What new data was provided or discovered.}
|
|
||||||
|
|
||||||
### Additional Findings
|
|
||||||
|
|
||||||
{New Confirmed findings, Deductions, or Hypotheses, with grading.}
|
|
||||||
|
|
||||||
### Updated Hypotheses
|
|
||||||
|
|
||||||
{Which hypotheses were Confirmed, Refuted, or refined.}
|
|
||||||
|
|
||||||
### Backlog Changes
|
|
||||||
|
|
||||||
{Items completed, items added, reprioritization.}
|
|
||||||
|
|
||||||
### Updated Conclusion
|
|
||||||
|
|
||||||
{Revised assessment incorporating new evidence.}
|
|
||||||
|
|
@ -0,0 +1,62 @@
|
||||||
|
# DO NOT EDIT -- overwritten on every update.
|
||||||
|
#
|
||||||
|
# Workflow customization surface for bmad-investigate. Mirrors the
|
||||||
|
# agent customization shape under the [workflow] namespace.
|
||||||
|
|
||||||
|
[workflow]
|
||||||
|
|
||||||
|
# --- Configurable below. Overrides merge per BMad structural rules: ---
|
||||||
|
# scalars: override wins • arrays (persistent_facts, activation_steps_*): append
|
||||||
|
# arrays-of-tables with `code`/`id`: replace matching items, append new ones.
|
||||||
|
|
||||||
|
# Steps to run before the standard activation (config load, greet).
|
||||||
|
# Overrides append. Use for pre-flight loads, compliance checks, etc.
|
||||||
|
|
||||||
|
activation_steps_prepend = []
|
||||||
|
|
||||||
|
# Steps to run after greet but before the workflow begins.
|
||||||
|
# Overrides append. Use for context-heavy setup that should happen
|
||||||
|
# once the user has been acknowledged.
|
||||||
|
|
||||||
|
activation_steps_append = []
|
||||||
|
|
||||||
|
# Persistent facts the workflow keeps in mind for the whole run.
|
||||||
|
# Use for citation conventions (path:line vs path#L42), grading-scale
|
||||||
|
# overrides (ITIL severity 1-5 instead of High/Medium/Low), tone
|
||||||
|
# directives (engineering vs exec-facing), or compliance constraints
|
||||||
|
# the case file must respect.
|
||||||
|
# Distinct from the runtime memory sidecar — these are static context
|
||||||
|
# loaded on activation. Overrides append.
|
||||||
|
#
|
||||||
|
# Each entry is either:
|
||||||
|
# - a literal sentence, e.g. "Use ITIL severity 1-5 instead of High/Medium/Low for confidence."
|
||||||
|
# - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
|
||||||
|
# (glob patterns are supported; the file's contents are loaded and treated as facts).
|
||||||
|
|
||||||
|
persistent_facts = [
|
||||||
|
"file:{project-root}/**/project-context.md",
|
||||||
|
]
|
||||||
|
|
||||||
|
# Scalar: path to the case-file template, resolved from the skill root.
|
||||||
|
# Override to point at an org-shaped template (compliance sections,
|
||||||
|
# SLA fields, post-mortem hooks, ITIL fields).
|
||||||
|
|
||||||
|
case_file_template = "references/case-file-template.md"
|
||||||
|
|
||||||
|
# Scalar: subdirectory under {implementation_artifacts} where case files land.
|
||||||
|
# Override for org taxonomies (forensics/, cases/, incidents/, bug-bash/).
|
||||||
|
|
||||||
|
case_file_subdir = "investigations"
|
||||||
|
|
||||||
|
# Scalar: filename pattern for new case files. {slug} expands to the
|
||||||
|
# ticket ID or a short user-agreed name.
|
||||||
|
|
||||||
|
case_file_filename = "{slug}-investigation.md"
|
||||||
|
|
||||||
|
# Scalar: executed when the workflow finalizes the case file at Outcome 5,
|
||||||
|
# after the conclusion is presented. Override wins. Use for post-case
|
||||||
|
# automation: post the case to Slack/Teams, push fields back to ticketing,
|
||||||
|
# link the case to a sprint, trigger a follow-up retro.
|
||||||
|
# Leave empty for no custom post-completion behavior.
|
||||||
|
|
||||||
|
on_complete = ""
|
||||||
|
|
@ -0,0 +1,127 @@
|
||||||
|
# Investigation: {title}
|
||||||
|
|
||||||
|
## Hand-off Brief
|
||||||
|
|
||||||
|
1. **What happened.** {one-sentence problem statement, evidence-graded}
|
||||||
|
2. **Where the case stands.** {status, last finding, what would unblock progress}
|
||||||
|
3. **What's needed next.** {single recommended action with rationale}
|
||||||
|
|
||||||
|
## Case Info
|
||||||
|
|
||||||
|
| Field | Value |
|
||||||
|
| ---------------- | -------------------------------------------------------------------------- |
|
||||||
|
| Ticket | {ticket-id or "N/A"} |
|
||||||
|
| Date opened | {date} |
|
||||||
|
| Status | Active |
|
||||||
|
| System | {OS, version, relevant environment details} |
|
||||||
|
| Evidence sources | {diagnostic archive, logs, crash dump, code, version control, etc.} |
|
||||||
|
|
||||||
|
## Problem Statement
|
||||||
|
|
||||||
|
{User-reported description; the initial claim. May be refined or contradicted by evidence.}
|
||||||
|
|
||||||
|
## Evidence Inventory
|
||||||
|
|
||||||
|
| Source | Status | Notes |
|
||||||
|
| -------- | ------------------------------- | --------- |
|
||||||
|
| {source} | {Available / Partial / Missing} | {details} |
|
||||||
|
|
||||||
|
## Investigation Backlog
|
||||||
|
|
||||||
|
| # | Path to Explore | Priority | Status | Notes |
|
||||||
|
| - | --------------- | --------------------- | ------------------------------------- | --------- |
|
||||||
|
| 1 | {description} | {High / Medium / Low} | {Open / In Progress / Done / Blocked} | {context} |
|
||||||
|
|
||||||
|
## Timeline of Events
|
||||||
|
|
||||||
|
| Time | Event | Source | Confidence |
|
||||||
|
| ----------- | ------------------- | --------------------- | --------------------- |
|
||||||
|
| {timestamp} | {event description} | {log file, commit, …} | {Confirmed / Deduced} |
|
||||||
|
|
||||||
|
## Confirmed Findings
|
||||||
|
|
||||||
|
### Finding 1: {title}
|
||||||
|
|
||||||
|
**Evidence:** {citation — `path:line`, log timestamp, or commit hash}
|
||||||
|
|
||||||
|
**Detail:** {description}
|
||||||
|
|
||||||
|
## Deduced Conclusions
|
||||||
|
|
||||||
|
### Deduction 1: {title}
|
||||||
|
|
||||||
|
**Based on:** {which Confirmed Findings}
|
||||||
|
|
||||||
|
**Reasoning:** {logical chain}
|
||||||
|
|
||||||
|
**Conclusion:** {what follows}
|
||||||
|
|
||||||
|
## Hypothesized Paths
|
||||||
|
|
||||||
|
### Hypothesis 1: {title}
|
||||||
|
|
||||||
|
**Status:** {Open / Confirmed / Refuted}
|
||||||
|
|
||||||
|
**Theory:** {description}
|
||||||
|
|
||||||
|
**Supporting indicators:** {what makes this plausible}
|
||||||
|
|
||||||
|
**Would confirm:** {specific evidence that would prove this}
|
||||||
|
|
||||||
|
**Would refute:** {specific evidence that would disprove this}
|
||||||
|
|
||||||
|
**Resolution:** {when Status changes from Open, what evidence settled it}
|
||||||
|
|
||||||
|
## Missing Evidence
|
||||||
|
|
||||||
|
| Gap | Impact | How to Obtain |
|
||||||
|
| ---------------- | ------------------------------------ | --------------- |
|
||||||
|
| {what's missing} | {what it would confirm or eliminate} | {how to get it} |
|
||||||
|
|
||||||
|
## Source Code Trace
|
||||||
|
|
||||||
|
| Element | Detail |
|
||||||
|
| ------------- | ------------------------------------------- |
|
||||||
|
| Error origin | {file:line, function name} |
|
||||||
|
| Trigger | {what causes this code to execute} |
|
||||||
|
| Condition | {what state produces the observed behavior} |
|
||||||
|
| Related files | {other files in the same code path} |
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
**Confidence:** {High / Medium / Low}
|
||||||
|
|
||||||
|
{Summary stating what is Confirmed vs. what remains Hypothesized. If a root cause is identified, state it; otherwise
|
||||||
|
name the most promising hypothesized paths and what would resolve the remaining uncertainty.}
|
||||||
|
|
||||||
|
## Recommended Next Steps
|
||||||
|
|
||||||
|
### Fix direction
|
||||||
|
|
||||||
|
{What needs to change and why. Categorize by mechanism when multiple issues combine.}
|
||||||
|
|
||||||
|
### Diagnostic
|
||||||
|
|
||||||
|
{Steps to confirm the root cause: additional logging, targeted tests, data to collect.}
|
||||||
|
|
||||||
|
## Reproduction Plan
|
||||||
|
|
||||||
|
{Setup, trigger, expected results. Scale from isolated proof to full system reproduction.}
|
||||||
|
|
||||||
|
## Side Findings
|
||||||
|
|
||||||
|
Tangential observations surfaced during the investigation, evidence-graded, with citation when applicable.
|
||||||
|
|
||||||
|
- {observation}
|
||||||
|
|
||||||
|
## Follow-up: {date}
|
||||||
|
|
||||||
|
### New Evidence
|
||||||
|
|
||||||
|
### Additional Findings
|
||||||
|
|
||||||
|
### Updated Hypotheses
|
||||||
|
|
||||||
|
### Backlog Changes
|
||||||
|
|
||||||
|
### Updated Conclusion
|
||||||
Loading…
Reference in New Issue