diff --git a/docs/explanation/forensic-investigation.md b/docs/explanation/forensic-investigation.md
new file mode 100644
index 000000000..7c604824c
--- /dev/null
+++ b/docs/explanation/forensic-investigation.md
@@ -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.
diff --git a/docs/fr/explanation/forensic-investigation.md b/docs/fr/explanation/forensic-investigation.md
new file mode 100644
index 000000000..b1f02138c
--- /dev/null
+++ b/docs/fr/explanation/forensic-investigation.md
@@ -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é.
diff --git a/docs/fr/reference/workflow-map.md b/docs/fr/reference/workflow-map.md
index 1a72e2618..857cde03f 100644
--- a/docs/fr/reference/workflow-map.md
+++ b/docs/fr/reference/workflow-map.md
@@ -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.
@@ -21,14 +31,15 @@ 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 |
|---------------------------------------------------------------------------|------------------------------------------------------------------------------------------|---------------------------|
| `bmad-brainstorming` | Brainstormez des idées de projet avec l’accompagnement guidé d’un coach de brainstorming | `brainstorming-report.md` |
| `bmad-domain-research`, `bmad-market-research`, `bmad-technical-research` | Validez les hypothèses de marché, techniques ou de domaine | Rapport de recherches |
| `bmad-product-brief` | Capturez la vision stratégique — idéal lorsque votre concept est clair | `product-brief.md` |
-| `bmad-prfaq` | Working Backwards — éprouvez et forgez votre concept produit | `prfaq-{project}.md` |
+| `bmad-prfaq` | Working Backwards — éprouvez et forgez votre concept produit | `prfaq-{project}.md` |
## Phase 2 : Planification
@@ -36,60 +47,75 @@ Définissez ce qu'il faut construire et pour qui.
| Workflow | Objectif | Produit |
|-------------------------|---------------------------------------------------------|--------------|
-| `bmad-create-prd` | Définissez les exigences (FRs/NFRs)[^1] | `PRD.md`[^2] |
+| `bmad-create-prd` | Définissez les exigences (FRs/NFRs)[^1] | `PRD.md`[^2] |
| `bmad-create-ux-design` | Concevez l'expérience utilisateur (lorsque l'UX compte) | `ux-spec.md` |
## Phase 3 : Solutioning
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 |
+| 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 |
## Phase 4 : Implémentation
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 |
-| `bmad-code-review` | Validez la qualité de l'implémentation | Approuvé ou changements demandés |
-| `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 |
+| 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 |
+| `bmad-code-review` | Validez la qualité de l'implémentation | Approuvé ou changements demandés |
+| `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 |
-|------------------|-------------------------------------------------------------------------------------|-----------------------|
+| 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.
diff --git a/docs/reference/workflow-map.md b/docs/reference/workflow-map.md
index 0c088fa8b..e84854440 100644
--- a/docs/reference/workflow-map.md
+++ b/docs/reference/workflow-map.md
@@ -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.
@@ -21,30 +30,31 @@ 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` |
-| `bmad-prfaq` | Working Backwards — stress-test and forge your product concept | `prfaq-{project}.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` |
+| `bmad-prfaq` | Working Backwards — stress-test and forge your product concept | `prfaq-{project}.md` |
## Phase 2: Planning
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` |
+| 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` |
## Phase 3: Solutioning
Decide how to build it and break work into stories.
-| Workflow | Purpose | Produces |
-| ----------------------------------------- | ------------------------------------------ | --------------------------- |
+| 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 |
@@ -53,32 +63,38 @@ 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 |
-| `bmad-code-review` | Validate implementation quality | Approved or changes requested |
-| `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 |
+| 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 |
+| `bmad-code-review` | Validate implementation quality | Approved or changes requested |
+| `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 |
+| 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:**
diff --git a/src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-01-init.md b/src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-01-init.md
index 8268e6a97..08ce6b05d 100644
--- a/src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-01-init.md
+++ b/src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-01-init.md
@@ -77,6 +77,7 @@ Discover and load context documents using smart discovery. Documents can be in t
- {planning_artifacts}/**
- {output_folder}/**
- {project_knowledge}/**
+- {implementation_artifacts}/investigations/**
- docs/**
Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content)
@@ -86,6 +87,7 @@ 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/*.md`) — `bmad-investigate` case files when the PRD is being driven by a forensic investigation rather than greenfield ideation. Captures both `*-investigation.md` and `*-archaeology.md`.
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
@@ -120,6 +122,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 +131,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
diff --git a/src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-02-discovery.md b/src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-02-discovery.md
index 3eeb52465..d7ba02a1d 100644
--- a/src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-02-discovery.md
+++ b/src/bmm-skills/2-plan-workflows/bmad-create-prd/steps-c/step-02-discovery.md
@@ -63,6 +63,7 @@ Read the frontmatter from `{outputFile}` to get document counts:
- `briefCount` - Product briefs available
- `researchCount` - Research documents available
- `brainstormingCount` - Brainstorming docs available
+- `investigationCount` - bmad-investigate case files available
- `projectDocsCount` - Existing project documentation
**Announce your understanding:**
@@ -71,6 +72,7 @@ Read the frontmatter from `{outputFile}` to get document counts:
- Product briefs: {{briefCount}}
- Research: {{researchCount}}
- Brainstorming: {{brainstormingCount}}
+- Investigations: {{investigationCount}}
- Project docs: {{projectDocsCount}}
{{if projectDocsCount > 0}}This is a brownfield project - I'll focus on understanding what you want to add or change.{{else}}This is a greenfield project - I'll help you define the full product vision.{{/if}}"
diff --git a/src/bmm-skills/4-implementation/bmad-agent-dev/customize.toml b/src/bmm-skills/4-implementation/bmad-agent-dev/customize.toml
index 62317297c..165878f7a 100644
--- a/src/bmm-skills/4-implementation/bmad-agent-dev/customize.toml
+++ b/src/bmm-skills/4-implementation/bmad-agent-dev/customize.toml
@@ -88,3 +88,8 @@ skill = "bmad-create-story"
code = "ER"
description = "Party mode review of all work completed across an epic"
skill = "bmad-retrospective"
+
+[[agent.menu]]
+code = "IN"
+description = "Forensic case investigation with evidence-graded findings, calibrated to the input"
+skill = "bmad-investigate"
diff --git a/src/bmm-skills/4-implementation/bmad-investigate/SKILL.md b/src/bmm-skills/4-implementation/bmad-investigate/SKILL.md
new file mode 100644
index 000000000..e19e26357
--- /dev/null
+++ b/src/bmm-skills/4-implementation/bmad-investigate/SKILL.md
@@ -0,0 +1,204 @@
+---
+name: bmad-investigate
+description: Forensic case investigation with evidence-graded findings, calibrated to the input. Use when the user asks to investigate a bug, trace what caused an incident, walk through unfamiliar code, or build a mental model of a code area before working on it. Accepts a ticket ID, log file path, diagnostic archive, error message, code area name, problem description, or a path to an existing case file.
+---
+
+**Language:** Use `{communication_language}` for all output.
+
+# Investigate
+
+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.
+
+The skill calibrates how much defect-chasing versus how much area-exploration the input demands, on a continuous scale.
+A vague "how does X work" question leans toward source-reading and mental-model building. A crash log leans toward
+hypothesis tracking, timeline reconstruction, and a fix direction. Most real cases sit somewhere in between, and the
+case-file output reflects whatever balance the evidence required.
+
+The discipline below applies regardless of where on that scale the case lands.
+
+**Args:** Accepts a ticket ID, log file path, diagnostic archive, error message, code area name, problem description, or
+a path to an existing case file.
+
+**Your output:** A structured investigation file at `{implementation_artifacts}/investigations/{slug}-investigation.md`.
+Evidence-cited, hypothesis-tracked, hand-off-ready. Sections that don't apply to a given case can stay empty or be
+omitted; the template covers the union.
+
+## Principles
+
+- **Evidence grading.** Every finding is one of three things and the grade is explicit in the output:
+ - **Confirmed.** Directly observed in logs, code, or dumps. Cited with a specific reference (`path:line`, log
+ timestamp, commit hash).
+ - **Deduced.** Logically follows from confirmed evidence. The reasoning chain is shown.
+ - **Hypothesized.** Plausible but unconfirmed. States what evidence would confirm or refute it.
+- **Stronghold first.** Anchor in one confirmed piece of evidence and expand outward. Never start from a theory and hunt
+ for supporting evidence. When evidence is sparse, say so explicitly and switch to hypothesis-driven exploration with a
+ prioritized data-collection list.
+- **Challenge the premise.** The user's description is a hypothesis, not a fact. Verify technical claims independently.
+ If evidence contradicts the premise, say so directly.
+- **Hypotheses are never deleted.** When evidence confirms or refutes a hypothesis, update its **Status** field
+ (Open / Confirmed / Refuted) and add a **Resolution**. The full reasoning history, including wrong turns, is 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 and update continuously.** The case file is the persistent state that survives session
+ interruptions. Initialize it as soon as the case slug is agreed.
+- **Path:line citations.** Every code reference uses CWD-relative `path:line` format, no leading `/`, so the citation is
+ clickable in IDE-embedded terminals (e.g., `src/auth/middleware.ts:42`).
+
+## Communication Style
+
+- **Clinical precision with detective instinct.** Findings come as a case file: evidence first, deductions second,
+ hypotheses clearly labeled. Never state speculation as fact.
+- **Evidence-first language.** Speak in "the evidence shows", "this is consistent with", "unconfirmed, requires X to
+ verify". When evidence contradicts a working theory, update the theory and say so.
+- **No hedging, no narrative.** Prefer "I don't have enough evidence to conclude X" over vague disclaimers. Do not pad
+ findings with story.
+- **Brief the grading model when presenting the case file.** A first-time reader needs to know what
+ Confirmed / Deduced / Hypothesized mean before they can read the report correctly.
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml`. Resolve `{user_name}`, `{communication_language}`,
+ `{document_output_language}`, `{implementation_artifacts}`, `{project_knowledge}`. If
+ `{project_knowledge}/project-context.md` exists, read it. Acknowledge the case input briefly without committing to a
+ diagnosis.
+
+2. Begin the procedure below. Calibrate as the case unfolds.
+
+## Procedure
+
+`{case_file}` resolves to `{implementation_artifacts}/investigations/{slug}-investigation.md`. `{slug}` is the issue
+tracker ticket ID when one is provided, otherwise a short descriptive name agreed with the user.
+
+The procedure is five outcomes that apply with varying weight depending on the input:
+
+- A symptom-driven case (bug, incident, error) leans into hypothesis tracking, timeline reconstruction, and a fix
+ direction.
+- A no-symptom case (understanding an unfamiliar area) leans into I/O mapping, control-flow filtering, and a mental
+ model.
+- An existing case file is read in full, identified open hypotheses and backlog items are surfaced, and new findings
+ land under a new dated `## Follow-up: {date}` block.
+
+After every outcome, update the case file, present what was learned, and stop for human input before continuing.
+
+### Outcome 1: Scope and stronghold are established
+
+Establish the case from whatever the user provides. Possible inputs:
+
+- **Issue tracker ticket.** Fetch full details via available MCP tools.
+- **Diagnostic archive.** Inventory contents.
+- **Log files or stack traces.** Note the time window covered.
+- **Free-text description.** Capture verbatim. Treat as hypothesis.
+- **Code area name** (no symptom). Identify the entry point.
+- **Recent commit area** to scan for likely culprits.
+
+If the user arrives with a hypothesis, register it as Hypothesis #1 and target evidence collection at confirming or
+refuting it, while still scanning broadly for the unexpected.
+
+Find a stronghold: a confirmed piece of evidence (an error message, a function name, an HTTP route, a configuration
+parameter, a test case). Anchor the case here.
+
+Initialize `{case_file}` from `case-file-template.md`. Fill in: Case Info, Problem Statement, initial Evidence
+Inventory.
+
+Present scope, stronghold, file path, proposed approach. Halt.
+
+### Outcome 2: Evidence perimeter is mapped
+
+Map all available evidence before analyzing.
+
+- **Diagnostic archives.** Log files, crash dumps, configuration snapshots, system info.
+- **Issue tracker.** Description, comments, linked issues, attachments.
+- **Version control history.** Recent changes in the affected area.
+- **Test results.** Existing test coverage, recent regressions.
+- **Static analysis.** Known defects.
+- **Source code.** The codebase as reference material.
+
+Classify each as Available, Partial, or Missing. Missing evidence is itself a finding.
+
+Update Evidence Inventory and Investigation Backlog. Present the inventory and any data gaps. Halt.
+
+### Outcome 3: Cause is reasoned about with discipline
+
+Apply the methodology systematically. Let the evidence guide where to dig.
+
+- **Establish a beachhead.** Find the first confirmed piece of evidence. Anchor here.
+- **Trace causality.** Symptom-driven: trace backward from the symptom (what produced this error? what condition
+ triggers this code path? what state would cause that condition? when did that state emerge?). Exploration: trace
+ backward from outputs (return statements, side effects, messages sent) to producing conditions. Same technique,
+ different anchor.
+- **Reconstruct the timeline.** Cross-reference timestamps across application logs, system events, version control
+ history, user-reported observations.
+- **Form and test hypotheses.** For each: state it, identify confirming evidence, identify refuting evidence, search,
+ and grade the outcome (Confirmed / Refuted / remains Open). Update Status. Never delete a hypothesis.
+- **Verify the user's premise.** Verify technical claims independently. If evidence contradicts, say so explicitly.
+- **Add discovered paths to the backlog.** Stay focused on the current thread.
+
+Update Confirmed Findings (with citations), Deduced Conclusions, Hypothesized Paths, Investigation Backlog, Timeline.
+
+Present key findings, active hypotheses, updated backlog. Highlight anything that contradicts the original premise.
+Recommend the next action with rationale. Halt.
+
+### Outcome 4: Source has been traced where it matters
+
+Once the procedure points at specific behaviors or an area, trace into the source.
+
+- Grep for exact error strings to find the originating function.
+- Read the surrounding code to understand the triggering condition.
+- Check for parallel implementations in different directories.
+- Follow the caller chain to understand the execution context.
+- Check version control history for recent changes.
+- Watch for language and process boundary crossings (compiled code calling scripts, IPC, host-to-device, configuration
+ flow). Boundaries hide bugs because each side assumes the other behaved as documented.
+
+For exploration cases, lean heavier into:
+
+- **I/O mapping.** Triggers, outputs, external dependencies of the area.
+- **Frequent-terms scan.** Recurring objects, variables, identifiers.
+- **Control-flow filtering.** Skeleton: branching, loops, error handling, state-machine transitions. Bugs hide in the
+ structure, not the syntax.
+
+For symptom-driven cases, lean heavier into:
+
+- **Depth assessment.** After the narrow trace, decide whether the root cause is reachable from local context or
+ whether a broader area model is required. Surface the decision when escalating. Never silently expand scope.
+- **Trivial-fix assessment.** If the fix is obviously trivial (off-by-one, missing null check, swapped argument), note
+ the direction in the report. For anything non-trivial, stop at identifying the root cause area. Investigation stops
+ at the diagnosis; implementation is a separate concern handled outside this skill.
+
+Update Source Code Trace section (Error origin, Trigger, Condition, Related files; plus area model when broader
+exploration was applied).
+
+Present the trace findings. Recommend the next step. Halt.
+
+### Outcome 5: Report is finalized and the hand-off is clean
+
+Update `{case_file}` with:
+
+- Final Conclusion with confidence level (High / Medium / Low).
+- Fix direction (when applicable; categorize by mechanism when multiple issues combine).
+- Diagnostic steps to confirm the root cause if any uncertainty remains.
+- Reproduction Plan (when applicable; setup, trigger, expected results) or a verification plan for exploration cases
+ (small set of operations or tests that would confirm the mental model).
+- Status: Active, Concluded, or Blocked on evidence.
+
+Present the conclusion summary. Recommend the highest-value next action with specifics. Halt.
+
+## Follow-up Iterations
+
+When the user chooses to continue, execute the requested action and update `{case_file}` with new findings. When
+extending an existing case across sessions, append findings under a new or current `## Follow-up: {date}` block to
+preserve the original reasoning.
+
+The investigation is complete when:
+
+- A root cause is Confirmed with evidence.
+- The most likely root cause is Hypothesized with a clear data gap.
+- The mental model is sufficient for the user's stated goal (exploration cases).
+- The backlog contains only items requiring evidence not currently available.
+- The user explicitly concludes.
+
+## Case File Structure
+
+The output file uses the structure defined in `case-file-template.md`. Initialize it once at the start of the case from
+that template, then update sections as evidence accumulates.
diff --git a/src/bmm-skills/4-implementation/bmad-investigate/case-file-template.md b/src/bmm-skills/4-implementation/bmad-investigate/case-file-template.md
new file mode 100644
index 000000000..ae757a24d
--- /dev/null
+++ b/src/bmm-skills/4-implementation/bmad-investigate/case-file-template.md
@@ -0,0 +1,164 @@
+# Case File Template
+
+The output file uses the structure below. Initialize it once at the start of the case, then update sections as evidence
+accumulates. Never delete a hypothesis. Update its Status and add a Resolution. Append follow-up sessions under dated
+`## Follow-up: {date}` blocks instead of overwriting earlier reasoning.
+
+---
+
+```markdown
+# Investigation: {title}
+
+## Case Info
+
+| Field | Value |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| Ticket | {ticket-id or "N/A"} |
+| Date opened | {date} |
+| Status | Active |
+| System | {system description, OS, version, relevant environment details} |
+| Evidence sources | {diagnostic archive, logs, crash dump, code, version control history, etc.} |
+
+## Problem Statement
+
+{User-reported problem description. This is the initial claim. It may be refined or contradicted by evidence during the
+investigation.}
+
+## Evidence Grading Legend
+
+- **Confirmed.** Directly observed in logs, code, or dumps. Cited with specific evidence.
+- **Deduced.** Logically follows from confirmed evidence. Reasoning chain shown.
+- **Hypothesized.** Plausible but unconfirmed. States what evidence would confirm or refute.
+
+## Evidence Inventory
+
+| Source | Status | Notes |
+| -------- | ------------------------------- | --------- |
+| {source} | {Available / Partial / Missing} | {details} |
+
+## Investigation Backlog
+
+Paths to explore, ordered by priority. Updated throughout the investigation.
+
+| # | Path to Explore | Priority | Status | Notes |
+| - | --------------- | --------------------- | ------------------------------------------ | --------- |
+| 1 | {description} | {High / Medium / Low} | {Open / In Progress / Done / Blocked} | {context} |
+
+## Timeline of Events
+
+Chronological reconstruction from multiple evidence sources. Each entry cites its source.
+
+| Time | Event | Source | Confidence |
+| ----------- | ------------------- | ---------------------- | ----------------------- |
+| {timestamp} | {event description} | {log file, commit, …} | {Confirmed / Deduced} |
+
+## Confirmed Findings
+
+Directly observed in logs, code, or dumps. Each finding includes a citation: `path:line`, log timestamp, commit hash.
+
+### Finding 1: {title}
+
+**Evidence:** {citation}
+
+**Detail:** {description}
+
+## Deduced Conclusions
+
+Logically follows from confirmed findings. Each deduction shows the reasoning chain from confirmed evidence to
+conclusion.
+
+### Deduction 1: {title}
+
+**Based on:** {which confirmed findings}
+
+**Reasoning:** {logical chain}
+
+**Conclusion:** {what follows}
+
+## Hypothesized Paths
+
+All hypotheses ever formed during the investigation. Hypotheses are NEVER removed. Only their Status is updated. This
+preserves the full reasoning history.
+
+### Hypothesis 1: {title}
+
+**Status:** {Open / Confirmed / Refuted}
+
+**Theory:** {description}
+
+**Supporting indicators:** {what makes this plausible}
+
+**Would confirm:** {specific evidence that would prove this}
+
+**Would refute:** {specific evidence that would disprove this}
+
+**Resolution:** {when status changes from Open, explain what evidence settled it}
+
+## Missing Evidence
+
+Data gaps identified during investigation. Each gap describes what is missing and what it would resolve if available.
+
+| Gap | Impact | How to Obtain |
+| -------------- | ------------------------------------- | -------------- |
+| {what's missing} | {what it would confirm or eliminate} | {how to get it} |
+
+## Source Code Trace
+
+If source code was traced during the investigation.
+
+| Element | Detail |
+| ------------- | -------------------------------------------- |
+| Error origin | {file:line, function name} |
+| Trigger | {what causes this code to execute} |
+| Condition | {what state produces the observed behavior} |
+| Related files | {other files in the same code path} |
+
+## Conclusion
+
+**Confidence:** {High / Medium / Low}
+
+{Summary of what happened based on the evidence. Clearly states what is Confirmed versus what remains Hypothesized. If
+the root cause is identified, states it. If not, states the most promising hypothesized paths and what would resolve the
+remaining uncertainty.}
+
+## Recommended Next Steps
+
+### Fix direction
+
+{High-level description of what needs to change and why. Categorize by mechanism when multiple issues combine to produce
+the bug.}
+
+### Diagnostic
+
+{Steps to confirm the root cause. Additional logging, targeted tests, data to collect.}
+
+## Reproduction Plan
+
+{How to reproduce the issue in a controlled environment. Include setup, trigger, and expected results. Scale from
+isolated proof to full system reproduction when applicable.}
+
+## Follow-up: {date}
+
+Append a new dated block when new findings extend an existing case across sessions. One block per session. Never
+overwrite earlier blocks.
+
+### New Evidence
+
+{What new data was provided or discovered.}
+
+### Additional Findings
+
+{New Confirmed findings, Deductions, or Hypotheses, with grading.}
+
+### Updated Hypotheses
+
+{Which hypotheses were Confirmed, Refuted, or refined.}
+
+### Backlog Changes
+
+{Items completed, items added, reprioritization.}
+
+### Updated Conclusion
+
+{Revised assessment incorporating new evidence.}
+```
diff --git a/src/bmm-skills/module-help.csv b/src/bmm-skills/module-help.csv
index 8b824795f..1667c4bc3 100644
--- a/src/bmm-skills/module-help.csv
+++ b/src/bmm-skills/module-help.csv
@@ -31,3 +31,4 @@ BMad Method,bmad-code-review,Code Review,CR,Story cycle: If issues back to DS if
BMad Method,bmad-checkpoint-preview,Checkpoint,CK,Guided walkthrough of a change from purpose and context into details. Use for human review of commits branches or PRs.,,4-implementation,,,false,,
BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,4-implementation,bmad-dev-story,,false,implementation_artifacts,test suite
BMad Method,bmad-retrospective,Retrospective,ER,Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC.,,4-implementation,bmad-code-review,,false,implementation_artifacts,retrospective
+BMad Method,bmad-investigate,Investigate,IN,Forensic case investigation calibrated to the input. Evidence-graded analysis with hypothesis tracking. Produces a structured case file.,,4-implementation,,,false,implementation_artifacts,investigation report
diff --git a/website/public/workflow-map-diagram-fr.html b/website/public/workflow-map-diagram-fr.html
index 1fde3c038..116ad8809 100644
--- a/website/public/workflow-map-diagram-fr.html
+++ b/website/public/workflow-map-diagram-fr.html
@@ -311,6 +311,16 @@
leçons
+
diff --git a/website/public/workflow-map-diagram.html b/website/public/workflow-map-diagram.html
index 0a17cc2eb..42897aad7 100644
--- a/website/public/workflow-map-diagram.html
+++ b/website/public/workflow-map-diagram.html
@@ -322,6 +322,16 @@
lessons
+