wdi-method 0.6.0 → 0.6.1

package/README.md

@@ -282,7 +282,7 @@ which review lenses run, and which review traces a validator will demand.
 
 ---
 
-## Five gates, sixteen skills
+## Five gates, seventeen skills
 
 | Gate | Decides | Skill |
 |---|---|---|
@@ -293,7 +293,7 @@ which review lenses run, and which review traces a validator will demand.
 | **G5 Release** | Whether it is done and proven | `wdi-build` |
 
 Around them: `wdi-init` (scaffold, component birth, depth and risk settings, structure maps),
-`wdi-decision`, `wdi-question`, `wdi-log`, `wdi-help`, `wdi-reconcile`, `wdi-review`, `wdi-report`,
+`wdi-decision`, `wdi-question`, `wdi-log`, `wdi-help`, `wdi-explain-to-me`, `wdi-reconcile`, `wdi-review`, `wdi-report`,
 `wdi-systematic-debugging`, and `wdi-upgrade` (moves a corpus written under an older kit into the current
 shape — content moves, nothing is invented).
 
@@ -382,9 +382,9 @@ English, whatever the settings say — it travels to every repo through this pac
 
 | | |
 |---|---|
-| Overwrites | everything in `.constitution/method/` · the sixteen wrappers · `_bmad/custom/*.toml` · the marked block in `AGENTS.md` |
+| Overwrites | everything in `.constitution/method/` · the seventeen wrappers · `_bmad/custom/*.toml` · the marked block in `AGENTS.md` |
 | Renames | a file whose content needs no judgment to move — `waves.yaml` → `specs.yaml`, the pre-0.5 registry names. Content is never rewritten |
-| Removes | Wrappers the method has retired — a `wdi-*` folder with a `SKILL.md` that is no longer one of the sixteen. Each removal is printed |
+| Removes | Wrappers the method has retired — a `wdi-*` folder with a `SKILL.md` that is no longer one of the seventeen. Each removal is printed |
 | Reports | what is still in the OLD shape, as an `upgrade` line — and names `wdi-upgrade` as the next step. The installer does not move content; that is a decision, and the skill's |
 | Keeps | All of `.constitution/project/`, plus your initiative slug and your language choice. A setting somebody already chose is not the installer's to change behind their back |
 | Never resurrects | A folder you retired. On update, absence is treated as a decision |

package/bin/wdi-method.js

