feat(bmm): add Tracy, a forensic code investigator agent#2340
Open
anderewrey wants to merge 1 commit intobmad-code-org:mainfrom
Open
feat(bmm): add Tracy, a forensic code investigator agent#2340anderewrey wants to merge 1 commit intobmad-code-org:mainfrom
anderewrey wants to merge 1 commit intobmad-code-org:mainfrom
Conversation
Introduce Tracy (🔎), a forensic code investigator who treats every
issue like a crime scene. Findings are graded as Confirmed, Deduced,
or Hypothesized, hypotheses are never deleted (only updated), and the
deliverable is a structured investigation file another engineer can
pick up cold.
Skills under src/bmm-skills/4-implementation/:
- bmad-agent-investigator: Tracy persona, registered in the module.yaml
agent roster (which surfaces her in Party Mode automatically) and in
module-help.csv. Menu codes IN (investigate) and CX (code archaeology).
- bmad-investigate: full case workflow with intake, scene survey,
evidence analysis, source-code trace, and finalization phases. Phase 4
folds archaeology techniques inline when a bug requires broader area
understanding. Resume mode is intrinsic auto-detection.
- bmad-code-archaeology: standalone code-area exploration when there is
no bug to chase.
Workflow integration:
- bmad-create-prd step-01-init now scans
{implementation_artifacts}/investigations/*.md and reports
investigationCount alongside briefs, research, brainstorming, and
project docs. The PM agent treats the case file as input context.
Greenfield/brownfield branching, the PRD template, and downstream
Phase 3/4 skills stay untouched. Restructuring step-02+ for fix-driven
mode is left for a maintainer-aligned PR.
- bmad-create-prd step-02-discovery echoes the new count.
Public docs:
- New explainer at docs/explanation/forensic-investigation.md covering
evidence grading, hypothesis discipline, the two downstream paths, and
the Tracy/Amelia separation.
- docs/explanation/named-agents.md adds Tracy and drops the hardcoded
count so the table is self-counting.
- docs/reference/agents.md adds Tracy with IN/CX triggers.
- docs/reference/workflow-map.md gains an Entry Points section
(greenfield vs working-backwards) and places bmad-investigate on the
Quick Flow track feeding bmad-quick-dev.
- The Quick Flow box in workflow-map-diagram.html now shows Tracy and
Amelia in series with an arrow between them.
🤖 Augment PR SummarySummary: This PR introduces Tracy, a forensic code investigator agent, and adds two investigation-oriented implementation workflows. Changes:
Technical Notes: The new workflows standardize deliverables as structured Markdown case files using a shared investigation template and explicit Confirmed/Deduced/Hypothesized evidence grading. 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| </div> | ||
| <div class="workflow-meta"> | ||
| <div class="agent"><div class="agent-icon tracy">T</div><span class="agent-name">Tracy</span></div> | ||
| <span class="output">investigation.md</span> |
There was a problem hiding this comment.
website/public/workflow-map-diagram.html:333: The diagram output label investigation.md (and archaeology.md) looks like a fixed filename, but the new workflows/docs describe output as {slug}-investigation.md / {slug}-archaeology.md; could be worth double-checking this doesn’t mislead users about where to find the generated file.
Severity: low
Other Locations
website/public/workflow-map-diagram-fr.html:322
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
Contributor
Author
There was a problem hiding this comment.
the whole workflow-map should be fully reviewed and deciding of a proper guideline how referring to the output files (in a generic way).
📝 WalkthroughWalkthroughThis PR introduces Tracy, a new forensic code investigator agent alongside two investigation workflows ( Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Tracy as Tracy Agent
participant Investigation as Investigation File
participant QuickDev as bmad-quick-dev
participant PRD as bmad-create-prd
User->>Tracy: Initiate investigation (symptom-driven or code archaeology)
activate Tracy
Tracy->>Tracy: Load persistent facts & project config
Tracy->>Tracy: Conduct case intake & evidence collection
Tracy->>Tracy: Analyze findings (Confirmed/Deduced/Hypothesized)
Tracy->>Tracy: Trace code & map I/O boundaries
Tracy->>Investigation: Generate investigation file with findings, fix direction, reproduction plan
deactivate Tracy
Investigation-->>QuickDev: Evidence-graded findings & fix direction (quick path)
Investigation-->>PRD: Investigation as contextual input (systemic rewrite path)
activate QuickDev
QuickDev->>QuickDev: Implement fix using investigation context
deactivate QuickDev
activate PRD
PRD->>PRD: Scope requirements from investigation findings
deactivate PRD
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-02-discovery.md (1)
66-67: Keep the context-boundary list consistent with investigation inputs.Line 66/75 adds investigations to discovery state, but Line 45 still omits investigations from the “already loaded in memory” list. Aligning those instructions will reduce prompt ambiguity.
Suggested wording update
-- Input documents already loaded are in memory (product briefs, research, brainstorming, project docs) +- Input documents already loaded are in memory (product briefs, research, brainstorming, investigations, project docs)Also applies to: 75-76
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-02-discovery.md` around lines 66 - 67, The context-boundary list is inconsistent: add investigations to the “already loaded in memory” list so it matches the discovery state keys used elsewhere—include the investigation-related item (investigationCount / Tracy investigation or archaeology files) alongside projectDocsCount in the list, and make the same change for the other occurrence that mirrors lines 75-76 so both places consistently document investigations as preloaded inputs.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/reference/workflow-map.md`:
- Around line 74-75: The docs incorrectly imply automatic consumption of
investigation artifacts by quick-dev; update the workflow text to state that
bmad-quick-dev / bmad-dev-story do not auto-load `{slug}-investigation.md`
unless an explicit loader is implemented, and either (a) reword the entries in
the workflow-map (`bmad-investigate` and `bmad-quick-dev` rows) and the
clarify-and-route doc
(`src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md`)
to describe a manual intent/artifact handoff, or (b) implement and document
explicit discovery/loading behavior in `bmad-quick-dev` (the
step-01-clarify-and-route flow) so it reliably reads `{slug}-investigation.md`;
choose one approach and make corresponding edits so the map and step doc are
consistent.
In `@src/bmm-skills/4-implementation/bmad-code-archaeology/SKILL.md`:
- Around line 97-106: Resume-by-path flow can trigger follow-up writes without
setting the {case_file} target; when resume mode is triggered by an explicit
file path ensure you derive and assign {case_file} from that path
(normalize/resolve the path, verify existence) before any append/update
operations (the logic around "Resume mode triggers" and the subsequent "Append a
new section" step). Update the resume-by-path branch to set {case_file} =
resolved input path (or computed investigations_dir + slug if a slug was
supplied), validate the file exists/readable, and only then perform the "##
Follow-up: {date}" append so updates go to the correct file.
---
Nitpick comments:
In
`@src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-02-discovery.md`:
- Around line 66-67: The context-boundary list is inconsistent: add
investigations to the “already loaded in memory” list so it matches the
discovery state keys used elsewhere—include the investigation-related item
(investigationCount / Tracy investigation or archaeology files) alongside
projectDocsCount in the list, and make the same change for the other occurrence
that mirrors lines 75-76 so both places consistently document investigations as
preloaded inputs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: a4fc4c78-efa3-4abf-83ab-5e1b77d86d2b
⛔ Files ignored due to path filters (3)
src/bmm-skills/module-help.csvis excluded by!**/*.csvwebsite/public/workflow-map-diagram-fr.htmlis excluded by!website/**website/public/workflow-map-diagram.htmlis excluded by!website/**
📒 Files selected for processing (18)
docs/explanation/forensic-investigation.mddocs/explanation/named-agents.mddocs/fr/explanation/forensic-investigation.mddocs/fr/reference/agents.mddocs/fr/reference/workflow-map.mddocs/reference/agents.mddocs/reference/workflow-map.mdsrc/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-01-init.mdsrc/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-02-discovery.mdsrc/bmm-skills/4-implementation/bmad-agent-investigator/SKILL.mdsrc/bmm-skills/4-implementation/bmad-agent-investigator/customize.tomlsrc/bmm-skills/4-implementation/bmad-code-archaeology/SKILL.mdsrc/bmm-skills/4-implementation/bmad-code-archaeology/assets/investigation-template.mdsrc/bmm-skills/4-implementation/bmad-code-archaeology/customize.tomlsrc/bmm-skills/4-implementation/bmad-investigate/SKILL.mdsrc/bmm-skills/4-implementation/bmad-investigate/assets/investigation-template.mdsrc/bmm-skills/4-implementation/bmad-investigate/customize.tomlsrc/bmm-skills/module.yaml
Comment on lines
+74
to
+75
| | `bmad-investigate` | Forensic case investigation. Produces a fix direction quick-dev can act on. | `{slug}-investigation.md` → | | ||
| | `bmad-quick-dev` | Unified quick flow. Clarify intent, plan, implement, review, and present. | `spec-*.md` + code | |
There was a problem hiding this comment.
Quick-dev handoff is documented as automatic, but the current flow doesn’t explicitly load investigation artifacts.
Lines [74-75] and Line [81] read as if bmad-quick-dev/bmad-dev-story directly consume {slug}-investigation.md. In src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md (Lines [49-75]), quick-dev does not define an explicit investigation-file discovery path; it primarily loads planning/implementation context and optional intent/spec input. Please reword this as a manual intent handoff (or add explicit loader behavior in quick-dev if automatic consumption is intended).
✏️ Suggested doc wording adjustment
-| `bmad-investigate` | Forensic case investigation. Produces a fix direction quick-dev can act on. | `{slug}-investigation.md` → |
+| `bmad-investigate` | Forensic case investigation. Produces a fix direction and case file you can pass into quick-dev as intent context. | `{slug}-investigation.md` |
-The investigation file is implementation-ready context: when `bmad-investigate` finalizes a fix direction, `bmad-quick-dev` (or `bmad-dev-story`) consumes it as the intent input.
+The investigation file can be used as implementation-ready intent context: pass `{slug}-investigation.md` into `bmad-quick-dev` when routing from Tracy into Quick Flow.Also applies to: 81-81
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/reference/workflow-map.md` around lines 74 - 75, The docs incorrectly
imply automatic consumption of investigation artifacts by quick-dev; update the
workflow text to state that bmad-quick-dev / bmad-dev-story do not auto-load
`{slug}-investigation.md` unless an explicit loader is implemented, and either
(a) reword the entries in the workflow-map (`bmad-investigate` and
`bmad-quick-dev` rows) and the clarify-and-route doc
(`src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md`)
to describe a manual intent/artifact handoff, or (b) implement and document
explicit discovery/loading behavior in `bmad-quick-dev` (the
step-01-clarify-and-route flow) so it reliably reads `{slug}-investigation.md`;
choose one approach and make corresponding edits so the map and step doc are
consistent.
There was a problem hiding this comment.
🧩 Analysis chain
Let me pull up the French mirror and any other relevant files to get a complete picture before proposing the guideline.
🏁 Script executed:
#!/bin/bash
# Get the French workflow-map for comparison
cat docs/fr/reference/workflow-map.md
echo "---SEPARATOR---"
# Check all unique "Produces" patterns across both files
echo "=== EN Produces column ==="
grep "^|" docs/reference/workflow-map.md | awk -F'|' '{print $4}' | sort | uniq
echo "=== FR Produces column ==="
grep "^|" docs/fr/reference/workflow-map.md | awk -F'|' '{print $4}' | sort | uniq
Length of output: 11338
@anderewrey, here is a full audit of the "Produces" column across both EN and FR workflow-map files and a proposed house-style guideline.
Audit findings
There are three classes of inconsistency today:
1. Placeholder style — four different conventions in use
| File | Current style | Example |
|---|---|---|
prfaq-{project}.md |
{project} |
curly, word "project" |
story-[slug].md |
[slug] |
square brackets |
spec-*.md |
* glob |
wildcard |
{slug}-investigation.md |
{slug} |
curly, word "slug" |
2. Mixed file + prose in a single cell
`architecture.md` with ADRs— file name plus a prose annotation`spec-*.md` + code— file name plus a prose artifact type
3. Stray directional symbol
- Quick Flow table:
`{slug}-investigation.md` →— the→doesn't appear anywhere else and has no defined meaning in the table convention.
Proposed guideline
Workflow-map "Produces" column style guide
- All artifact filenames must be wrapped in backtick code formatting.
- Variable segments of a filename use
{slug}as the universal placeholder — never[slug],{project}, or a glob*.- When a workflow produces both a named artifact file and additional unstructured output (e.g., working code), list the named file first in backticks, then append the prose part after a comma:
`spec-{slug}.md`, working code.- Non-file outputs (status decisions, lessons learned, sprint updates, etc.) remain as plain prose — no backticks.
- No directional arrows or decorators (
→,↓, etc.) in the Produces cell.
Concrete changes (EN + FR)
--- a/docs/reference/workflow-map.md
+++ b/docs/reference/workflow-map.md
@@ Phase 1
-| `bmad-prfaq` | Working Backwards — stress-test and forge your product concept | `prfaq-{project}.md` |
+| `bmad-prfaq` | Working Backwards — stress-test and forge your product concept | `prfaq-{slug}.md` |
@@ Phase 3
-| `bmad-create-architecture` | Make technical decisions explicit | `architecture.md` with ADRs |
+| `bmad-create-architecture` | Make technical decisions explicit | `architecture.md`, ADRs included |
@@ Phase 4
-| `bmad-create-story` | Prepare next story for implementation | `story-[slug].md` |
+| `bmad-create-story` | Prepare next story for implementation | `story-{slug}.md` |
@@ Quick Flow table
-| `bmad-investigate` | Forensic case investigation. Produces a fix direction quick-dev can act on. | `{slug}-investigation.md` → |
+| `bmad-investigate` | Forensic case investigation. Produces a fix direction quick-dev can act on. | `{slug}-investigation.md` |
-| `bmad-quick-dev` | Unified quick flow. Clarify intent, plan, implement, review, and present. | `spec-*.md` + code |
+| `bmad-quick-dev` | Unified quick flow. Clarify intent, plan, implement, review, and present. | `spec-{slug}.md`, working code |The same set of changes applies to docs/fr/reference/workflow-map.md (keeping prose portions in French):
--- a/docs/fr/reference/workflow-map.md
+++ b/docs/fr/reference/workflow-map.md
-| `bmad-prfaq` | ... | `prfaq-{project}.md` |
+| `bmad-prfaq` | ... | `prfaq-{slug}.md` |
-| `bmad-create-architecture` | ... | `architecture.md` avec ADRs[^3] |
+| `bmad-create-architecture` | ... | `architecture.md`, ADRs inclus[^3] |
-| `bmad-create-story` | ... | `story-[slug].md` |
+| `bmad-create-story` | ... | `story-{slug}.md` |
-| `bmad-investigate` | ... | `{slug}-investigation.md` → |
+| `bmad-investigate` | ... | `{slug}-investigation.md` |
-| `bmad-quick-dev` | ... | `spec-*.md` + code |
+| `bmad-quick-dev` | ... | `spec-{slug}.md`, code |The non-file outputs ("Research findings", "Working code + tests", "PASS/CONCERNS/FAIL decision", "Approved or changes requested", "Updated plan or re-routing", "Sprint status update", "Lessons learned", "Epic files with stories") are already consistent as plain prose and don't need changes under this guideline.
Once you're aligned on the guideline, I can kick off the code change planning to apply all of these uniformly. Would you like me to proceed?
🧠 Learnings used
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1807
File: src/bmm/workflows/bmad-quick-flow/quick-dev2/steps/step-02-plan.md:21-23
Timestamp: 2026-03-02T23:53:28.943Z
Learning: In BMAD-METHOD quick-flow workflows (quick-spec, quick-dev2), workflow.md persists as root context throughout all step execution. Just-In-Time (JIT) loading governs step files only, not the workflow.md orchestrator. Step files can reference standards and configuration defined in workflow.md (e.g., "READY FOR DEVELOPMENT standard defined in workflow.md") because workflow.md remains loaded as the persistent orchestrator context.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1807
File: src/bmm/workflows/bmad-quick-flow/quick-dev2/steps/step-01-clarify-and-route.md:21-24
Timestamp: 2026-03-02T23:53:06.292Z
Learning: In BMAD-METHOD workflows (quick-spec, quick-dev, quick-dev2), "skip to step X" instructions based on detected artifact state constitute state-aware routing, not prohibited optimization skipping. The "NEVER skip steps" rule in workflow.md prohibits agents from autonomously optimizing the sequence for efficiency, but does not prohibit state-aware routing to appropriate resumption points when pre-existing artifacts are detected (e.g., specs with status `ready-for-dev`, `in-progress`, or `in-review`).
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:31.149Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), the input-trust guardrail (line 17: "may contain hallucinations, scope creep, or unvalidated assumptions. Follow the workflow exactly...") is intentionally advisory, not a hard enforcement gate. Enforcement is provided by the surrounding workflow structure: the mandatory clarify loop (Step 2 clarify intent), codebase investigation, and the human checkpoint in Step 2. Reviewers should not flag this guardrail as non-operational or require it to include a mandatory verification sub-step.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1934
File: src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-02-discovery.md:158-162
Timestamp: 2026-03-13T21:43:13.299Z
Learning: In BMAD-METHOD, converted-workflow native skills (e.g., src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/) use a different `./` path resolution convention from `bmad-quick-dev-new-preview`-style skills. In step files located inside a `steps/` subdirectory of a converted-workflow skill, `./` resolves relative to the file's own directory (`steps/`), not relative to the skill root. Therefore `./step-03-core-experience.md` inside `steps/step-02-discovery.md` correctly resolves to `steps/step-03-core-experience.md`. Only `workflow.md` at the skill root needs the `./steps/` prefix to reach step files. Reviewers must not apply the skill-root resolution rule from learning 1647d05b (scoped to bmad-quick-dev-new-preview) to converted-workflow skills.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1874
File: src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-12-complete.md:90-90
Timestamp: 2026-03-09T19:38:08.849Z
Learning: In BMAD-METHOD completion step files (e.g., src/bmm/workflows/**/steps/*-complete.md), "Suggest Next Workflows" sections that contain only a delegation to the help mechanism (previously "Read fully and follow: {project-root}/_bmad/core/tasks/help.md", now "Run `/bmad-help`") are intentional. The help skill is the canonical dynamic oracle for next-step guidance; these sections are not required to enumerate a hardcoded list of next workflows. Reviewers must not flag this delegation pattern as missing content or as conflicting with section headings.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1850
File: docs/explanation/quick-flow.md:48-49
Timestamp: 2026-03-07T23:10:54.712Z
Learning: In BMAD-METHOD quick-flow documentation (e.g., docs/explanation/quick-flow.md), the short-form invocations `quick-dev` and `quick-spec` (without the `bmad-` prefix) are established aliases used by the quick-flow system by design. They are not errors or missing prefixes. Reviewers should not flag these short forms as incorrect or suggest replacing them with the full `bmad-quick-dev` / `bmad-quick-spec` skill names in example commands.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:27-30
Timestamp: 2026-03-08T13:17:20.371Z
Learning: In BMAD-METHOD correct-course workflow (src/bmm/workflows/4-implementation/correct-course/workflow.md), the "DOCUMENT OUTPUT" contract line ("Updated epics, stories, or PRD sections...") is wording carried over verbatim from the original instructions.md during the yaml-to-md format conversion PR `#1858`. It is a pre-existing limitation, not a regression introduced by the conversion. Reviewers should not flag this narrower output contract during format conversion PRs; any expansion of the contract to include Architecture/UI/UX changes and Sprint Change Proposal file should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1877
File: src/core/tasks/bmad-editorial-review-prose/workflow.md:0-0
Timestamp: 2026-03-11T11:49:23.055Z
Learning: In BMAD-METHOD workflow.md files (e.g., src/core/tasks/bmad-editorial-review-prose/workflow.md), forward references to the execution steps using informal language such as "flow section" (rather than the precise section heading, e.g., "EXECUTION") are understood contextually by LLM agents and should not be flagged as terminology mismatches or invalid cross-references. Reviewers must not flag informal section name references in role/goal preamble text as errors requiring correction.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:31.149Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), the phrase "Follow the workflow exactly" in the input-trust guardrail (line 17) is an input-trust directive, not a routing constraint. It does not conflict with, and does not override, the state-aware skip/resume rules in ARTIFACT SCAN (e.g., "skip to step 3" or "skip to step 4" based on artifact status). State-aware routing is part of following the workflow correctly. Reviewers should not flag this phrase as creating a conflict with conditional routing branches.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1876
File: src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md:15-16
Timestamp: 2026-03-11T18:02:12.404Z
Learning: In BMAD-METHOD bmad-quick-dev-new-preview step-05-present.md (src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md), setting the `{spec_file}` frontmatter status to `done` before displaying the summary and before any explicit human approval is intentional by design. The workflow treats the spec as finalized at the presentation stage; human review and further revision happen at the user's discretion after presentation. Reviewers must not flag this ordering as premature finalization or request a gating approval step before the status is written.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:60-65
Timestamp: 2026-03-08T17:15:57.663Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the `{{story_path}}` input parameter used in Step 1 ("Use provided {{story_path}} or ask user which story file to review") is not declared in the Input Files table or Configuration Loading section. This is a pre-existing issue inherited from the original instructions.xml, not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag the absence of a formal `{{story_path}}` declaration in conversion PRs; any addition of this parameter to the inputs table should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1871
File: src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md:30-34
Timestamp: 2026-03-09T14:19:53.575Z
Learning: In BMAD-METHOD step-04-review.md (src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md), the no-subagent fallback role descriptions (Blind hunter, Edge case hunter, Acceptance auditor) are intentional pointers to named skills, not full contract reproductions. When a fallback prompt file names a skill explicitly (e.g., `bmad-review-edge-case-hunter`), the agent running in the separate session resolves the complete contract — including JSON output schema and execution steps — by reading the skill's own workflow.md. Reviewers should not flag the absence of inline contract reproduction in fallback role blurbs; the skill name is sufficient.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1934
File: src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-03-core-experience.md:182-182
Timestamp: 2026-03-13T21:42:35.893Z
Learning: In BMAD-METHOD, `./` relative path references in step files under `src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/*.md` resolve relative to the step file's own directory (i.e., the `steps/` folder), NOT relative to the skill root. Therefore `./step-04-emotional-response.md` inside `steps/step-03-core-experience.md` correctly resolves to `steps/step-04-emotional-response.md`. Reviewers must not flag these as missing a `steps/` prefix. The skill-root resolution rule from learning 1647d05b applies specifically to `bmad-quick-dev-new-preview/steps/*.md` and must not be generalized to all skill step subdirectories.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1934
File: src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-06-design-system.md:218-218
Timestamp: 2026-03-13T21:43:06.947Z
Learning: In BMAD-METHOD, `./` relative path references in skill step files under `src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/*.md` resolve relative to the step file's own directory (`steps/`), NOT relative to the skill root. Therefore `./step-07-defining-experience.md` inside `steps/step-06-design-system.md` correctly resolves to `steps/step-07-defining-experience.md`. Reviewers must not flag same-directory relative references in these files as missing a `steps/` prefix. Learning 1647d05b (which states `./` resolves to the skill root) applies specifically to `bmad-quick-dev-new-preview/steps/*.md` files, not universally to all skill step subdirectories.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:31.149Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), artifact precedence over prompt text is already established by three layered controls: (1) the ARTIFACT SCAN halt-and-user-choice flow, (2) frozen-after-approval locking, and (3) the input-trust guardrail. No additional explicit precedence rule is needed. Reviewers should not flag the absence of a standalone "artifact state governs routing" precedence declaration.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:40-47
Timestamp: 2026-03-08T13:17:27.822Z
Learning: In BMAD-METHOD, sharded document inputs (e.g., `*prd*/*.md`, `*epic*/*.md`, `*architecture*/*.md`, `*ux*/*.md`) in workflow input tables are doc-convention glob patterns illustrating the directory structure, not independent behavioral contracts. The actual discovery algorithm for sharded documents always requires an `index.md` entry point within the sharded directory. This is an intentional, project-wide convention used consistently across all workflows. Reviewers should not flag the glob patterns in input tables as mismatched with the index.md-based discovery logic.
Learnt from: n-zhi
Repo: bmad-code-org/BMAD-METHOD PR: 1817
File: tools/cli/installers/lib/ide/templates/combined/antigravity-workflow-yaml.md:13-13
Timestamp: 2026-03-05T14:31:20.599Z
Learning: In BMAD-METHOD, the "Save outputs after EACH section when generating any documents from templates" directive in antigravity-workflow-yaml.md (tools/cli/installers/lib/ide/templates/combined/antigravity-workflow-yaml.md) is a pre-existing pattern inherited verbatim from the corresponding default-*.md template. It is not introduced by PR `#1817`. A future dedicated PR should make this save step conditional and idempotent: consult an artifact policy flag before persisting, use overwrite/merge/versioned semantics, perform atomic writes, and redact sensitive keys—applied holistically across all affected default-*.md and antigravity-*.md templates.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1807
File: src/bmm/workflows/bmad-quick-flow/quick-dev2/workflow.md:84-87
Timestamp: 2026-03-02T23:53:19.550Z
Learning: In BMAD-METHOD workflows under src/bmm/workflows/, the "Micro-file Design" pattern is used where step files are intentionally self-contained. Step files declare their own variables (e.g., templateFile, wipFile) even if those variables are also defined at the workflow level, so each step can be read and understood in isolation. This duplication is a deliberate architectural choice, not drift. The quick-spec and quick-dev2 workflows follow this pattern.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1875
File: src/core/tasks/bmad-editorial-review-structure/workflow.md:139-142
Timestamp: 2026-03-11T09:57:45.068Z
Learning: In BMAD-METHOD workflow.md files (e.g., src/core/tasks/bmad-editorial-review-structure/workflow.md), a short-circuit fallback sentence on the no-findings path (e.g., "No substantive changes recommended -- document structure is sound") is intentional and does not need to reproduce the full output-schema structure (summary block, empty recommendations list, estimated reduction line). Reviewers must not flag this as a contradiction with the normal output format.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md:119-150
Timestamp: 2026-03-06T01:54:20.886Z
Learning: In BMAD-METHOD, workflow step files under src/bmm/workflows/**/steps/*.md are LLM agent prompts loaded fresh at execution time on every run. There is no cached or in-progress state between runs. The agent always reads the current version of the step file, so migration guidance for step-file schema changes (e.g., renumbered steps, new sub-steps) is not applicable and should not be flagged in reviews.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:32-37
Timestamp: 2026-03-08T13:17:23.329Z
Learning: In BMAD-METHOD, implicit write targets referenced only within checklist steps (e.g., `sprint-status.yaml` in src/bmm/workflows/4-implementation/correct-course/checklist.md) are not declared as explicit path variables in the workflow's Paths section. This is consistent with the convention across all workflows in the project. Reviewers should not flag the absence of such path declarations when the file location is implied by the checklist context.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1875
File: src/core/tasks/bmad-editorial-review-structure/workflow.md:63-67
Timestamp: 2026-03-11T09:57:42.463Z
Learning: In BMAD-METHOD bmad-editorial-review-structure/workflow.md, Step 4 (Flow Analysis) intentionally applies reader-journey, pacing, and FAQ-placement checks to all document types, including Reference/Database. The executing agent is expected to contextually calibrate these checks against the selected structure model rather than having explicit per-model conditional branches. Reviewers should not flag the absence of per-model conditional guards in Step 4 as a false-positive risk or structural conflict.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: src/bmm/workflows/4-implementation/create-story/discover-inputs.md:63-67
Timestamp: 2026-03-09T00:01:27.172Z
Learning: In BMAD-METHOD discover-inputs.md (src/bmm/workflows/4-implementation/create-story/discover-inputs.md and src/bmm/workflows/4-implementation/code-review/discover-inputs.md), the whole-document fallback (Step 2b) intentionally loads ALL glob matches into {pattern_name_content} rather than selecting a single canonical file. This is deliberate design — the reporting step (Step 3) and LLM context handling are relied upon to mitigate contradictory sources. Reviewers should not flag the absence of a canonical-match or deduplication rule in the whole-document fallback.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1896
File: src/core/tasks/bmad-shard-doc/workflow.md:73-86
Timestamp: 2026-03-11T21:28:59.373Z
Learning: In BMAD-METHOD, the missing HALT/error-handling paths in the "Handle Original Document" step of src/core/tasks/bmad-shard-doc/workflow.md (delete and move branches, lines ~73-86) — specifically the absence of failure checks after the delete, mkdir, and move operations before printing confirmation messages — are pre-existing behavior carried over verbatim from the original src/core/tasks/shard-doc.xml. PR `#1896` is a pure format conversion (XML task → native skill directory) with no behavioral changes. Reviewers must not flag these missing error paths as regressions introduced by the conversion; any behavioral improvements (e.g., adding HALT on failure for filesystem ops) should be addressed in a dedicated follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 2104
File: src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md:0-0
Timestamp: 2026-03-22T22:47:08.579Z
Learning: In BMAD-METHOD, behavioral instruction changes to step files under `src/bmm-skills/**` (e.g., adding checkbox-tracking instructions to `src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md`) are considered implementation details and do not require corresponding documentation updates under `docs/`. Reviewers must not flag the absence of a `docs/` change for such step-level behavioral additions.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1896
File: src/core/tasks/bmad-shard-doc/workflow.md:79-85
Timestamp: 2026-03-11T21:29:04.747Z
Learning: In BMAD-METHOD, the archive branch in src/core/tasks/bmad-shard-doc/workflow.md (Step 6, "If user selects m (move)") does not check whether the archive destination path already exists before moving the original document, risking a silent overwrite on reruns. This is pre-existing behavior carried over verbatim from the original src/core/tasks/shard-doc.xml. PR `#1896` is a faithful format conversion (XML task → native skill directory) and does not change workflow logic. Reviewers must not flag the missing existence check / overwrite guard as a regression introduced by this conversion; any behavioral fix (e.g., prompting user to confirm overwrite, generating a non-colliding name) should be addressed in a dedicated follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: tools/cli/installers/lib/core/manifest-generator.js:347-354
Timestamp: 2026-03-09T00:01:25.359Z
Learning: In BMAD-METHOD `tools/cli/installers/lib/core/manifest-generator.js`, `getWorkflowsFromPath()` silently skips `workflow.md` files that lack YAML frontmatter (via `continue`). This is intentional: all valid workflow.md files are structurally required to have frontmatter, so files without it are invalid by convention and should be skipped. Reviewers must not flag this silent skip as a missing error or warning — the existing debug log is sufficient and a hard error is not warranted.
Learnt from: eatse21
Repo: bmad-code-org/BMAD-METHOD PR: 2073
File: docs/fr/reference/agents.md:14-14
Timestamp: 2026-03-20T10:22:40.574Z
Learning: In BMAD-METHOD, the agent skill ID naming convention is being refactored to drop the `-agent-` segment (e.g., `bmad-analyst` instead of `bmad-agent-analyst`, `bmad-architect` instead of `bmad-agent-architect`, `bmad-ux-designer` instead of `bmad-agent-ux-designer`, `bmad-tech-writer` instead of `bmad-agent-tech-writer`). This refactor started in PR `#1834` and PR `#1850`. Documentation (including French translations under docs/fr/) that already uses the shorter IDs (without `-agent-`) is intentionally forward-looking and aligned with this in-progress refactor. Reviewers must not flag the absence of `-agent-` in agent skill IDs as incorrect during this transition period.
Learnt from: muratkeremozcan
Repo: bmad-code-org/BMAD-METHOD PR: 1367
File: src/bmm/workflows/testarch/test-design/instructions.md:304-307
Timestamp: 2026-01-22T18:34:14.142Z
Learning: When documenting cross-reference patterns in Markdown, ensure header anchors follow GitHub's anchor generation rules: lowercase, spaces to hyphens, remove emojis/special characters, and strip leading/trailing hyphens. Example: '### 🚨 R-001: Title' becomes '#r-001-title'. Use anchors that reflect these rules in documentation across Markdown files.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1850
File: docs/how-to/install-bmad.md:81-81
Timestamp: 2026-03-07T23:10:38.564Z
Learning: In documentation under docs/, ensure that the artifact 'bmad-persona' is described as a valid installed skill artifact of BMAD-METHOD and shown in install output examples. Do not flag it as undocumented or missing from the skills reference in install-related docs (e.g., docs/how-to/install-bmad.md).
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1850
File: docs/how-to/quick-fixes.md:41-47
Timestamp: 2026-03-07T23:11:09.292Z
Learning: Enforce the documented architectural relationship: in BMAD-METHOD, agents are invoked via their skill entry point, and there is no overlap/conflict between agent skills and standalone workflow skills. Reviewers should not flag invocations like 'bmad-quick-flow-solo-dev' as conflicting with workflow skills like 'bmad-quick-spec'. This guideline applies to documentation files under docs (md) and should be checked whenever similar agent/skill invocations appear.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1850
File: docs/tutorials/getting-started.md:241-245
Timestamp: 2026-03-07T23:11:16.460Z
Learning: In the BMAD-METHOD repository, slash-prefixed skill invocations (e.g., /bmad-correct-course, /bmad-brainstorming, /bmad-help) are the standard IDE invocation syntax to reference skills in Claude Code, Cursor, and similar AI IDEs. In user-facing docs and FAQ sections, these slash-prefixed references are correct and intentional. Reviewers should not flag slash-prefixed invocations as legacy slash-command notation or suggest removing the leading slash. Apply this guidance to Markdown documentation under docs/ (e.g., docs/tutorials, docs/faq) and related docs files.
Comment on lines
+97
to
+106
| - The user passed a path to an existing archaeology file (anywhere under the project). | ||
| - A slug was supplied AND `{investigations_dir}/{slug}-archaeology.md` already exists. | ||
| - The user explicitly said "resume", "continue", "follow up on", or named a prior exploration. | ||
|
|
||
| <check if="Resume mode triggers"> | ||
| <action>Read the existing archaeology file fully — restore Code area surveyed, How it works, Inferred behavior, Uncertain areas, Further reading needed, Source Code Trace, and Conclusion.</action> | ||
| <action>Identify the frontier: open uncertain areas, documented data gaps, areas marked as "further reading needed".</action> | ||
| <action>Ask the user what they want to dig into — a specific uncertain area, a new entry point, or the next item flagged for further reading.</action> | ||
| <action>Append a new section to the file: `## Follow-up: {date}` with empty subsections. All findings from this session land under this dated heading.</action> | ||
| <goto step="3">Skip Phase 1 scoping and go to Phase 2 input/output mapping for the chosen target.</goto> |
There was a problem hiding this comment.
Resume-by-path branch doesn’t bind {case_file} before writing follow-up updates.
When resume mode is triggered by an explicit file path (Line [97]), subsequent actions append/update {case_file} (starting Line [105]) without explicitly setting {case_file} from that path. This can send updates to the wrong target file.
🛠️ Suggested workflow fix
<step n="1" goal="Detect mode — new exploration or resume">
...
<check if="Resume mode triggers">
+ <action>If the user supplied a file path, set `{case_file}` to that exact path.</action>
+ <action>If `{slug}` is empty and `{case_file}` ends with `-archaeology.md`, derive `{slug}` from the filename stem.</action>
+ <action>If resume is slug-based (no explicit file path), set `{case_file}` to `{investigations_dir}/{slug}-archaeology.md`.</action>
<action>Read the existing archaeology file fully — restore Code area surveyed, How it works, Inferred behavior, Uncertain areas, Further reading needed, Source Code Trace, and Conclusion.</action>
<action>Identify the frontier: open uncertain areas, documented data gaps, areas marked as "further reading needed".</action>
<action>Ask the user what they want to dig into — a specific uncertain area, a new entry point, or the next item flagged for further reading.</action>
<action>Append a new section to the file: `## Follow-up: {date}` with empty subsections. All findings from this session land under this dated heading.</action>
<goto step="3">Skip Phase 1 scoping and go to Phase 2 input/output mapping for the chosen target.</goto>
</check>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm-skills/4-implementation/bmad-code-archaeology/SKILL.md` around lines
97 - 106, Resume-by-path flow can trigger follow-up writes without setting the
{case_file} target; when resume mode is triggered by an explicit file path
ensure you derive and assign {case_file} from that path (normalize/resolve the
path, verify existence) before any append/update operations (the logic around
"Resume mode triggers" and the subsequent "Append a new section" step). Update
the resume-by-path branch to set {case_file} = resolved input path (or computed
investigations_dir + slug if a slug was supplied), validate the file
exists/readable, and only then perform the "## Follow-up: {date}" append so
updates go to the correct file.
bmadcode
requested changes
Apr 28, 2026
Collaborator
bmadcode
left a comment
bmadcode
left a comment
There was a problem hiding this comment.
Thanks AJ — the methodology here is genuinely strong. Evidence grading, hypothesis discipline, stronghold-first tracing, working backward from outputs, boundary mapping, and the structured case-file as a hand-off artifact that survives context compaction — that's a real forensic discipline most contributions don't bring. I want to find a way to land the substance.
Three structural changes before this can merge:
1. No new agent. We're keeping the named-agents roster persona-shaped, not task-shaped. Investigation belongs under Amelia — she already owns brownfield bug-fix work, and "investigate before you fix" fits there cleanly. The workflow is what carries the value; Tracy as a separate persona dilutes the roster.
2. Fold the two workflows into one skill with progressive disclosure. The current bmad-investigate SKILL.md already proves they're the same skill — Phase 4 widens into archaeology techniques inline (I/O mapping, frequent-terms scan, control-flow filtering, working backward, boundary tracing) when the bug isn't local. The split is purpose-of-arrival, not methodology:
- Bug-investigation mode: bug ticket / log / crash dump → root cause + fix direction. Hypothesis grading is central.
- Archaeology mode: "explain this subsystem" → mental model + area map. Lighter on hypothesis grading.
Stronghold reasoning, backward tracing, and boundary mapping are shared — the bug-investigation flow is essentially archaeology plus a hypothesis/evidence overlay. One skill, mode detected at activation, with the case-file template branching at finalize time.
3. Drop the regimented step structure. This is the bigger lift. We're moving away from numbered <step n="N"> choreography (and away from the steps-c/step-NN-*.md split too — that pattern hasn't been retired everywhere yet, but it's not where we're going). The new shape is outcome-based skill engineering — describe what to achieve, trust the LLM to figure out how, and use progressive disclosure: a short SKILL.md that routes by intent, with deeper procedural detail deferred to references/*.md loaded on demand.
The cleanest exemplar is the workflow-builder itself — short SKILL.md, explicit intent-routing table (Build / Convert / Quality Analyze), 3-way "Analyze / Edit / Rebuild" disambiguation when given an existing skill, deeper flow in references/:
That's structurally what your skill wants to look like — top-level dispatch on intent (investigate-bug / archaeology / resume-existing), with each path loading its own reference file. Most of your phases map naturally — Intake, Scene Survey, Evidence Analysis, Source Code Trace, Report — they just need to be re-expressed as goals with conditional flow rather than ordered <step> blocks with halt-points.
And rather than hand-converting from XML, run the methodology through the builders themselves — they're designed to produce skills in this shape:
- https://github.com/bmad-code-org/bmad-builder/blob/main/skills/bmad-workflow-builder/SKILL.md (also handles
--convertof existing skills) - https://github.com/bmad-code-org/bmad-builder/blob/main/skills/bmad-agent-builder/SKILL.md
Smaller note: there's an existing root-cause-analysis skill in the utility-skills repo:
Worth a sentence on how this relates — pre-fix forensics on an open issue vs. post-fix analysis on a known commit?
The forensic methodology is the win here. The current shape is the issue, not the substance. Happy to pair on the conversion if the new skill-builder paradigm is unfamiliar — and feel free to reach out on Discord (bmadcode in https://discord.gg/gk8jAdXWmj) if you'd like to talk it through live before refactoring. Let me know how you'd like to proceed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Introduce Tracy, a forensic code investigator who treats every issue like a crime scene. Findings are graded as Confirmed, Deduced, or Hypothesized, hypotheses are updated (confirmed, dismissed), and the deliverable is a structured investigation file another agent or workflow can pick up cold.
Why
See #2265
How
Testing
Used with real investigation made against brownfield source code.