bmad-method 6.6.1-next.3 → 6.6.1-next.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.6.1-next.3",
+  "version": "6.6.1-next.4",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

package/src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-01-init.md

@@ -77,6 +77,7 @@ Discover and load context documents using smart discovery. Documents can be in t
 - {planning_artifacts}/**
 - {output_folder}/**
 - {project_knowledge}/**
+- {implementation_artifacts}/investigations/**
 - docs/**
 
 Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content)
@@ -86,6 +87,8 @@ Try to discover the following:
 - Research Documents (`/*research*.md`)
 - Project Documentation (generally multiple documents might be found for this in the `{project_knowledge}` or `docs` folder.)
 - 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.
 
 <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>
 
@@ -120,6 +123,7 @@ Try to discover the following:
 - Product briefs: {{briefCount}} files {if briefCount > 0}✓ loaded{else}(none found){/if}
 - Research: {{researchCount}} files {if researchCount > 0}✓ loaded{else}(none found){/if}
 - Brainstorming: {{brainstormingCount}} files {if brainstormingCount > 0}✓ loaded{else}(none found){/if}
+- Investigations: {{investigationCount}} files {if investigationCount > 0}✓ loaded{else}(none found){/if}
 - Project docs: {{projectDocsCount}} files {if projectDocsCount > 0}✓ loaded (brownfield project){else}(none found - greenfield project){/if}
 
 **Files loaded:** {list of specific file names or "No additional documents found"}
@@ -128,6 +132,10 @@ Try to discover the following:
 📋 **Note:** This is a **brownfield project**. Your existing project documentation has been loaded. In the next step, I'll ask specifically about what new features or changes you want to add to your existing system.
 {/if}
 
+{if investigationCount > 0}
+🔎 **Note:** Investigation files have been loaded. The evidence-graded findings (Confirmed / Deduced / Hypothesized), timeline, and fix direction are available as context while we scope requirements.
+{/if}
+
 Do you have any other documents you'd like me to include, or shall we continue to the next step?"
 
 ### 4. Present MENU OPTIONS

package/src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-02-discovery.md

@@ -63,6 +63,7 @@ Read the frontmatter from `{outputFile}` to get document counts:
 - `briefCount` - Product briefs available
 - `researchCount` - Research documents available
 - `brainstormingCount` - Brainstorming docs available
+- `investigationCount` - bmad-investigate case files available
 - `projectDocsCount` - Existing project documentation
 
 **Announce your understanding:**
@@ -71,6 +72,7 @@ Read the frontmatter from `{outputFile}` to get document counts:
 - Product briefs: {{briefCount}}
 - Research: {{researchCount}}
 - Brainstorming: {{brainstormingCount}}
+- Investigations: {{investigationCount}}
 - Project docs: {{projectDocsCount}}
 
 {{if projectDocsCount > 0}}This is a brownfield project - I'll focus on understanding what you want to add or change.{{else}}This is a greenfield project - I'll help you define the full product vision.{{/if}}"

package/src/bmm-skills/4-implementation/bmad-agent-dev/customize.toml

@@ -88,3 +88,8 @@ skill = "bmad-create-story"
 code = "ER"
 description = "Party mode review of all work completed across an epic"
 skill = "bmad-retrospective"
+
+[[agent.menu]]
+code = "IN"
+description = "Forensic case investigation with evidence-graded findings, calibrated to the input"
+skill = "bmad-investigate"

package/src/bmm-skills/4-implementation/bmad-investigate/SKILL.md

@@ -0,0 +1,194 @@
+---
+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.
+---
+
+# 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.
+
+## On Activation
+
+### Step 1: Resolve the workflow block
+
+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
+
+### Outcome 0: Existing case is loaded and surfaced
+
+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
+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.
+
+### Outcome 1: Scope and stronghold are established
+
+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.
+- **Diagnostic archive.** Record path, file count, time window.
+- **Log file or stack trace.** Record path and time window; only the stack frame already in the user's message is in
+  scope here.
+- **Free-text description.** Capture verbatim; treat as hypothesis.
+- **Code area name** (no symptom). Record entry point.
+- **Recent commit area.** Record commit range.
+
+If the user arrived with a hypothesis, register it as Hypothesis #1. Find the stronghold *independently*; the user's
+hypothesis is one of the things the stronghold validates or refutes.
+
+Find a stronghold: a Confirmed piece of evidence (error message, function name, HTTP route, config parameter, test
+case). Anchor here.
+
+**Initialize `{case_file}` before branching.** The path is
+`{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.
+
+**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
+
+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`).
+
+Classify each Available, Partial, or Missing — Missing is itself a finding. Update Evidence Inventory and Investigation
+Backlog. Pause for user with the recap above; wait for direction.
+
+### Outcome 3: Cause is reasoned about with discipline
+
+- **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.
+  Same technique, different anchor.
+- **Reconstruct the timeline** by cross-referencing logs, system events, version control, user observations.
+- **Form and test hypotheses.** State, identify confirming/refuting evidence, search, grade
+  (Confirmed / Refuted / Open). Update Status. Never delete.
+- **Refutation pass.** Each time a hypothesis transitions toward Confirmed, actively look for refuting evidence first.
+  Record the attempt in Resolution.
+- **Verify the user's premise.** If evidence contradicts, say so explicitly.
+- **Add discovered paths to the backlog.** Stay focused on the current thread.
+
+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.
+
+### Outcome 4: Source has been traced where it matters
+
+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.
+
+Then sequentially: read the surrounding code; follow the caller chain; watch for language and process boundary
+crossings (compiled→scripts, IPC, host→device, configuration flow).
+
+Lean by case type:
+
+- **Exploration:** I/O mapping (triggers, outputs, dependencies); frequent-terms scan; control-flow filtering
+  (branches, loops, error handling, state-machine transitions).
+- **Symptom-driven:** depth assessment — is the root cause reachable from local context, or is a broader area model
+  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.
+
+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.
+
+### Outcome 5: Report is finalized and the hand-off is clean
+
+Update `{case_file}`:
+
+- **Hand-off Brief** rewritten to final form (3 sentences, 15-second read).
+- **Final Conclusion** with confidence: **High** (Confirmed root cause, deterministic repro), **Medium** (Deduced;
+  minor uncertainty), **Low** (Hypothesized; clear data gap).
+- **Fix direction** when applicable (categorize by mechanism if multiple combine).
+- **Diagnostic steps** if uncertainty remains.
+- **Reproduction Plan** when applicable, or a verification plan for exploration cases.
+- **Status:** Active / Concluded / Blocked on evidence.
+
+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
+
+Continue work by appending to `{case_file}` under a new `## Follow-up: {YYYY-MM-DD}` block (`#2`, `#3` on same-day
+reentry). The investigation is complete when:
+
+- Root cause is Confirmed.
+- Root cause is Hypothesized with a clear data gap.
+- The mental model is sufficient for the user's stated goal (exploration cases).
+- The backlog contains only items requiring unavailable evidence.
+- The user explicitly concludes.

package/src/bmm-skills/4-implementation/bmad-investigate/customize.toml

@@ -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 = ""

package/src/bmm-skills/4-implementation/bmad-investigate/references/case-file-template.md

@@ -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

package/src/bmm-skills/module-help.csv

@@ -31,3 +31,4 @@ BMad Method,bmad-code-review,Code Review,CR,Story cycle: If issues back to DS if
 BMad Method,bmad-checkpoint-preview,Checkpoint,CK,Guided walkthrough of a change from purpose and context into details. Use for human review of commits branches or PRs.,,,4-implementation,,,false,,
 BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,,4-implementation,bmad-dev-story,,false,implementation_artifacts,test suite
 BMad Method,bmad-retrospective,Retrospective,ER,Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC.,,,4-implementation,bmad-code-review,,false,implementation_artifacts,retrospective
+BMad Method,bmad-investigate,Investigate,IN,Forensic case investigation calibrated to the input. Evidence-graded analysis with hypothesis tracking. Produces a structured case file.,,4-implementation,,,false,implementation_artifacts,investigation report