bmad-investigate

Investigate

Overview

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. Calibrate continuously between defect-chasing (symptom-driven) and area-exploration (no symptom); the same discipline applies on both ends.

Args: A ticket ID, log file path, diagnostic archive, error message, code area name, problem description, or a path to an existing case file. The last form resumes a prior investigation; everything else opens a new case.

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.

{slug} is the ticket ID when one is provided, otherwise a short descriptive name agreed with the user, sanitized to 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).

After every outcome, present what was learned and pause for the user before continuing.

Principles

• Evidence grading.
  • Confirmed. Directly observed; cite path:line, log timestamp, or commit hash.
  • Deduced. Logically follows from Confirmed evidence; show the chain.
  • Hypothesized. Plausible but unconfirmed; state what would confirm or refute it.
• Stronghold first. Anchor in one Confirmed piece of evidence and expand outward. Never start from a theory and hunt for support. When evidence is sparse, switch to evidence-light mode (Outcome 1 branch).
• Challenge the premise. The user's description is a hypothesis, not a fact. Verify independently; if evidence contradicts, say so.
• Follow the evidence, not the narrative. When evidence contradicts the working theory, update the theory — never the other way around. Resist confirmation bias even when the user is convinced.
• Hypotheses are never deleted. Update Status (Open / Confirmed / Refuted) and add a Resolution. Wrong turns are part of the deliverable.
• Missing evidence is itself a finding. Document the gap, what it would resolve, and how to obtain it.
• Write it down early. Initialize the case file as soon as the slug is agreed; it is the persistent state across interruptions.
• Path:line citations use CWD-relative format, no leading /, so they're clickable in IDE-embedded terminals.
• 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.
• Issue independent operations in parallel (multi-grep, multi-read, parallel inventories) — one message, multiple tool calls.
• Communication. Evidence-first language ("the evidence shows", "unconfirmed, requires X to verify"). No hedging, no narrative.