@@ -48,6 +48,7 @@ const WDI_SKILLS = [
   "wdi-question",
   "wdi-log",
   "wdi-help",
+  "wdi-explain-to-me",
   "wdi-reconcile",
   "wdi-review",
   "wdi-report",

package/kit/.constitution/method/README.md

@@ -29,7 +29,7 @@ Never a rule. When it disagrees with a guide, the guide wins and the disagreemen
 
 | File | Opened when |
 |---|---|
-| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, sixteen skills, WDI ↔ BMad |
+| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, seventeen skills, WDI ↔ BMad |
 | [`why/artifact-map.md`](why/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
 | [`why/mode-risk-map.md`](why/mode-risk-map.md) | A `mode` and a `risk_accepted` are set and you want the two side by side — all twelve cells |
 | [`why/rationale.md`](why/rationale.md) | Before changing a rule, to know what you would break |

package/kit/.constitution/method/method-glossary.md

@@ -137,7 +137,7 @@ where BMad's own meaning is wider, the narrower one here wins.
 | `epics.md` · `sprint-status.yaml` · `bmad-sprint-planning` · `bmad-create-epics-and-stories` · `stories.yaml` | Tickets, each carrying its own status and its blocking edges |
 | Validator `V10` | Nothing. Its number is not reused |
 | `bmad-help` as the answer to "where am I" | `wdi-help` |
-| The skills `wdi-analysis` · `wdi-architecture` · `wdi-design` · `wdi-glossary` · `wdi-structure` · `wdi-apply` · `wdi-correct-course` · `wdi-wave` · `wdi-ship-story` · `wdi-product-brief` · `wdi-meeting` · `wdi-project-log` | The fifteen in `why/README.md`. `why/rationale.md` says which absorbed which, and why |
+| The skills `wdi-analysis` · `wdi-architecture` · `wdi-design` · `wdi-glossary` · `wdi-structure` · `wdi-apply` · `wdi-correct-course` · `wdi-wave` · `wdi-ship-story` · `wdi-product-brief` · `wdi-meeting` · `wdi-project-log` | The seventeen in `why/README.md`. `why/rationale.md` says which absorbed which, and why |
 | An Indonesian synonym for a `mode` value — *ringkas*, *terjaga*, *katalog* as prose | The English value, used as written: `catalog` · `outline` · `guarded` · `deep` |
 
 ## Synonyms that MUST NOT be coined

package/kit/.constitution/method/why/README.md

@@ -101,7 +101,7 @@ and the Fast Path do not.
 | `wdi-method update` printed an `upgrade` line | `wdi-upgrade`, before any other skill — it moves content into the new shape, never invents it, one commit |
 | You do not know where you are | `wdi-help` |
 
-## Sixteen skills
+## Seventeen skills
 
 Named for the **gate they serve**, so *"which skill do I run"* is answered by *"which gate am I at"*.
 
@@ -125,6 +125,7 @@ Named for the **gate they serve**, so *"which skill do I run"* is answered by *"
 | `wdi-question` | Something that cannot be decided now |
 | `wdi-log` | A meeting finished, or a non-technical fact now binds |
 | `wdi-help` | "Where am I, what next" |
+| `wdi-explain-to-me` | "Brief me so I can decide this" — an open question, a defect, a design fork. Reads everything, writes nothing; the decision then goes to `wdi-decision` or `wdi-question` |
 | `wdi-upgrade` | `wdi-method update` just moved the method version, and the summary listed content still in the old shape. Moves it, never invents it; one commit |
 | `wdi-reconcile` | Any time. Read-only — it reports, it never edits |
 | `wdi-review` | Over any document, any time |

package/kit/.constitution/method/why/artifact-map.md

@@ -124,7 +124,7 @@ someone else performs. `../document/corpus-guide.md` holds the binding version o
 | `wdi-report` | `.control/reports/<period>.md` |
 | a script | everything in `.control/generated/`, and the three inventories once code exists |
 
-Four skills write **no file at all**, and that is deliberate: `wdi-reconcile`, `wdi-help`,
+Five skills write **no file at all**, and that is deliberate: `wdi-reconcile`, `wdi-help`, `wdi-explain-to-me`,
 `wdi-report` intent `dispatch`, and `wdi-review` apart from one frontmatter block. What reports MUST NOT
 also change things — otherwise there is nothing left to check with.
 

package/kit/.constitution/method/why/portability.md

@@ -28,7 +28,7 @@ them only an *example* does — not a rule.
 | `templates/design-system.md` | The pointer to wherever this project keeps its tokens | Re-point at that project's token file |
 | `templates/oq.md` | One example of a bad question title | Cosmetic |
 
-Everything else — the five gates, the two fields, the sixteen skills, the templates, `validate.py`,
+Everything else — the five gates, the two fields, the seventeen skills, the templates, `validate.py`,
 `inventory.py`, `../method-glossary.md`, and the three files beside this one — carries without edit.
 
 One half-exception, and it is by design: `inventory.py` is the generic engine and carries whole, but

package/kit/skills/wdi-explain-to-me/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: wdi-explain-to-me
+description: Use when the owner has to decide something — an open question, a defect, a design fork, a failing validator, a vague worry — and wants the reading done for them. Investigates, then briefs in six fixed sections, in the owner's language. Writes no file; the decision itself goes to wdi-decision or wdi-question.
+disable-model-invocation: true
+---
+
+# WDI Explain To Me
+
+The owner names a problem. The result is a **decision briefing**: everything needed to decide, with the
+agent doing all of the reading and the owner doing only the deciding.
+
+`disable-model-invocation: true` is deliberate. A briefing is written for a person who has to choose;
+a skill that wants one has nothing to choose, and would only be reading its own summary back.
+
+Four asks look alike from the outside and are four skills:
+
+| Ask | Skill |
+|---|---|
+| "Where am I, what next" | `wdi-help` — position and routing, under fifteen lines |
+| "Brief me so I can decide this" | **this skill** — investigation, then a briefing |
+| "Record what was decided" | `wdi-decision` |
+| "This cannot be decided now" | `wdi-question` |
+
+## Inputs
+
+| Source | What it answers |
+|---|---|
+| The topic argument | An id (`OQ-12`, `DEC-007`, a defect row, a validator name), a file path, or a sentence |
+| `.control/registry/*.yaml` · `.control/generated/status` | What the registry says holds today, and which validators are red |
+| `.control/questions/` · `.control/decisions/` | Whether this was asked or decided before, and what is already settled |
+| The working documents in `.what/` and `.how/` | The promise and the mechanism the topic touches |
+| `validate.py` output · tests · git history · the code | What actually holds, as opposed to what a document claims |
+
+## Step 1 — Investigate
+
+When the topic is too vague to investigate, ask **one** narrowing question first — one, not a list. A
+briefing on the wrong topic wastes the owner's five minutes.
+
+Then read the sources that bear on the topic before writing a word: files, registries, validator or test
+output, git history. Run what can be run. Done when every claim the briefing will make traces to
+something read or executed in this session, with its `file:line` in hand.
+
+## Step 2 — Brief
+
+**Language.** Write in the language the owner is using in the conversation. When that is unclear, use
+`policy.doc_language` from `.control/registry/index.yaml`. Method terminology — ids, gate names, the
+values of `mode` and `risk_accepted`, validator names — stays English as `language-guide.md` requires;
+those are keys, not prose.
+
+**Six sections, fixed in number, order, and meaning.** The headings are given here in English; render
+each one in the briefing's language and keep its slot. A briefing that drops, merges, or reorders a
+section has changed what the owner can compare it against.
+
+1. **Topic** — what kind of thing this is (an `OQ-`? a defect? a design fork? stale prose?) and the one
+   decision it asks for. Two or three sentences.
+2. **Background** — how it came to exist and what is already settled. Plain language; gloss any term of
+   art in half a sentence where it first appears.
+3. **Problem Analysis** — what is actually wrong and why, with evidence. Put a `file:line` citation
+   beside each claim; the reader MAY verify, but MUST NOT need to.
+4. **Solution Design** — 2–4 options. For each: what changes, what it costs, what breaks or is lost, and
+   the size of the work. An option whose downside is missing has not been analysed.
+5. **Recommendation** — exactly one, with its reason and the single condition that would flip it.
+6. **What Helps You Decide** — the facts worth weighing against each other, then a verdict on the
+   owner's own eyes: either state that this briefing is sufficient, or name the exact file, section, or
+   screen the owner MUST look at themselves and what to look for there. Reserve that second verdict for
+   judgement only the owner can make — taste, risk appetite, a promise to a stakeholder — never for
+   legwork the investigation could have done.
+
+Done when the owner could decide from the briefing alone, or knows exactly what to open and why.
+
+## Rules
+
+- Reading time MUST stay under five minutes; push detail into citations, not prose.
+- A claim without a source read this session MUST NOT appear in the briefing. Memory is not a source.
+- This skill writes **no file** and MUST NOT edit anything. The briefing lives in the conversation. It
+  MUST NOT open a `DEC-`, file an `OQ-`, or patch the corpus on the way — a briefing that also changes
+  things leaves nothing to decide against.
+- You MUST NOT run other skills on the owner's behalf. Name the skill; let them invoke it.
+
+## Output
+
+The six sections, then one line naming where the decision goes once it is made: `wdi-decision` intent
+`open` when it is worth remembering, the owning document directly when it is not, or `wdi-question`
+when it turns out it cannot be decided yet.

package/kit/skills/wdi-help/SKILL.md

@@ -64,6 +64,7 @@ mis-route in this flow, because every other gate is the same for every component
 | Depth done and G4 passed for every component the work touches | `wdi-build` — it opens the spec, has the owner run `to-spec` and `to-tickets`, ships each ticket, closes the spec |
 | A small fix touching no `FR`, `UC`, `AD-N`, or domain model | Fast Path: the owner runs `/implement` directly. It stops and becomes a spec `S` the moment an `FR` is touched |
 | A planning assumption turned out void | `wdi-decision` intent `open` — it proposes, and changes nothing |
+| The owner has to decide something and wants the reading done first | `wdi-explain-to-me` — it briefs, and changes nothing; the decision then goes to `wdi-decision` or `wdi-question` |
 | An accepted `DEC-` has not reached its documents | `wdi-decision` intent `apply` |
 | A bug, a failing test, unexpected behaviour | `wdi-systematic-debugging`, before any fix is proposed |
 | Numbers are wanted before the work is committed | `wdi-report` intent `estimate` |

package/kit-overlay/AGENTS.md

@@ -112,7 +112,7 @@ derived from the other: one component MAY be thin on purpose and reviewed the ha
 `.constitution/method/document/delivery-flow-guide.md` owns both;
 `.constitution/method/why/rationale.md` says why they are separate.
 
-## The five gates and the sixteen skills
+## The five gates and the seventeen skills
 
 | Gate | Decides | Skill |
 |---|---|---|
@@ -125,7 +125,7 @@ derived from the other: one component MAY be thin on purpose and reviewed the ha
 Before G1 and at the tail of G2: `wdi-init`, five intents — `setup` · `component` · `mode` · `risk` ·
 `structure`.
 
-Any time: `wdi-decision` · `wdi-question` · `wdi-log` · `wdi-help` · `wdi-reconcile` · `wdi-review` ·
+Any time: `wdi-decision` · `wdi-question` · `wdi-log` · `wdi-help` · `wdi-explain-to-me` · `wdi-reconcile` · `wdi-review` ·
 `wdi-report` · `wdi-systematic-debugging`.
 
 **No BMad skill is invoked directly.** Each has a wrapper, and the wrapper is what checks position,
@@ -166,6 +166,7 @@ verifies the result, and lands the memlog.
 | Looking for a non-technical fact — a domain, an account, a legal entity, a locked date | `.control/project-non-technical-log.md` |
 | Naming anything — a code identifier, a file, a database column | `.constitution/method/language-guide.md` |
 | Asking "which gate now, what next" | `.constitution/method/document/delivery-flow-guide.md` · skill `wdi-help` |
+| Having to decide something, and wanting the reading done first | skill `wdi-explain-to-me` — it briefs, and changes nothing |
 | Setting or changing `mode` or `risk_accepted` | `.constitution/method/document/delivery-flow-guide.md` · skill `wdi-init` |
 | Invoking a BMad skill | `.constitution/method/document/bmad-guide.md` · `.constitution/method/document/bmad-skill-register.md` |
 | Writing or reviewing a product brief | `.constitution/method/document/brief-guide.md` |

package/kit-overlay/README.md

@@ -29,7 +29,7 @@ Never a rule. When it disagrees with a guide, the guide wins and the disagreemen
 
 | File | Opened when |
 |---|---|
-| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, sixteen skills, WDI ↔ BMad |
+| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, seventeen skills, WDI ↔ BMad |
 | [`why/artifact-map.md`](why/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
 | [`why/mode-risk-map.md`](why/mode-risk-map.md) | A `mode` and a `risk_accepted` are set and you want the two side by side — all twelve cells |
 | [`why/rationale.md`](why/rationale.md) | Before changing a rule, to know what you would break |

package/kit-overlay/portability.md

@@ -28,7 +28,7 @@ them only an *example* does — not a rule.
 | `templates/design-system.md` | The pointer to wherever this project keeps its tokens | Re-point at that project's token file |
 | `templates/oq.md` | One example of a bad question title | Cosmetic |
 
-Everything else — the five gates, the two fields, the sixteen skills, the templates, `validate.py`,
+Everything else — the five gates, the two fields, the seventeen skills, the templates, `validate.py`,
 `inventory.py`, `../method-glossary.md`, and the three files beside this one — carries without edit.
 
 One half-exception, and it is by design: `inventory.py` is the generic engine and carries whole, but

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdi-method",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "WDI Method — software delivery method that wraps BMad",
   "type": "module",
   "bin": {