bmad-method 6.6.1-next.9 → 6.7.0

package/src/bmm-skills/2-plan-workflows/bmad-prd/references/facilitation-guide.md

@@ -1,79 +0,0 @@
-# PRD Facilitation Guide
-
-Per-section conversation techniques for facilitative mode. Each entry names the coaching move that makes the section's conversation productive — not a checklist, a posture. Skip sections the PM has already resolved; spend more time where thinking is thin.
-
----
-
-## Users and Personas
-
-**The move:** Ground personas in real people, not archetypes.
-
-Ask the PM to describe a specific person they have observed or talked to — not a type, an actual human. "Who is the clerk at your store? Tell me about them." Invented detail (name, age, backstory from nowhere) is persona theater — the team builds for a fiction. If the PM says "someone like..." push gently: "Is there a real person you're thinking of?"
-
-Once grounded: what does that person want to accomplish in the time they interact with this product? What would make them say this is easier than what they do today? What would make them abandon it?
-
-For the remote user or secondary persona: same grounding, different question — what question do they need answered in under ten seconds, and what do they do if they can't get it?
-
-Mark anything the PM could not ground in observation as `[ILLUSTRATIVE]` — and note it's a hypothesis to validate, not a spec to build for.
-
----
-
-## Core User Journeys
-
-**The move:** Story structure, not use-case list.
-
-For each primary journey, walk through four beats:
-
-- **Opening scene** — where do we meet this person, what is their situation right now, what pain or need is present?
-- **Rising action** — what steps do they take, what do they discover or decide along the way?
-- **Climax** — the moment the product delivers real value; the thing they could not do before
-- **Resolution** — what is their new reality; how is their situation different?
-
-After each journey: what could go wrong at the climax? What is the recovery path? This is where edge cases that matter surface — not invented error states, but real failure modes for this person.
-
-Explicitly name what capability each journey reveals. "This journey requires the operator to log an entry with no internet — which means we need a decision on whether that's in or out of MVP." Journeys produce capability requirements; make the link visible.
-
----
-
-## Key Feature Decisions
-
-**The move:** Surface the assumptions that would otherwise be silent.
-
-Before the draft exists, there are decisions the agent would silently make and the PM would never know were made. These are the ones worth a thirty-second conversation:
-
-- Decisions that drive the core UX model (e.g., one record per day vs. many; who can edit vs. view; what happens when the expected input doesn't exist)
-- Decisions where the "obvious" choice has real consequences the PM may not have considered
-- Decisions that, if wrong, require structural changes to fix later
-
-For each: state what you inferred, name the alternative, ask which is right. Do not present options as a quiz — present your inference and invite correction. "I'm assuming one sales tally per day replaces rather than adds. Is that right, or should the operator be able to log multiple?" Resolve and move on. Only tag as `[ASSUMPTION]` when the answer requires external input or research the PM cannot provide now.
-
----
-
-## Scope Boundary
-
-**The move:** Establish MVP philosophy before listing features.
-
-Before asking what is in or out, ask what kind of MVP this is:
-
-- **Problem-solving MVP** — the minimum that proves the core problem is solved; rough edges acceptable
-- **Experience MVP** — the minimum that proves the interaction model works; quality matters
-- **Platform MVP** — the minimum infrastructure other things can build on; completeness of the base matters
-- **Revenue MVP** — the minimum someone will pay for; business viability is the test
-
-The answer changes what "minimum" means. A problem-solving MVP for a personal-use tool has different scope logic than an experience MVP aimed at non-tech-savvy users who will bounce at the first confusion.
-
-Once the philosophy is named, non-goals do as much work as in-scope items. Probe for the things the PM is tempted to add. "What keeps almost making it onto the list?" For each: is it truly out of MVP, or does it need to be in because the MVP fails without it?
-
----
-
-## Success Metrics
-
-**The move:** Push every adjective to a measurement.
-
-"Users will love it" — what does that mean in behavior? "It'll be fast" — fast at what, for whom, measured how? "Good adoption" — what percentage, by when, doing what? Every quality claim needs a measurement or it is not a success criterion, it is a wish.
-
-For each metric surfaced: connect it back to the product's differentiator. If the differentiator is simplicity for non-tech users, the primary metric should measure whether non-tech users successfully complete the core action without help — not session count or feature usage breadth.
-
-Name counter-metrics explicitly — what this product should *not* optimize for. These prevent the wrong thing being built: more entries per day is not better if the goal is accurate daily records; longer dashboard sessions may indicate a broken IA, not high engagement. Counter-metrics are as load-bearing as primary metrics for downstream readers.
-
-For low-stakes or personal-use products: one sentence is enough. "Success: I use this daily and it replaces the notebook within a month." Do not impose metric rigor where the stakes do not warrant it.

package/src/bmm-skills/2-plan-workflows/bmad-prd/references/validation-render.md

@@ -1,58 +0,0 @@
-# Validation Rendering
-
-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.
-
-## Validator subagent output contract
-
-The subagent walks `{workflow.validation_checklist}` against `prd.md` (and `addendum.md` if present) and writes `{doc_workspace}/validation-findings.json`:
-
-```json
-{
-  "prd_name": "Plantsona",
-  "prd_path": "{doc_workspace}/prd.md",
-  "checklist_path": "{workflow.validation_checklist}",
-  "timestamp": "2026-05-11T09:14:00",
-  "overall_synthesis": "2-3 sentences of judgment about the PRD's overall state — what holds up, what's at risk. Written by the subagent, not the parent.",
-  "findings": [
-    {
-      "id": "Q-2",
-      "category": "Quality",
-      "title": "Measurability",
-      "status": "warn",
-      "severity": "medium",
-      "location": "§16 Success Metrics, lines 408-422",
-      "note": "Success Metrics list is measurable but counter-metrics are named only for premium conversion. Other metrics lack paired counter-metrics.",
-      "suggested_fix": "Add counter-metrics for engagement (e.g., DAU/MAU) and seasonal cadence."
-    }
-  ]
-}
-```
-
-Per-finding fields:
-
-- `id` (required) — checklist item ID (e.g., `Q-1`, `D-2`, `STK-1`, or org-custom prefixes).
-- `category` (optional) — explicit category name; if omitted, the renderer maps from the ID prefix.
-- `title` (optional but recommended) — the checklist item's short name.
-- `status` — `pass` | `warn` | `fail` | `n/a`.
-- `severity` — `low` | `medium` | `high` | `critical`.
-- `location` (optional) — section/line/range in the PRD where the finding lives. Cite specifics, never abstract criticism.
-- `note` (optional) — the finding itself, in one or two sentences.
-- `suggested_fix` (optional) — concrete next action.
-
-## Rendering invocation
-
-After the subagent writes findings:
-
-```bash
-python3 {skill-root}/scripts/render-validation-html.py \
-  --findings {doc_workspace}/validation-findings.json \
-  --template {workflow.validation_report_template} \
-  --output {doc_workspace}/validation-report.html \
-  --open
-```
-
-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": {...}}`.
-
-Re-running validation overwrites the existing report files in place. Markdown form is what Update mode reads when rolling findings into a revision.

package/src/bmm-skills/2-plan-workflows/bmad-prd/scripts/render-validation-html.py

@@ -1,290 +0,0 @@
-#!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.10"
-# ///
-"""Render a PRD validation findings JSON into HTML + markdown reports.
-
-Reads structured findings produced by the validator subagent, groups them by
-category (explicit `category` field, else derived from ID prefix), computes a
-pass/warn/fail summary and grade, substitutes into the configured HTML
-template, writes a markdown companion at the same path with `.md` extension,
-and optionally opens the HTML in the default browser.
-"""
-
-import argparse
-import html
-import json
-import string
-import sys
-import webbrowser
-from datetime import datetime
-from pathlib import Path
-
-CATEGORY_FROM_PREFIX = {
-    "Q": "Quality",
-    "D": "Discipline",
-    "S": "Structural integrity",
-    "STK": "Stakes-gated",
-    "M": "Mechanical",
-}
-
-CATEGORY_ORDER = ["Quality", "Discipline", "Structural integrity", "Stakes-gated", "Mechanical"]
-
-
-def category_for(finding: dict) -> str:
-    explicit = finding.get("category")
-    if explicit:
-        return explicit
-    fid = finding.get("id", "")
-    prefix = fid.split("-", 1)[0] if "-" in fid else fid
-    return CATEGORY_FROM_PREFIX.get(prefix, prefix or "Other")
-
-
-def compute_stats(findings: list[dict]) -> dict:
-    total = len(findings)
-    by_status = {"pass": 0, "warn": 0, "fail": 0, "n/a": 0}
-    failed_critical = 0
-    failed_high = 0
-    for f in findings:
-        status = (f.get("status") or "n/a").lower()
-        if status in by_status:
-            by_status[status] += 1
-        if status == "fail":
-            sev = (f.get("severity") or "low").lower()
-            if sev == "critical":
-                failed_critical += 1
-            elif sev == "high":
-                failed_high += 1
-    return {
-        "total": total,
-        "passed": by_status["pass"],
-        "warned": by_status["warn"],
-        "failed": by_status["fail"],
-        "na": by_status["n/a"],
-        "failed_critical": failed_critical,
-        "failed_high": failed_high,
-    }
-
-
-def grade_from(stats: dict) -> tuple[str, str]:
-    if stats["failed_critical"] > 0:
-        return "Poor", "grade-poor"
-    if stats["failed_high"] >= 1 or stats["failed"] >= 4:
-        return "Fair", "grade-fair"
-    if stats["failed"] > 0 or stats["warned"] > 2:
-        return "Good", "grade-good"
-    return "Excellent", "grade-excellent"
-
-
-def render_score_bar(stats: dict, width: int = 480, height: int = 22) -> str:
-    total = max(stats["total"], 1)
-    p = stats["passed"] / total * width
-    w = stats["warned"] / total * width
-    f = stats["failed"] / total * width
-    n = stats["na"] / total * width
-    return (
-        f'<svg width="{width}" height="{height}" viewBox="0 0 {width} {height}" role="img" '
-        f'aria-label="Pass / warn / fail / n-a breakdown">'
-        f'<rect x="0" y="0" width="{p:.1f}" height="{height}" fill="#22c55e"/>'
-        f'<rect x="{p:.1f}" y="0" width="{w:.1f}" height="{height}" fill="#eab308"/>'
-        f'<rect x="{p + w:.1f}" y="0" width="{f:.1f}" height="{height}" fill="#ef4444"/>'
-        f'<rect x="{p + w + f:.1f}" y="0" width="{n:.1f}" height="{height}" fill="#94a3b8"/>'
-        f"</svg>"
-    )
-
-
-def render_finding(f: dict) -> str:
-    status = (f.get("status") or "n/a").lower()
-    severity = (f.get("severity") or "low").lower()
-    fid = html.escape(f.get("id") or "")
-    title = html.escape(f.get("title") or fid)
-    location = html.escape(f.get("location") or "")
-    note = html.escape(f.get("note") or "")
-    fix = html.escape(f.get("suggested_fix") or "")
-
-    status_class = "na" if status == "n/a" else status
-    parts = [
-        f'<article class="finding finding-{status_class}">',
-        '<header>',
-        f'<span class="badge badge-status badge-{status_class}">{status.upper()}</span>',
-        f'<span class="badge badge-severity badge-sev-{severity}">{severity}</span>',
-        f'<span class="finding-id">{fid}</span>',
-        f'<h3 class="finding-title">{title}</h3>',
-        '</header>',
-    ]
-    if location:
-        parts.append(f'<div class="finding-location"><strong>Location:</strong> {location}</div>')
-    if note:
-        parts.append(f'<div class="finding-note">{note}</div>')
-    if fix:
-        parts.append(f'<div class="finding-fix"><strong>Suggested fix:</strong> {fix}</div>')
-    parts.append("</article>")
-    return "\n".join(parts)
-
-
-def render_category(name: str, findings: list[dict]) -> str:
-    items = "\n".join(render_finding(f) for f in findings)
-    name_e = html.escape(name)
-    return (
-        f'<section class="category">'
-        f"<details open>"
-        f'<summary><h2>{name_e} <span class="count">({len(findings)})</span></h2></summary>'
-        f"{items}"
-        f"</details>"
-        f"</section>"
-    )
-
-
-SEVERITY_ORDER = ["critical", "high", "medium", "low"]
-
-
-def render_finding_md(f: dict) -> str:
-    status = (f.get("status") or "n/a").upper()
-    severity = (f.get("severity") or "low").lower()
-    fid = f.get("id") or ""
-    title = f.get("title") or fid
-    location = f.get("location") or ""
-    note = f.get("note") or ""
-    fix = f.get("suggested_fix") or ""
-
-    lines = [f"### [{status}] {fid} — {title} _(severity: {severity})_"]
-    if location:
-        lines.append(f"- **Location:** {location}")
-    if note:
-        lines.append(f"- **Finding:** {note}")
-    if fix:
-        lines.append(f"- **Suggested fix:** {fix}")
-    return "\n".join(lines)
-
-
-def render_markdown_report(data: dict, findings: list[dict], stats: dict, grade: str) -> str:
-    prd_name = data.get("prd_name") or "PRD"
-    prd_path = data.get("prd_path") or ""
-    checklist_path = data.get("checklist_path") or ""
-    timestamp = data.get("timestamp") or datetime.now().isoformat(timespec="seconds")
-    synthesis = data.get("overall_synthesis") or ""
-
-    out = [
-        f"# Validation Report — {prd_name}",
-        "",
-        f"- **PRD:** `{prd_path}`",
-        f"- **Checklist:** `{checklist_path}`",
-        f"- **Run at:** {timestamp}",
-        f"- **Grade:** {grade}",
-        "",
-        f"**Summary:** {stats['passed']} pass · {stats['warned']} warn · {stats['failed']} fail · {stats['na']} n/a "
-        f"(total {stats['total']}; critical fails: {stats['failed_critical']}, high fails: {stats['failed_high']})",
-    ]
-    if synthesis:
-        out += ["", "## Overall synthesis", "", synthesis]
-
-    # Group by severity then status: failed criticals first, then highs, etc.
-    by_sev: dict[str, list[dict]] = {s: [] for s in SEVERITY_ORDER}
-    other: list[dict] = []
-    for f in findings:
-        sev = (f.get("severity") or "low").lower()
-        if sev in by_sev:
-            by_sev[sev].append(f)
-        else:
-            other.append(f)
-
-    out += ["", "## Findings by severity"]
-    any_findings = False
-    for sev in SEVERITY_ORDER:
-        items = by_sev[sev]
-        if not items:
-            continue
-        any_findings = True
-        out += ["", f"### {sev.capitalize()} ({len(items)})", ""]
-        out += [render_finding_md(f) for f in items]
-    if other:
-        any_findings = True
-        out += ["", f"### Other ({len(other)})", ""]
-        out += [render_finding_md(f) for f in other]
-    if not any_findings:
-        out += ["", "_No findings._"]
-
-    return "\n".join(out) + "\n"
-
-
-def main(argv: list[str]) -> int:
-    parser = argparse.ArgumentParser(description="Render PRD validation findings to HTML.")
-    parser.add_argument("--findings", required=True, help="Path to validation-findings.json")
-    parser.add_argument("--template", required=True, help="Path to HTML template")
-    parser.add_argument("--output", required=True, help="Path to write the rendered HTML")
-    parser.add_argument("--open", action="store_true", help="Open the rendered HTML in the default browser")
-    args = parser.parse_args(argv)
-
-    findings_path = Path(args.findings)
-    template_path = Path(args.template)
-    output_path = Path(args.output)
-
-    try:
-        data = json.loads(findings_path.read_text(encoding="utf-8"))
-    except FileNotFoundError:
-        print(f"error: findings file not found: {findings_path}", file=sys.stderr)
-        return 1
-    except json.JSONDecodeError as e:
-        print(f"error: findings file is not valid JSON ({findings_path}): {e}", file=sys.stderr)
-        return 1
-    try:
-        template = template_path.read_text(encoding="utf-8")
-    except FileNotFoundError:
-        print(f"error: template file not found: {template_path}", file=sys.stderr)
-        return 1
-
-    findings = data.get("findings", []) or []
-
-    by_cat: dict[str, list[dict]] = {}
-    for f in findings:
-        by_cat.setdefault(category_for(f), []).append(f)
-
-    sorted_cats = sorted(
-        by_cat.keys(),
-        key=lambda c: (CATEGORY_ORDER.index(c) if c in CATEGORY_ORDER else 99, c),
-    )
-    categories_html = "\n".join(render_category(c, by_cat[c]) for c in sorted_cats)
-
-    stats = compute_stats(findings)
-    grade, grade_class = grade_from(stats)
-    score_svg = render_score_bar(stats)
-
-    timestamp = data.get("timestamp") or datetime.now().isoformat(timespec="seconds")
-    substitutions = {
-        "prd_name": html.escape(str(data.get("prd_name") or "PRD")),
-        "prd_path": html.escape(str(data.get("prd_path") or "")),
-        "checklist_path": html.escape(str(data.get("checklist_path") or "")),
-        "timestamp": html.escape(timestamp),
-        "overall_synthesis": html.escape(str(data.get("overall_synthesis") or "")),
-        "grade": grade,
-        "grade_class": grade_class,
-        "total": str(stats["total"]),
-        "passed": str(stats["passed"]),
-        "failed": str(stats["failed"]),
-        "warned": str(stats["warned"]),
-        "na": str(stats["na"]),
-        "score_svg": score_svg,
-        "categories_html": categories_html,
-    }
-
-    rendered = string.Template(template).safe_substitute(substitutions)
-    output_path.write_text(rendered, encoding="utf-8")
-
-    md_path = output_path.with_suffix(".md")
-    md_path.write_text(render_markdown_report(data, findings, stats, grade), encoding="utf-8")
-
-    print(json.dumps({
-        "output": str(output_path),
-        "markdown": str(md_path),
-        "grade": grade,
-        "stats": stats,
-    }))
-
-    if args.open:
-        webbrowser.open(output_path.resolve().as_uri())
-
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))