feat(bmm): add bmad-investigate skill
feat(bmm): add bmad-investigate skill
This commit is contained in:
Brian
GitHub
commit
24a81706ca
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
title: "Forensic Investigation"
|
||||
description: How bmad-investigate treats every issue like a crime scene, grades evidence, and produces a structured case file engineers can act on
|
||||
sidebar:
|
||||
order: 6
|
||||
---
|
||||
|
||||
You hand `bmad-investigate` a crash log, a stack trace, or just a "this used to work, now it doesn't". The skill takes
|
||||
over the investigator's discipline for the duration of the run. It does not start fixing. It opens a case file.
|
||||
|
||||
Every finding gets graded. Every hypothesis gets a status. Wrong turns are kept, not erased. The deliverable is a
|
||||
document another engineer can pick up cold.
|
||||
|
||||
This page explains why investigation is its own discipline, and what the skill buys you that a regular dev workflow
|
||||
doesn't.
|
||||
|
||||
## The Problem With "Just Debug It"
|
||||
|
||||
Normal debugging blends three things: looking at evidence, reasoning about cause, and changing code to test the theory.
|
||||
When they're blended, two failure modes show up.
|
||||
|
||||
The first is **narrative lock-in**. The first plausible story becomes the working theory, and every observation gets
|
||||
bent to fit it. The bug stays unfixed until someone gives up and starts over. Hours later.
|
||||
|
||||
The second is **evidence amnesia**. You traced something, ruled it out, but didn't write down why. Two days later, with
|
||||
fresh eyes, you trace it again. Or worse, a colleague picks up the bug and re-runs the same dead end you already
|
||||
eliminated.
|
||||
|
||||
The skill's design is a direct response to both.
|
||||
|
||||
## Evidence Grading
|
||||
|
||||
Every finding in an investigation is one of three things.
|
||||
|
||||
- **Confirmed.** Directly observed in logs, code, or dumps; cited with a specific reference (a `path:line`, a log
|
||||
timestamp, a commit hash). If someone asks "how do you know?", you point at the citation.
|
||||
- **Deduced.** Logically follows from confirmed evidence; the reasoning chain is shown. If a step in the chain is wrong,
|
||||
the deduction is wrong, and you can see exactly which step.
|
||||
- **Hypothesized.** Plausible but unconfirmed. States what evidence would confirm or refute, and declares upfront what
|
||||
would close it. Hypotheses are explicitly *not facts*.
|
||||
|
||||
The grading is not about being humble. It's about making the case file readable. A reader can scan the Confirmed section
|
||||
to know what is true, the Deduced section to know what follows, and the Hypothesized section to know what is still open.
|
||||
Confusion between the three is the most common reason investigations spiral.
|
||||
|
||||
## Stronghold First
|
||||
|
||||
Investigation never starts from a theory. It starts from one piece of confirmed evidence and expands outward. That
|
||||
evidence might be a specific error message, a stack frame, or a timestamped log entry.
|
||||
|
||||
This is the opposite of how investigations often go. Someone has a hunch, builds a theory, and then hunts for evidence
|
||||
that supports it. The hunch can be right; the *method* is fragile because it makes confirmation bias the default.
|
||||
|
||||
A stronghold is a fact you can return to when reasoning gets murky. If a deduction takes you somewhere strange, you can
|
||||
walk it back to the stronghold and try a different branch. Without one, you don't know which step to undo.
|
||||
|
||||
When evidence is sparse, the skill says so and switches to hypothesis-driven exploration: form hypotheses from what's
|
||||
available, identify what would test each, present a prioritized data-collection list. Missing evidence is itself a
|
||||
finding.
|
||||
|
||||
## Hypothesis Discipline
|
||||
|
||||
Hypotheses are never deleted from the case file. When evidence confirms or refutes one, its **Status** field updates
|
||||
from Open to Confirmed or Refuted, and a **Resolution** explains what evidence settled it.
|
||||
|
||||
This rule has a real cost. Case files grow. The benefit is real too. The full reasoning history becomes part of the
|
||||
deliverable. Six months later, when a similar bug surfaces, the next investigator can read the original case file and
|
||||
see which paths were already eliminated and why. Without that history, every new investigator re-runs the same dead
|
||||
ends.
|
||||
|
||||
It also disciplines the present-tense investigator. If you can't delete a wrong hypothesis, you have to disprove it
|
||||
with cited evidence. Quietly dropping it when it becomes inconvenient is no longer an option.
|
||||
|
||||
## Challenge the Premise
|
||||
|
||||
The user's description of the problem is a hypothesis, not a fact. "The cache is broken" is something a user *believes*.
|
||||
Before the skill builds an investigation around it, the technical claims are verified independently. If the evidence
|
||||
contradicts the premise, the report says so directly.
|
||||
|
||||
This is the forensic instinct: the witness's account is data, not truth. Sometimes the reported bug is real but
|
||||
mislabeled. Sometimes the described symptom is downstream of a different cause. Investigations that take the premise as
|
||||
gospel diagnose the wrong defect, and the bug returns in a slightly different form.
|
||||
|
||||
## A Calibrated Walk
|
||||
|
||||
The skill is one procedure, not two modes. It calibrates how much defect-chasing versus how much area-exploration the
|
||||
input demands, on a continuous scale.
|
||||
|
||||
A symptom-driven case (a ticket, a crash, an error message, a "this used to work") leans into hypothesis tracking,
|
||||
timeline reconstruction, and a fix direction. A no-symptom case (understanding a module before you touch it, evaluating
|
||||
reusability, building a mental model) leans into I/O mapping, control-flow filtering, and a verification plan. Most
|
||||
real cases sit somewhere between, and the case file reflects whichever balance the evidence required.
|
||||
|
||||
The discipline is the same regardless of where on the scale a case lands: stronghold first, evidence grading, hypothesis
|
||||
tracking, never erase. The output is always at `{implementation_artifacts}/investigations/{slug}-investigation.md`, with
|
||||
sections that don't apply to a given case left empty or omitted.
|
||||
|
||||
When a deep bug requires understanding a broader subsystem, the procedure folds in the I/O mapping, control-flow
|
||||
filtering, working-backward-from-outputs, and cross-component boundary tracing techniques inline. The area model lands
|
||||
in the same case file. There is no mode switch.
|
||||
|
||||
## Methodology Lives in the Skill
|
||||
|
||||
The investigator's discipline is a property of the skill itself. Whoever invokes `bmad-investigate` takes on the
|
||||
methodology and communication style for the run: clinical precision, evidence-first language, no hedging, case-file
|
||||
framing. When the skill ends, the caller returns to its prior voice. No persona swap, just a tone shift from the skill's
|
||||
principles.
|
||||
|
||||
This matters because investigation and implementation reward different instincts. Investigators are slow and precise.
|
||||
Implementers are fast and confident. The same brain doing both in one session tends to do neither well. The skill
|
||||
carves out the investigative posture inline, without a context switch to a separate identity.
|
||||
|
||||
## What You Get
|
||||
|
||||
A completed investigation file:
|
||||
|
||||
- Separates Confirmed findings (with citations) from Deductions and Hypotheses
|
||||
- Preserves all hypotheses ever formed, with their final Status and Resolution
|
||||
- Reconstructs a timeline of events from multiple evidence sources
|
||||
- Identifies data gaps and what they would resolve
|
||||
- Provides actionable conclusions grounded in evidence
|
||||
- Includes a reproduction plan when a root cause is identified
|
||||
- Maintains an investigation backlog of paths still to explore
|
||||
|
||||
Hand it to an engineer who was not present and they understand what happened, what is known, and what remains uncertain.
|
||||
That's the bar.
|
||||
|
||||
## The Bigger Idea
|
||||
|
||||
Most "AI debugging" today blends evidence, reasoning, and code changes into one stream of plausible-looking text. The
|
||||
signal is hard to find, the dead ends repeat, and the case file, if there is one, is a chat log nobody wants to read.
|
||||
|
||||
`bmad-investigate` treats investigation as a discipline with its own deliverable. Evidence has a grade. Hypotheses have
|
||||
a status. Wrong turns are documented, not erased. The case file outlives the session.
|
||||
|
||||
When the next bug shows up that looks like one you've seen before, you have somewhere to start that isn't a blank
|
||||
prompt.
|
||||
|
|
@ -0,0 +1,157 @@
|
|||
---
|
||||
title: "Enquête de code"
|
||||
description: Comment bmad-investigate traite chaque problème comme une scène d'enquête, classe les preuves et produit un dossier structuré sur lequel les ingénieurs peuvent agir
|
||||
sidebar:
|
||||
order: 6
|
||||
---
|
||||
|
||||
Vous confiez à `bmad-investigate` un journal de plantage, une trace de pile, ou simplement un « ça marchait avant, plus
|
||||
maintenant ». Le skill prend le relais avec la discipline d'enquête le temps de l'exécution. Il ne se met pas à
|
||||
corriger. Il ouvre un dossier d'enquête.
|
||||
|
||||
Chaque constatation reçoit une note. Chaque hypothèse a un statut. Les fausses pistes sont conservées, pas effacées. Le
|
||||
livrable est un document qu'un autre ingénieur peut reprendre à froid.
|
||||
|
||||
Cette page explique pourquoi l'enquête est une discipline à part entière, et ce que le skill apporte qu'un workflow de
|
||||
développement classique n'apporte pas.
|
||||
|
||||
## Le problème du « débogue, c'est tout »
|
||||
|
||||
Le débogage classique mélange trois activités : examiner les preuves, raisonner sur la cause, et modifier le code pour
|
||||
tester la théorie. Quand elles sont mélangées, deux modes de défaillance apparaissent.
|
||||
|
||||
Le premier est le **verrouillage narratif**[^1]. La première histoire plausible devient la théorie de travail, et chaque
|
||||
observation est tordue pour la confirmer. Le bug reste non corrigé jusqu'à ce que quelqu'un abandonne et reparte de
|
||||
zéro. Des heures plus tard.
|
||||
|
||||
Le second est l'**amnésie probatoire**. Vous avez tracé quelque chose, l'avez écarté, mais n'avez pas écrit pourquoi.
|
||||
Deux jours plus tard, avec un regard frais, vous le retracez. Pire encore, un collègue reprend le bug et refait la même
|
||||
impasse que vous aviez déjà éliminée.
|
||||
|
||||
La conception du skill est une réponse directe à ces deux modes.
|
||||
|
||||
## Classement des preuves
|
||||
|
||||
Chaque constatation dans une enquête appartient à l'une de trois catégories.
|
||||
|
||||
- **Confirmé.** Directement observé dans les logs, le code ou les dumps ; cité avec une référence spécifique (un
|
||||
`chemin:ligne`, un horodatage de log, un hash de commit). Si quelqu'un demande « comment le sais-tu ? », vous pointez
|
||||
la citation.
|
||||
- **Déduit.** Découle logiquement de preuves confirmées ; la chaîne de raisonnement est explicite. Si une étape de la
|
||||
chaîne est fausse, la déduction est fausse, et on peut voir précisément quelle étape.
|
||||
- **Hypothétique.** Plausible mais non confirmé. Énonce quelle preuve confirmerait ou réfuterait, et déclare d'avance ce
|
||||
qui le clôturerait. Les hypothèses sont explicitement *non factuelles*.
|
||||
|
||||
Le classement n'est pas une posture d'humilité. Il rend le dossier lisible. Un lecteur peut parcourir la section
|
||||
Confirmé pour savoir ce qui est vrai, la section Déduit pour savoir ce qui en découle, et la section Hypothétique pour
|
||||
savoir ce qui reste ouvert. Confondre les trois est la première raison pour laquelle les enquêtes dérapent.
|
||||
|
||||
## Tête de pont d'abord
|
||||
|
||||
L'enquête ne part jamais d'une théorie. Elle part d'une seule preuve confirmée et étend la zone à partir de là. Cette
|
||||
preuve peut être un message d'erreur précis, une trame de pile, ou une entrée de log horodatée.
|
||||
|
||||
C'est l'inverse de la manière dont les enquêtes se déroulent souvent : quelqu'un a une intuition, construit une théorie,
|
||||
puis cherche les preuves qui la soutiennent. L'intuition peut être correcte ; la *méthode* est fragile parce qu'elle
|
||||
fait du biais de confirmation[^2] le comportement par défaut.
|
||||
|
||||
Une tête de pont est un fait sur lequel vous pouvez revenir quand le raisonnement devient flou. Si une déduction vous
|
||||
emmène quelque part d'étrange, vous pouvez remonter jusqu'à la tête de pont et essayer une autre branche. Sans elle,
|
||||
vous ne savez pas quelle étape annuler.
|
||||
|
||||
Quand les preuves sont rares, le skill le dit et bascule en exploration guidée par hypothèses : formuler des hypothèses
|
||||
à partir de ce qui est disponible, identifier ce qui testerait chacune, présenter une liste priorisée de données à
|
||||
collecter. L'absence de preuve est elle-même une constatation.
|
||||
|
||||
## Discipline des hypothèses
|
||||
|
||||
Les hypothèses ne sont jamais supprimées du dossier. Quand une preuve en confirme ou en réfute une, son champ **Statut**
|
||||
passe d'Ouvert à Confirmé ou Réfuté, et une **Résolution** explique quelle preuve a tranché.
|
||||
|
||||
Cette règle a un coût réel : les dossiers grossissent. Le bénéfice est réel aussi. L'historique complet du raisonnement
|
||||
fait partie du livrable. Six mois plus tard, quand un bug similaire surgit, le prochain enquêteur peut lire le dossier
|
||||
original et voir quelles pistes ont déjà été éliminées et pourquoi. Sans cet historique, chaque nouvel enquêteur refait
|
||||
les mêmes impasses.
|
||||
|
||||
Cela discipline aussi l'enquêteur du présent. Si vous ne pouvez pas supprimer une hypothèse fausse, vous devez la
|
||||
réfuter avec une preuve citée. L'abandonner discrètement quand elle devient gênante n'est plus une option.
|
||||
|
||||
## Remettre en question la prémisse
|
||||
|
||||
La description du problème par l'utilisateur est une hypothèse, pas un fait. « Le cache est cassé » est quelque chose
|
||||
que l'utilisateur *croit*. Avant que le skill ne construise une enquête autour, les affirmations techniques sont
|
||||
vérifiées de manière indépendante. Si la preuve contredit la prémisse, le rapport le dit directement.
|
||||
|
||||
C'est l'instinct de l'enquêteur : le récit du témoin est une donnée, pas la vérité. Parfois le bug rapporté est réel
|
||||
mais mal étiqueté. Parfois le symptôme décrit est en aval d'une cause différente. Les enquêtes qui prennent la prémisse
|
||||
pour argent comptant diagnostiquent le mauvais défaut, et le bug revient sous une forme légèrement différente.
|
||||
|
||||
## Une marche calibrée
|
||||
|
||||
Le skill est une seule procédure, pas deux modes. Il calibre la part d'investigation de défaut versus la part
|
||||
d'exploration de zone que l'entrée demande, sur une échelle continue.
|
||||
|
||||
Un cas piloté par symptôme (un ticket, un plantage, un message d'erreur, un « ça marchait avant ») penche vers le suivi
|
||||
d'hypothèses, la reconstruction de la chronologie et une direction de correction. Un cas sans symptôme (comprendre un
|
||||
module avant de le toucher, évaluer la réutilisabilité, bâtir un modèle mental) penche vers la cartographie
|
||||
entrées/sorties, le filtrage du flux de contrôle et un plan de vérification. La plupart des cas réels se situent quelque
|
||||
part entre les deux, et le dossier reflète l'équilibre que les preuves ont exigé.
|
||||
|
||||
La discipline est la même quel que soit l'endroit de l'échelle où se situe un cas : tête de pont d'abord, classement
|
||||
des preuves, suivi des hypothèses, jamais effacer. La sortie est toujours
|
||||
`{implementation_artifacts}/investigations/{slug}-investigation.md`, avec les sections qui ne s'appliquent pas à un cas
|
||||
laissées vides ou omises.
|
||||
|
||||
Quand un bug profond exige de comprendre un sous-système plus large, la procédure intègre en ligne les techniques de
|
||||
cartographie entrées/sorties, de filtrage du flux de contrôle, de raisonnement à rebours depuis les sorties et de
|
||||
traçage des frontières inter-composants[^3]. Le modèle de la zone atterrit dans le même dossier. Pas de changement de
|
||||
mode.
|
||||
|
||||
## La méthodologie vit dans le skill
|
||||
|
||||
La discipline d'enquête est une propriété du skill lui-même. Quiconque invoque `bmad-investigate` adopte la méthodologie
|
||||
et le style de communication pour l'exécution : précision clinique, langage centré sur la preuve, pas de prudence
|
||||
inutile, présentation en dossier de cas. Quand le skill se termine, l'appelant retrouve sa voix d'avant. Pas de
|
||||
changement de persona, juste un déplacement de ton issu des principes du skill.
|
||||
|
||||
Cela compte parce que l'enquête et l'implémentation récompensent des instincts différents. Les enquêteurs sont lents et
|
||||
précis. Les implémenteurs sont rapides et confiants. Le même cerveau faisant les deux dans une seule session finit par
|
||||
mal faire les deux. Le skill délimite la posture d'enquête en ligne, sans changement de contexte vers une identité
|
||||
séparée.
|
||||
|
||||
## Ce que vous obtenez
|
||||
|
||||
Un fichier d'enquête achevé :
|
||||
|
||||
- Sépare les constatations Confirmées (avec citations) des Déductions et des Hypothèses
|
||||
- Préserve toutes les hypothèses jamais formulées, avec leur Statut final et leur Résolution
|
||||
- Reconstruit une chronologie des événements à partir de plusieurs sources de preuves
|
||||
- Identifie les lacunes de données et ce qu'elles résoudraient
|
||||
- Fournit des conclusions actionnables ancrées dans les preuves
|
||||
- Inclut un plan de reproduction quand une cause racine est identifiée
|
||||
- Maintient un backlog d'enquête de pistes encore à explorer
|
||||
|
||||
Donnez-le à un ingénieur qui n'était pas là, et il comprend ce qui s'est passé, ce qui est connu, et ce qui reste
|
||||
incertain. C'est la barre.
|
||||
|
||||
## L'idée plus large
|
||||
|
||||
La plupart du « débogage par IA » d'aujourd'hui mélange preuves, raisonnement et changements de code en un seul flux de
|
||||
texte plausible. Le signal est difficile à trouver, les impasses se répètent, et le dossier, s'il en existe un, est un
|
||||
journal de chat que personne ne veut lire.
|
||||
|
||||
`bmad-investigate` traite l'enquête comme une discipline avec son propre livrable. La preuve a une note. Les hypothèses
|
||||
ont un statut. Les fausses pistes sont documentées, pas effacées. Le dossier survit à la session.
|
||||
|
||||
Quand le prochain bug ressemblant à un que vous avez déjà vu apparaîtra, vous aurez un point de départ qui ne sera pas
|
||||
une invite vide.
|
||||
|
||||
## Glossaire
|
||||
|
||||
[^1]: **Verrouillage narratif** : phénomène cognitif par lequel un raisonnement adopte la première explication plausible
|
||||
et l'enrichit progressivement, devenant de plus en plus difficile à abandonner même face à des preuves contraires.
|
||||
[^2]: **Biais de confirmation** : tendance cognitive à rechercher, interpréter et favoriser les informations qui
|
||||
confirment des croyances préexistantes, tout en ignorant ou minimisant celles qui les contredisent.
|
||||
[^3]: **Passage de frontière** : transition entre deux zones d'exécution distinctes (langage, processus, machine,
|
||||
client/serveur, code/configuration). Les frontières concentrent les bugs car chaque côté suppose que l'autre s'est
|
||||
comporté comme documenté.
|
||||
|
|
@ -5,13 +5,23 @@ sidebar:
|
|||
order: 1
|
||||
---
|
||||
|
||||
La méthode BMad (BMM) est un module de l'écosystème BMad, conçu pour suivre les meilleures pratiques de l'ingénierie du contexte et de la planification. Les agents IA fonctionnent de manière optimale avec un contexte clair et structuré. Le système BMM construit ce contexte progressivement à travers 4 phases distinctes — chaque phase, et plusieurs workflows optionnels au sein de chaque phase, produisent des documents qui alimentent la phase suivante, afin que les agents sachent toujours quoi construire et pourquoi.
|
||||
La méthode BMad (BMM) est un module de l'écosystème BMad, conçu pour suivre les meilleures pratiques de l'ingénierie du
|
||||
contexte et de la planification. Les agents IA fonctionnent de manière optimale avec un contexte clair et structuré. Le
|
||||
système BMM construit ce contexte progressivement à travers 4 phases distinctes — chaque phase, et plusieurs workflows
|
||||
optionnels au sein de chaque phase, produisent des documents qui alimentent la phase suivante, afin que les agents
|
||||
sachent toujours quoi construire et pourquoi.
|
||||
|
||||
La logique et les concepts proviennent des méthodologies agiles qui ont été utilisées avec succès dans l'industrie comme cadre mental de référence.
|
||||
La logique et les concepts proviennent des méthodologies agiles qui ont été utilisées avec succès dans l'industrie comme
|
||||
cadre mental de référence.
|
||||
|
||||
Si à tout moment vous ne savez pas quoi faire, le skill `bmad-help` vous aidera à rester sur la bonne voie ou à savoir quoi faire ensuite. Vous pouvez toujours vous référer à cette page également — mais `bmad-help` est entièrement interactif et beaucoup plus rapide si vous avez déjà installé la méthode BMad. De plus, si vous utilisez différents modules qui ont étendu la méthode BMad ou ajouté d'autres modules complémentaires non extensifs — `bmad-help` évolue pour connaître tout ce qui est disponible et vous donner les meilleurs conseils du moment.
|
||||
Si à tout moment vous ne savez pas quoi faire, le skill `bmad-help` vous aidera à rester sur la bonne voie ou à savoir
|
||||
quoi faire ensuite. Vous pouvez toujours vous référer à cette page également — mais `bmad-help` est entièrement
|
||||
interactif et beaucoup plus rapide si vous avez déjà installé la méthode BMad. De plus, si vous utilisez différents
|
||||
modules qui ont étendu la méthode BMad ou ajouté d'autres modules complémentaires non extensifs — `bmad-help` évolue
|
||||
pour connaître tout ce qui est disponible et vous donner les meilleurs conseils du moment.
|
||||
|
||||
Note finale importante : Chaque workflow ci-dessous peut être exécuté directement avec l'outil de votre choix via un skill ou en chargeant d'abord un agent et en utilisant l'entrée du menu des agents.
|
||||
Note finale importante : Chaque workflow ci-dessous peut être exécuté directement avec l'outil de votre choix via un
|
||||
skill ou en chargeant d'abord un agent et en utilisant l'entrée du menu des agents.
|
||||
|
||||
<iframe src="/workflow-map-diagram-fr.html" title="Diagramme de la carte des workflows de la méthode BMad" width="100%" height="100%" style="border-radius: 8px; border: 1px solid #334155; min-height: 900px;"></iframe>
|
||||
|
||||
|
|
@ -21,7 +31,8 @@ Note finale importante : Chaque workflow ci-dessous peut être exécuté directe
|
|||
|
||||
## Phase 1 : Analyse (Optionnelle)
|
||||
|
||||
Explorez l’espace problème et validez les idées avant de vous engager dans la planification. [**Découvrez ce que fait chaque outil et quand l’utiliser**](../explanation/analysis-phase.md).
|
||||
Explorez l’espace problème et validez les idées avant de vous engager dans la planification. [**Découvrez ce que fait
|
||||
chaque outil et quand l’utiliser**](../explanation/analysis-phase.md).
|
||||
|
||||
| Workflow | Objectif | Produit |
|
||||
|---------------------------------------------------------------------------|------------------------------------------------------------------------------------------|---------------------------|
|
||||
|
|
@ -44,7 +55,7 @@ Définissez ce qu'il faut construire et pour qui.
|
|||
Décidez comment le construire et décomposez le travail en stories.
|
||||
|
||||
| Workflow | Objectif | Produit |
|
||||
|---------------------------------------|---------------------------------------------------|------------------------------|
|
||||
|---------------------------------------|---------------------------------------------------|---------------------------------|
|
||||
| `bmad-create-architecture` | Rendez les décisions techniques explicites | `architecture.md` avec ADRs[^3] |
|
||||
| `bmad-create-epics-and-stories` | Décomposez les exigences en travail implémentable | Fichiers d'epic avec stories |
|
||||
| `bmad-check-implementation-readiness` | Vérification avant implémentation | Décision Passe/Réserves/Échec |
|
||||
|
|
@ -54,7 +65,7 @@ Décidez comment le construire et décomposez le travail en stories.
|
|||
Construisez, une story à la fois. Bientôt disponible : automatisation complète de la phase 4 !
|
||||
|
||||
| Workflow | Objectif | Produit |
|
||||
|------------------------|-------------------------------------------------------------------------------------|----------------------------------|
|
||||
|------------------------|-------------------------------------------------------------------------------------|------------------------------------------------------|
|
||||
| `bmad-sprint-planning` | Initialisez le suivi (une fois par projet pour séquencer le cycle de développement) | `sprint-status.yaml` |
|
||||
| `bmad-create-story` | Préparez la story suivante pour implémentation | `story-[slug].md` |
|
||||
| `bmad-dev-story` | Implémentez la story | Code fonctionnel + tests |
|
||||
|
|
@ -62,34 +73,49 @@ Construisez, une story à la fois. Bientôt disponible : automatisation complèt
|
|||
| `bmad-correct-course` | Gérez les changements significatifs en cours de sprint | Plan mis à jour ou réorientation |
|
||||
| `bmad-sprint-status` | Suivez la progression du sprint et le statut des stories | Mise à jour du statut du sprint |
|
||||
| `bmad-retrospective` | Revue après complétion d'un epic | Leçons apprises |
|
||||
| `bmad-investigate` | Enquête de cas avec conclusions à preuves graduées, calibrée selon l'entrée | `{slug}-investigation.md` |
|
||||
|
||||
## Quick Dev (Parcours Parallèle)
|
||||
|
||||
Sautez les phases 1-3 pour les travaux de faible envergure et bien compris.
|
||||
|
||||
| Workflow | Objectif | Produit |
|
||||
|------------------|-------------------------------------------------------------------------------------|-----------------------|
|
||||
|------------------|-------------------------------------------------------------------------------------|--------------------|
|
||||
| `bmad-quick-dev` | Flux rapide unifié — clarifie l'intention, planifie, implémente, révise et présente | `spec-*.md` + code |
|
||||
|
||||
## Gestion du Contexte
|
||||
|
||||
Chaque document devient le contexte de la phase suivante. Le PRD[^2] indique à l'architecte quelles contraintes sont importantes. L'architecture indique à l'agent de développement quels modèles suivre. Les fichiers de story fournissent un contexte focalisé et complet pour l'implémentation. Sans cette structure, les agents prennent des décisions incohérentes.
|
||||
Chaque document devient le contexte de la phase suivante. Le PRD[^2] indique à l'architecte quelles contraintes sont
|
||||
importantes. L'architecture indique à l'agent de développement quels modèles suivre. Les fichiers de story fournissent
|
||||
un contexte focalisé et complet pour l'implémentation. Sans cette structure, les agents prennent des décisions
|
||||
incohérentes.
|
||||
|
||||
### Contexte du Projet
|
||||
|
||||
:::tip[Recommandé]
|
||||
Créez `project-context.md` pour vous assurer que les agents IA suivent les règles et préférences de votre projet. Ce fichier fonctionne comme une constitution pour votre projet — il guide les décisions d'implémentation à travers tous les workflows. Ce fichier optionnel peut être généré à la fin de la création de l'architecture, ou dans un projet existant il peut également être généré pour capturer ce qui est important de conserver aligné avec les conventions actuelles.
|
||||
Créez `project-context.md` pour vous assurer que les agents IA suivent les règles et préférences de votre projet. Ce
|
||||
fichier fonctionne comme une constitution pour votre projet — il guide les décisions d'implémentation à travers tous les
|
||||
workflows. Ce fichier optionnel peut être généré à la fin de la création de l'architecture, ou dans un projet existant
|
||||
il peut également être généré pour capturer ce qui est important de conserver aligné avec les conventions actuelles.
|
||||
:::
|
||||
|
||||
**Comment le créer :**
|
||||
|
||||
- **Manuellement** — Créez `_bmad-output/project-context.md` avec votre pile technologique et vos règles d'implémentation
|
||||
- **Générez-le** — Exécutez `bmad-generate-project-context` pour l'auto-générer à partir de votre architecture ou de votre codebase
|
||||
- **Manuellement** — Créez `_bmad-output/project-context.md` avec votre pile technologique et vos règles
|
||||
d'implémentation
|
||||
- **Générez-le** — Exécutez `bmad-generate-project-context` pour l'auto-générer à partir de votre architecture ou de
|
||||
votre codebase
|
||||
|
||||
[**En savoir plus sur project-context.md**](../explanation/project-context.md)
|
||||
|
||||
## Glossaire
|
||||
|
||||
[^1]: FR / NFR (Functional / Non-Functional Requirement) : exigences décrivant respectivement **ce que le système doit faire** (fonctionnalités, comportements attendus) et **comment il doit le faire** (contraintes de performance, sécurité, fiabilité, ergonomie, etc.).
|
||||
[^2]: PRD (Product Requirements Document) : document de référence qui décrit les objectifs du produit, les besoins utilisateurs, les fonctionnalités attendues, les contraintes et les critères de succès, afin d’aligner les équipes sur ce qui doit être construit et pourquoi.
|
||||
[^3]: ADR (Architecture Decision Record) : document qui consigne une décision d’architecture, son contexte, les options envisagées, le choix retenu et ses conséquences, afin d’assurer la traçabilité et la compréhension des décisions techniques dans le temps.
|
||||
[^1]: FR / NFR (Functional / Non-Functional Requirement) : exigences décrivant respectivement **ce que le système doit
|
||||
faire** (fonctionnalités, comportements attendus) et **comment il doit le faire** (contraintes de performance, sécurité,
|
||||
fiabilité, ergonomie, etc.).
|
||||
[^2]: PRD (Product Requirements Document) : document de référence qui décrit les objectifs du produit, les besoins
|
||||
utilisateurs, les fonctionnalités attendues, les contraintes et les critères de succès, afin d’aligner les équipes sur
|
||||
ce qui doit être construit et pourquoi.
|
||||
[^3]: ADR (Architecture Decision Record) : document qui consigne une décision d’architecture, son contexte, les options
|
||||
envisagées, le choix retenu et ses conséquences, afin d’assurer la traçabilité et la compréhension des décisions
|
||||
techniques dans le temps.
|
||||
|
|
|
|||
|
|
@ -5,13 +5,22 @@ sidebar:
|
|||
order: 1
|
||||
---
|
||||
|
||||
The BMad Method (BMM) is a module in the BMad Ecosystem, targeted at following the best practices of context engineering and planning. AI agents work best with clear, structured context. The BMM system builds that context progressively across 4 distinct phases - each phase, and multiple workflows optionally within each phase, produce documents that inform the next, so agents always know what to build and why.
|
||||
The BMad Method (BMM) is a module in the BMad Ecosystem, targeted at following the best practices of context engineering
|
||||
and planning. AI agents work best with clear, structured context. The BMM system builds that context progressively
|
||||
across 4 distinct phases - each phase, and multiple workflows optionally within each phase, produce documents that
|
||||
inform the next, so agents always know what to build and why.
|
||||
|
||||
The rationale and concepts come from agile methodologies that have been used across the industry with great success as a mental framework.
|
||||
The rationale and concepts come from agile methodologies that have been used across the industry with great success as a
|
||||
mental framework.
|
||||
|
||||
If at any time you are unsure what to do, the `bmad-help` skill will help you stay on track or know what to do next. You can always refer to this for reference also - but `bmad-help` is fully interactive and much quicker if you have already installed the BMad Method. Additionally, if you are using different modules that have extended the BMad Method or added other complementary non-extension modules - `bmad-help` evolves to know all that is available to give you the best in-the-moment advice.
|
||||
If at any time you are unsure what to do, the `bmad-help` skill will help you stay on track or know what to do next. You
|
||||
can always refer to this for reference also - but `bmad-help` is fully interactive and much quicker if you have already
|
||||
installed the BMad Method. Additionally, if you are using different modules that have extended the BMad Method or added
|
||||
other complementary non-extension modules - `bmad-help` evolves to know all that is available to give you the best
|
||||
in-the-moment advice.
|
||||
|
||||
Final important note: Every workflow below can be run directly with your tool of choice via skill or by loading an agent first and using the entry from the agents menu.
|
||||
Final important note: Every workflow below can be run directly with your tool of choice via skill or by loading an agent
|
||||
first and using the entry from the agents menu.
|
||||
|
||||
<iframe src="/workflow-map-diagram.html" title="BMad Method Workflow Map Diagram" width="100%" height="100%" style="border-radius: 8px; border: 1px solid #334155; min-height: 900px;"></iframe>
|
||||
|
||||
|
|
@ -21,10 +30,11 @@ Final important note: Every workflow below can be run directly with your tool of
|
|||
|
||||
## Phase 1: Analysis (Optional)
|
||||
|
||||
Explore the problem space and validate ideas before committing to planning. [**Learn what each tool does and when to use it**](../explanation/analysis-phase.md).
|
||||
Explore the problem space and validate ideas before committing to planning. [**Learn what each tool does and when to use
|
||||
it**](../explanation/analysis-phase.md).
|
||||
|
||||
| Workflow | Purpose | Produces |
|
||||
| ------------------------------- | -------------------------------------------------------------------------- | ------------------------- |
|
||||
|---------------------------------------------------------------------------|----------------------------------------------------------------------------|---------------------------|
|
||||
| `bmad-brainstorming` | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
|
||||
| `bmad-domain-research`, `bmad-market-research`, `bmad-technical-research` | Validate market, technical, or domain assumptions | Research findings |
|
||||
| `bmad-product-brief` | Capture strategic vision — best when your concept is clear | `product-brief.md` |
|
||||
|
|
@ -35,7 +45,7 @@ Explore the problem space and validate ideas before committing to planning. [**L
|
|||
Define what to build and for whom.
|
||||
|
||||
| Workflow | Purpose | Produces |
|
||||
| --------------------------- | ---------------------------------------- | ------------ |
|
||||
|-------------------------|------------------------------------------|--------------|
|
||||
| `bmad-create-prd` | Define requirements (FRs/NFRs) | `PRD.md` |
|
||||
| `bmad-create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` |
|
||||
|
||||
|
|
@ -44,7 +54,7 @@ Define what to build and for whom.
|
|||
Decide how to build it and break work into stories.
|
||||
|
||||
| Workflow | Purpose | Produces |
|
||||
| ----------------------------------------- | ------------------------------------------ | --------------------------- |
|
||||
|---------------------------------------|--------------------------------------------|-----------------------------|
|
||||
| `bmad-create-architecture` | Make technical decisions explicit | `architecture.md` with ADRs |
|
||||
| `bmad-create-epics-and-stories` | Break requirements into implementable work | Epic files with stories |
|
||||
| `bmad-check-implementation-readiness` | Gate check before implementation | PASS/CONCERNS/FAIL decision |
|
||||
|
|
@ -54,7 +64,7 @@ Decide how to build it and break work into stories.
|
|||
Build it, one story at a time. Coming soon, full phase 4 automation!
|
||||
|
||||
| Workflow | Purpose | Produces |
|
||||
| -------------------------- | ------------------------------------------------------------------------ | -------------------------------- |
|
||||
|------------------------|-------------------------------------------------------------------------------|------------------------------------------------------|
|
||||
| `bmad-sprint-planning` | Initialize tracking (once per project to sequence the dev cycle) | `sprint-status.yaml` |
|
||||
| `bmad-create-story` | Prepare next story for implementation | `story-[slug].md` |
|
||||
| `bmad-dev-story` | Implement the story | Working code + tests |
|
||||
|
|
@ -62,23 +72,29 @@ Build it, one story at a time. Coming soon, full phase 4 automation!
|
|||
| `bmad-correct-course` | Handle significant mid-sprint changes | Updated plan or re-routing |
|
||||
| `bmad-sprint-status` | Track sprint progress and story status | Sprint status update |
|
||||
| `bmad-retrospective` | Review after epic completion | Lessons learned |
|
||||
| `bmad-investigate` | Forensic case investigation with evidence-graded findings, calibrated to the input | `{slug}-investigation.md` |
|
||||
|
||||
## Quick Flow (Parallel Track)
|
||||
|
||||
Skip phases 1-3 for small, well-understood work.
|
||||
|
||||
| Workflow | Purpose | Produces |
|
||||
| ------------------ | --------------------------------------------------------------------------- | ---------------------- |
|
||||
|------------------|---------------------------------------------------------------------------|--------------------|
|
||||
| `bmad-quick-dev` | Unified quick flow — clarify intent, plan, implement, review, and present | `spec-*.md` + code |
|
||||
|
||||
## Context Management
|
||||
|
||||
Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture tells the dev agent which patterns to follow. Story files give focused, complete context for implementation. Without this structure, agents make inconsistent decisions.
|
||||
Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture
|
||||
tells the dev agent which patterns to follow. Story files give focused, complete context for implementation. Without
|
||||
this structure, agents make inconsistent decisions.
|
||||
|
||||
### Project Context
|
||||
|
||||
:::tip[Recommended]
|
||||
Create `project-context.md` to ensure AI agents follow your project's rules and preferences. This file works like a constitution for your project — it guides implementation decisions across all workflows. This optional file can be generated at the end of Architecture Creation, or in an existing project it can be generated also to capture whats important to keep aligned with current conventions.
|
||||
Create `project-context.md` to ensure AI agents follow your project's rules and preferences. This file works like a
|
||||
constitution for your project — it guides implementation decisions across all workflows. This optional file can be
|
||||
generated at the end of Architecture Creation, or in an existing project it can be generated also to capture whats
|
||||
important to keep aligned with current conventions.
|
||||
:::
|
||||
|
||||
**How to create it:**
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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}}"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
Can't render this file because it has a wrong number of fields in line 34.
|
|
|
@ -311,6 +311,16 @@
|
|||
<span class="output">leçons</span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="workflow">
|
||||
<div class="workflow-header">
|
||||
<span class="workflow-name">investigate</span>
|
||||
<span class="badge adhoc">à tout moment</span>
|
||||
</div>
|
||||
<div class="workflow-meta">
|
||||
<div class="agent"><div class="agent-icon amelia">A</div><span class="agent-name">Amelia</span></div>
|
||||
<span class="output">dossier de cas</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -322,6 +322,16 @@
|
|||
<span class="output">lessons</span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="workflow">
|
||||
<div class="workflow-header">
|
||||
<span class="workflow-name">investigate</span>
|
||||
<span class="badge adhoc">anytime</span>
|
||||
</div>
|
||||
<div class="workflow-meta">
|
||||
<div class="agent"><div class="agent-icon amelia">A</div><span class="agent-name">Amelia</span></div>
|
||||
<span class="output">case file</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Reference in New Issue