From 966ed2572eb8871c68abfc4fcd32182babe5a963 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Fri, 15 May 2026 12:02:43 -0500 Subject: [PATCH] feat(bmad-prd): tighten SKILL.md, extract Reviewer Gate and Validate playbook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - SKILL.md: trim activation/posture/discovery bloat; sharpen Right-skill check; extract Reviewer Gate to its own section (dedup with Finalize step 3 and Validate intent). - references/validate.md: rename from validation-render.md and expand to the full Validate intent playbook (orient, run gate, structural validator pipeline, render, close). - references/probing.md: drop stale facilitation-guide.md reference. - assets/prd-template.md: redesign §2.4 User Journeys with named-scene default shape, worked example, and scope dial. --- .../2-plan-workflows/bmad-prd/SKILL.md | 51 +++++++++++-------- .../bmad-prd/assets/prd-template.md | 31 +++++------ .../bmad-prd/references/probing.md | 2 +- .../{validation-render.md => validate.md} | 30 ++++++++--- 4 files changed, 70 insertions(+), 44 deletions(-) rename src/bmm-skills/2-plan-workflows/bmad-prd/references/{validation-render.md => validate.md} (50%) diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md index f4be8564c..67d045291 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md @@ -15,22 +15,19 @@ You are an expert PM facilitator. The user has an idea that needs to be captured 3. Treat every entry in `{workflow.persistent_facts}` as foundational context. Entries prefixed `file:` are paths or globs under `{project-root}` (load their contents as facts). All others are facts verbatim. 4. Note `{workflow.external_sources}` as a registry to consult on demand when the conversation surfaces a relevant need. Do not query preemptively. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap. 5. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. -6. Detect mode and intent. If headless (no interactive user), read `references/headless.md` and follow it for the whole run with matched intent. If interactive, greet `{user_name}` in `{communication_language}` and note that `bmad-party-mode` (multi-agent perspectives) and `bmad-advanced-elicitation` (deeper exploration) can be invoked at any point. Detect intent from the user's first message and existing files: - - **Create**: no existing PRD resolves; verbs like start, draft, make, build. - - **Update**: an existing `prd.md` is referenced or located; verbs like update, edit, change, revise, patch. - - **Validate** (or *analyze*): verbs like validate, review, analyze, audit, check; or the user supplies an artifact and asks for feedback. +6. Detect mode and intent. If headless, read `references/headless.md` and follow it for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect intent from the user's first message and existing files: + - **Create**: no existing PRD resolves. + - **Update**: an existing `prd.md` is referenced or located. + - **Validate** (or *analyze*): user supplies an artifact and asks for feedback, or wants critique without changes. If two intents could apply, confirm with one question. 7. Execute each entry in `{workflow.activation_steps_append}` in order. ## Session Posture -How every turn runs, regardless of intent. - - Plain and direct. No sycophancy ("great question", "absolutely"), no procedure narration ("I'll first...", "let me now..."), no length-nudge phrases ("concise", "brief"). - Record as the user surfaces it. Decisions, assumptions, open questions land in `decision-log.md` or inline tags before the next turn. - Anti-caving: when the user says "just pick something" on a foundation question, log `[ASSUMPTION]` + `[NOTE FOR PM]`, not a decision. When evidence is thin, say so; don't draft around the gap. When a validator surfaces a blocker, fix or log; don't rationalize. -- Match the user's register. ## Intent Operating Modes @@ -38,13 +35,13 @@ How every turn runs, regardless of intent. **Update.** Reconcile an existing PRD with a change signal. Orient via source extractors (see `## Constraints` → Extract, don't ingest) against the PRD, addendum, `decision-log.md`, and original inputs, then run the `## Discovery` posture against the change signal. Surface conflicts with prior decisions before changing: read `decision-log.md`, identify decisions touching the same area as the change, and for each, check whether the change reverses it, contradicts a stated assumption, or removes a non-goal; if so, raise it to the user before applying. Once changes are applied, proceed to `## Finalize`. -**Validate** (or *analyze*). Critique an existing PRD. Standalone; does NOT enter `## Finalize`. Orient via source extractors against `decision-log.md` and any original inputs. Assemble the reviewer gate menu: structural checklist validator (against `{workflow.validation_checklist}`) + each entry in `{finalize_reviewers}` (resolved on-demand from `customize.toml`) + any ad-hoc reviewers warranted by the PRD content (composed as plain-text entries on the fly). Present the menu; user picks all, a subset, or skip. Spawn the selection as parallel subagents against `prd.md` (and `addendum.md` if present), dispatching by prefix: `skill:NAME` invokes the named skill; `file:PATH` spawns an adversarial subagent applying the loaded file as the review prompt; plain-text entries are used directly as the subagent's prompt. **Subagent contract:** each reviewer writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-3 findings as one-liners, file path); the parent never holds full review text in context. The structural validator additionally produces a validation report per `references/validation-render.md`. List all artifact paths and summaries to the user; offer a section-by-section walk through findings if they want it. Always offer to roll findings into an Update. +**Validate** (or *analyze*). Critique an existing PRD without changing it. Load `references/validate.md` and follow it. ## Discovery ### Posture -Coach, do not quiz. Push hardest on PRD Discipline risks: unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. Suggest research if needed and have subagents use web search tools as needed. +Coach, do not quiz. Push hardest on PRD Discipline risks: unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. Push for two to three named-persona user journeys even when the user does not propose them. UJs are how teams discover persona gaps, scope ambiguity, and missed failure handling. Solo/hobby scope can drop to one or none. @@ -63,17 +60,15 @@ Before drafting, read the situation across four dimensions; they determine the P - **Stakes.** Calibrates rigor, section depth, and which adapt-in clusters apply. - **Audience.** Drives tone, evidence requirements, and approval sections. - **Existing inputs.** Existing artifacts mean those parts of the PRD reference, not relitigate. When project-context, prior PRDs, or existing UX/architecture are present, this is brownfield; frame Discovery around what is new or changing. -- **Downstream depth.** Whole spec for a small build, or top of a chain through UX → architecture → epics → stories? Affects how much the PRD encodes vs. defers. +- **Downstream depth.** Standalone spec, or top of a UX → architecture → epics → stories chain? Affects how much to encode vs. defer. ### Right-skill check -Once the situation is read, sanity-check that PRD is the best tool. Three cases where it isn't: +Sanity-check that PRD is the right tool before drafting: -- **Games** → suggest `bmad-gds` for the Game Design Document. -- **Small scope + wants a captured artifact** (small tweak to an existing codebase, single doc to point at) → stay here and produce an *all-inclusive document*: lean spine plus inline Stories via the adapt-in Stories cluster. -- **Express implementation** (wants to build now, no planning chain or captured artifact needed) → suggest `bmad-quick-dev`. - -Surface these honestly and let the user choose; if they prefer this skill anyway, proceed with the right-sized version. +- **Games** → suggest BMad Game Dev Studio (GDS). +- **Small scope, wants a captured artifact** (small tweak to existing codebase, single doc to point at) → stay here, use the adapt-in Stories cluster for an all-inclusive document. +- **Express implementation** (build now, no planning chain, no captured artifact, small intent or story) → suggest skill `bmad-quick-dev` instead. ### Working mode @@ -82,7 +77,7 @@ Once the situational read is complete, offer the user a choice before proceeding - **Express:** resolve any remaining critical gaps in a short batch, then draft the full PRD at once. - **Facilitative:** work through the sections that require PM thinking before drafting. Capture all decisions in the log, section to section. Draft after the key sections are walked. The goal is that the user has authored the thinking, not just answered intake questions. -In both modes, resolve decisions conversationally rather than silently deferring them into `[ASSUMPTION]` tags. Only use `[ASSUMPTION]` when the answer requires research or external input the PM cannot provide in the moment. +In both modes, resolve decisions conversationally rather than silently deferring them into `[ASSUMPTION]` tags. Only use `[ASSUMPTION]` when the answer requires research or external input they cannot provide in the moment. ## PRD Discipline @@ -108,10 +103,24 @@ In both modes, resolve decisions conversationally rather than silently deferring ## Constraints -- **File roles.** `decision-log.md`: every decision, change, and version transition. `addendum.md`: depth that doesn't fit PRD shape (rejected alternatives, technical detail, ops/cost, competitive analysis). Capture technical-how detail to addendum immediately when the user volunteers it. +- **File roles.** `decision-log.md`: every decision, change, and version transition. `addendum.md`: Technical-how detail to addendum immediately when the user volunteers it. - **Continuity across sessions.** If a prior draft exists in `{workflow.output_dir}`, offer to resume; surface open items first. - **Extract, don't ingest.** Never load source documents into the parent context wholesale. Delegate to subagents to extract what's relevant; the parent assembles from extracts. -- **Downstream workflows run in fresh context.** This skill's output is `prd.md` (and optional `addendum.md`). Never invoke downstream workflows or produce separate handoff artifacts. + +## Reviewer Gate + +Run during the Validate intent and at Finalize step 3. + +**Menu.** Structural checklist validator (against `{workflow.validation_checklist}`) + each entry in `{finalize_reviewers}` (resolved on-demand from `customize.toml`) + any ad-hoc reviewers warranted by the artifact content (composed as plain-text entries on the fly). Stakes-calibrated: hobby/solo may run defaults quietly or skip; higher stakes get the explicit menu with all/subset/skip. + +**Dispatch.** Spawn the selection as parallel subagents against `prd.md` (and `addendum.md` if present), by prefix: +- `skill:NAME` — invoke named skill. +- `file:PATH` — spawn an adversarial subagent giving the agent the file path to use as review lens. +- `text` — follow the instructions use directly as the subagent's prompt. + +**Subagent contract.** Each reviewer writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-5 findings succinct, file path). The parent never holds full review text unless tool does not support subagents. Under Validate intent, the structural validator additionally runs the rendering pipeline in `references/validate.md`. + +**Walk-through.** Present the findings in an organized facilitative fashion. Per finding user can choose to: autofix, discuss, defer to open items, or ignore. ## Finalize @@ -119,8 +128,8 @@ At entry, name the sequence for the user in one sentence: walk the decision log, 1. Decision log audit: walk `decision-log.md` with the user; each entry captured in PRD, in addendum, or set aside. 2. Input reconciliation: subagent per user-supplied input against `prd.md` + `addendum.md`; surface gaps, especially qualitative ideas (tone, voice, feel) the FR structure silently drops. Must happen before polish. -3. Reviewer pass. Assemble the gate menu: structural checklist validator (against `{workflow.validation_checklist}`) + each entry in `{finalize_reviewers}` (resolved on-demand from `customize.toml`) + any ad-hoc reviewers warranted by the PRD content (composed as plain-text entries on the fly). Gate UX is stakes-calibrated: hobby/solo scope may run defaults quietly or skip; higher stakes get the explicit menu with all, subset, or skip. Spawn the selection as parallel subagents against `prd.md`, dispatching by prefix: `skill:NAME` invokes the named skill; `file:PATH` spawns an adversarial subagent applying the loaded file as the review prompt; plain-text entries are used directly. **Subagent contract:** each reviewer writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary to the parent (verdict, top 2-3 findings as one-liners, file path). The parent never holds full review text in context. **Walk-through:** the parent groups findings by PRD section using each finding's location field (or by reviewer when section mapping is unclear); walks the user section by section, offering to open the full review document for any reviewer. Per finding, user picks autofix, discuss, defer to open items, or ignore. Hobby/solo scope can skip the walk and just print summaries. Resolve before polish. -4. Open-items review: triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. A phase-blocker is an open item that would make the PRD unsafe for the next phase of work (UX, architecture, epics); a non-blocker is deferrable to a later cycle with an owner and revisit condition. Surface only phase-blockers one at a time; resolve before calling the PRD ready. Log deferred items to `decision-log.md`. If phase-blocker count is high, flag it. +3. Reviewer pass: run the `## Reviewer Gate` against `prd.md`. Resolve before polish. +4. Triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. A phase-blocker is an open item that would make the PRD unsafe for the next phase of work (UX, architecture, epics); a non-blocker is deferrable to a later cycle with an owner and revisit condition. Surface only phase-blockers one at a time; resolve before calling the PRD ready. Log deferred items to `decision-log.md`. If phase-blocker count is high, flag it. 5. Polish: apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` via parallel subagents. 6. External handoffs: execute `{workflow.external_handoffs}` entries; surface returned URLs/IDs. Skip and flag unavailable tools. 7. Record finalization to `decision-log.md`. Share all artifact paths. Invoke `bmad-help` to share possible steps. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md index ccdc3c52e..2d2e265b1 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md @@ -30,26 +30,27 @@ updated: {YYYY-MM-DD} [Who this is explicitly not for in v1.] ### 2.4 Key User Journeys -*Named-persona flows the product enables. Numbered globally as UJ-1 through UJ-N. FRs reference journeys by ID inline ("realizes UJ-3"); SMs may also cross-reference. Depth is the team's call — the default below carries enough detail for downstream extraction; PMs may go deeper, including full UX-level detail with screens and micro-interactions, if they choose. If a UX doc already exists, mirror its UJ IDs here and point to the source.* +*Named-persona narratives the product enables. Numbered globally as UJ-1 through UJ-N. FRs reference journeys by ID inline ("realizes UJ-3"); SMs may also cross-reference. If a UX doc already exists, mirror its UJ IDs here and point to the source.* -#### UJ-1: {Persona doing the thing} +**Default shape:** a named scene with entry state, path, climax, and resolution. Each beat forces specificity the team would otherwise leave implicit — auth assumptions, screen order, what tells the user value landed. Read together as a short narrative; the example below shows the form. -**Persona:** {Name from §2.1, e.g. "Merchant Admin"} +- **UJ-1. {One-line title — persona doing the thing.}** + - **Persona + context:** one line, grounded enough to explain the *why*. + - **Entry state:** authenticated? which surface? coming from where? + - **Path:** 3-5 concrete beats — taps, screens, decisions. + - **Climax:** the moment value is delivered and how the user knows. + - **Resolution:** state they're left in, what's next. + - **Edge case** *(optional)*: one real failure mode and what the user does next. -**Flow:** -1. {step} -2. {step} -3. {step} + *Written out, that becomes:* + > **UJ-3. Priya checks the trip damage before she's even home.** + > Priya, budgeting on a single income with a new baby, finishes a grocery run and gets in the car. Already authenticated via biometric on a previous session. She opens the app, taps the FAB camera, and scans the receipt. The app OCRs the total and shows a single-screen overlay: this trip $84.20, weekly cap $250, $172.10 remaining, three days left in the week. She closes the app and drives home. **Edge case:** if she scanned a receipt earlier today, the app asks whether this replaces or adds to that trip before counting it against the cap. -**Edge cases:** -- {real failure mode and what the user does next} +- **UJ-2. ...** -**Capabilities surfaced:** *(optional)* -- The system must {capability}. → FR-N - -#### UJ-2: ... - -[Hobby/solo scope can collapse each UJ to a one-liner ("UJ-1 — short flow description"). For complex products with onboarding, checkout, multi-step approvals, etc., expand further. For libraries/CLIs with minimal flow, reduce to a single line or collapse into §2.2 JTBD.] +**Scope dial:** +- **Lighter** — hobby/solo, library/CLI, or when the UJ is essentially a JTBD restated: a single sentence works (`{Persona}, {context}, {what they do and why}.`). +- **Heavier** — auth, multi-device handoff, complex navigation, or anything feeding downstream UX/architecture: add a numbered Flow, an Edge cases list, and a capability → FR mapping (`The system must {capability}. → FR-N`). ## 3. Glossary *Downstream workflows and readers must use these terms exactly. FRs, UJs, and SMs use Glossary terms verbatim; introducing a synonym anywhere in the PRD is a discipline violation. If §4 introduces a new domain noun, add it to the Glossary in the same pass.* diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md index 968f878b9..03b01cc5b 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/probing.md @@ -1,6 +1,6 @@ # Probing -Loaded on entry to Discovery or Update. Symptom-based; `facilitation-guide.md` is section-based. Both apply. +Loaded on entry to Discovery or Update. One probe per turn. When multiple gaps surface, pick the most load-bearing; record the others as Open Questions. diff --git a/src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md b/src/bmm-skills/2-plan-workflows/bmad-prd/references/validate.md similarity index 50% rename from src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md rename to src/bmm-skills/2-plan-workflows/bmad-prd/references/validate.md index 09df82423..fe1e2380f 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md +++ b/src/bmm-skills/2-plan-workflows/bmad-prd/references/validate.md @@ -1,10 +1,22 @@ -# Validation Rendering +# Validate -How the validator subagent's findings become a validation report. Loaded only when the user has explicitly asked for analysis — either Validate intent or a mid-session report request. The Finalize discipline pass during Create/Update does NOT render a report; its findings stay in-conversation. +The full Validate intent playbook. Also covers the structural-validator rendering pipeline used during mid-session report requests. -## Validator subagent output contract +Critique an existing PRD without changing it. Standalone; does NOT enter `## Finalize`. -The subagent walks `{workflow.validation_checklist}` against `prd.md` (and `addendum.md` if present) and writes `{doc_workspace}/validation-findings.json`: +## Orient + +Source-extract against `decision-log.md`, any original inputs, and the PRD/addendum themselves. Delegate to subagents per `## Constraints` → Extract, don't ingest; the parent assembles from extracts. + +## Run the Reviewer Gate + +Run the `## Reviewer Gate` (in SKILL.md) against `prd.md` (and `addendum.md` if present). The gate handles menu assembly, parallel dispatch, the subagent contract, and the section-by-section walk-through. + +The structural checklist validator is one entry in the gate menu; under Validate intent it additionally runs the rendering pipeline below. The Finalize discipline pass during Create/Update does NOT render a report — its findings stay in-conversation. + +## Structural validator pipeline + +The structural validator subagent walks `{workflow.validation_checklist}` against `prd.md` (and `addendum.md` if present) and writes findings to `{doc_workspace}/validation-findings.json`: ```json { @@ -39,7 +51,7 @@ Per-finding fields: - `note` (optional) — the finding itself, in one or two sentences. - `suggested_fix` (optional) — concrete next action. -## Rendering invocation +### Render After the subagent writes findings: @@ -53,6 +65,10 @@ python3 {skill-root}/scripts/render-validation-html.py \ Include `--open` for interactive runs (auto-opens in default browser). Omit `--open` in headless runs. -The script writes two artifacts side-by-side: the HTML report at `--output`, and a markdown companion at the same path with `.md` extension (e.g. `validation-report.md`). Both are always produced when the script runs — trigger gating happens upstream (the script is only invoked when the user has asked for analysis). It computes pass/warn/fail/na counts, derives a grade (Excellent / Good / Fair / Poor) from critical-fail and total-fail counts, renders an inline SVG score bar in the HTML, groups findings by category, and returns a one-line JSON summary on stdout: `{"output": "...", "markdown": "...", "grade": "...", "stats": {...}}`. +The script writes two artifacts side-by-side: the HTML report at `--output`, and a markdown companion at the same path with `.md` extension (e.g. `validation-report.md`). Both are always produced when the script runs. It computes pass/warn/fail/na counts, derives a grade (Excellent / Good / Fair / Poor) from critical-fail and total-fail counts, renders an inline SVG score bar in the HTML, groups findings by category, and returns a one-line JSON summary on stdout: `{"output": "...", "markdown": "...", "grade": "...", "stats": {...}}`. -Re-running validation overwrites the existing report files in place. Markdown form is what Update mode reads when rolling findings into a revision. +Re-running validation overwrites existing report files in place. Markdown form is what Update mode reads when rolling findings into a revision. + +## Close + +Surface all artifact paths and summaries to the user. The Reviewer Gate's walk-through covers section-by-section review of findings; the rendered HTML/markdown report is the persistent artifact. Always offer to roll findings into an Update; Validate itself does not change `prd.md`.