Brian
bb45db4aa4
* feat(bmm): consolidate research trio into bmad-deep-recon
Replace bmad-market-research, bmad-domain-research, and bmad-technical-research
(5,136 lines of near-duplicate legacy step files) with one modern skill,
bmad-deep-recon (~650 lines):
- Research-master-orchestrator persona; conclusions never rest on training
data alone; lead-following rounds with coverage/novelty-exhaustion stops
- Six type packs as ~25-line policy+craft cards (market, domain, technical,
competitive, user-voice, academic-lit) + select decision shape layering a
weighted-matrix method over any type
- Three acquisition modes: Generate (subagent fan-out), Delegate (engine
registry: CLI/MCP, engine-first strategy), Import (provenance-tracked)
- Claims-ledger verification (normal/high/max) with independence rules and
optional red-team pass; cited synthesis with staleness map
- Effort presets (quick/standard/deep) over four knobs (subagents,
sources/round, depth, validation); precedence request > knob > preset
- Plan gate with surface discovery (MCPs/CLIs/engines), routing table, and
time estimate; use_workflows and subagent_models config
- Create/Refresh/Deepen intents, memlog run-folder workspace, headless JSON
- v6 shims forward the three old IDs with type pre-set; analyst menu,
catalog, marketplace, docs and translation mirrors updated
* feat(bmm): runtime output_format for bmad-deep-recon (v7 artifact protocol)
Replace the output_formats array with output_format = auto|html|md|both
(default auto): interactive runs render the HTML briefing, headless or
skill-invoked runs present the canonical markdown only. research.md always
exists in the workspace as the machine-readable report; the briefing is its
regenerable face. First instance of the v7 artifact protocol (memlog = truth,
md = distillation under contract, html = face).
* feat(core): move bmad-deep-recon to core-skills; address review findings
Move: research is not code-project-specific — home it in core-skills
(brainstorming precedent) so CIS and core-only installs get it. Skill ID
unchanged; standalone marketplace plugin added; catalogs moved to Core;
{planning_artifacts} falls back to {output_folder} on core-only installs.
v6 shims stay in bmm-skills (the legacy trio were bmm skills).
Review fixes (CodeRabbit):
- Engine briefs are now file-based: invoke templates substitute
{brief_file} (a skill-generated path), never inline brief text — quotes
and shell metacharacters in researched content can't shape a command.
- Refresh/Deepen preserve verification statuses for out-of-scope claims.
- HTML briefing: http(s)-only source links, escape source-derived text.
- user-voice pack: redact usernames/handles/emails from verbatim quotes;
communities complement surveys (triangulate) rather than beat them.
- engine.md: explicit single-writer rule — digests return to the lead,
which alone writes research.md in plan order.
* feat(core): deep-recon v2 — draft/process/run, faster defaults, research firewall
Rework after first real-run feedback (slow, token-heavy, locally biased
report, end-pass verification degraded quality, digests stranded in
subagent contexts):
- Three modes replace the acquisition-mode machinery: Draft (build a
deep-research prompt the user runs in their own subscribed tool),
Process (file a finished report into imports/, extract to digests/,
distill research.md summary + metadata so downstream never reprocesses),
Run (native fan-out, first-class). Bare research asks get the choice up
front with the trade stated honestly.
- Engine/Delegate registry cut: the Draft->Process round-trip is the
integration with dedicated deep-research tools; engine.md -> run.md.
- Files-first: digests hit {doc_workspace}/digests/ on landing, sections
commit per dimension, synthesis reads files never conversation memory,
dead runs resume from disk.
- Research firewall: persistent_facts default now empty, assistants get
only their brief, project context frames questions but is inadmissible
as evidence.
- Verification at landing, not end-of-run: normal = spot-check
load-bearing claims only; red_team default off; heavy passes behind
high/max. Presets rescaled faster (standard 3 subagents/8 sources/
depth 2).
- Multi-agent research lessons folded into run.md and the plan gate:
decomposition topology (breadth/depth/straightforward), per-assistant
tool-call budgets, query craft with OODA pause, shared source-quality
card, stop-and-write valve, mechanical citation check at finalize.
- Ripple: v6 shims, catalogs, marketplace, docs one-liners (all five
languages), template gains source: provenance field.
* feat(core): deep-recon quality pass — carve SKILL.md, recon_kit scripts, single-source verification
- SKILL.md 3989→2091 tokens: Draft/Process/Refresh+Deepen/Finalize carved to
references/{draft,process,lifecycle,finalize}.md; Run effort knobs + plan
gate moved into run.md; Overview and pack prose trimmed
- verification.md: red-team pass is the single adversarial mechanism (max
runs it at full breadth — no double-spawn); level semantics single-sourced
- scripts/recon_kit.py + tests: citations cross-check, memlog claim tally
(ref=/status= convention, last wins), staleness date math from per-class
windows, deterministic run-folder slugs, escaped source-appendix HTML
- Draft wired with preferred/banned source policies and an open-floor opening
- external_sources examples (Tavily/Sonar/xAI X-Search MCPs); source-quality
card: answer engines are aggregators — chase their citations
* docs: Deep Recon explanation page + integration
- new docs/explanation/deep-recon.md: three modes, mode-choice guidance,
research types, native-run internals diagram, firewall/verification, refresh
- analysis-phase.md research section rewritten for bmad-deep-recon
- core-tools.md: deep-recon in thinking-skills table, full catalog entry,
migration note for the merged market/domain/technical trio
- workflow-map.md + getting-started.md link the new page
- vi-vn developer guide: last stale old-skill flow mention updated
6.0 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Analysis Phase: From Idea to Foundation | What brainstorming, research, product briefs, and PRFAQs are — and when to use each |
|
The Analysis phase (Phase 1) helps you think clearly about your product before committing to building it. Every tool in this phase is optional, but skipping analysis entirely means your PRD is built on assumptions instead of insight.
Why Analysis Before Planning?
A PRD answers "what should we build and why?" If you feed it vague thinking, you get a vague PRD — and every downstream document inherits that vagueness. Architecture built on a weak PRD makes wrong technical bets. Stories derived from weak architecture miss edge cases. The cost compounds.
Analysis tools exist to make your PRD sharp. They attack the problem from different angles — creative exploration, market reality, customer clarity, feasibility — so that by the time you sit down with the PM agent, you know what you're building and for whom.
The Tools
Brainstorming
What it is. A facilitated creative session using proven ideation techniques. The AI acts as coach, pulling ideas out of you through structured exercises — not generating ideas for you.
Why it's here. Raw ideas need space to develop before they get locked into requirements. Brainstorming creates that space. It's especially valuable when you have a problem domain but no clear solution, or when you want to explore multiple directions before committing.
When to use it. You have a vague sense of what you want to build but haven't crystallized the concept. Or you have a concept but want to pressure-test it against alternatives.
See Brainstorming for a deeper look at how sessions work.
Research (Deep Recon)
What it is. One research skill, bmad-deep-recon, that investigates any dimension of your idea through typed research packs: market (competitors, trends, sizing), domain (subject-matter expertise and terminology), technical (feasibility and implementation approaches), competitive teardowns, user-voice, and academic literature. It works three ways — draft a prompt for the deep-research tool you already subscribe to, process a finished report into a cited summary, or run the research directly.
Why it's here. Building on assumptions is the fastest way to build something nobody needs. Research grounds your concept in reality — what competitors already exist, what users actually struggle with, what's technically feasible, and what industry-specific constraints you'll face.
When to use it. You're entering an unfamiliar domain, you suspect competitors exist but haven't mapped them, or your concept depends on technical capabilities you haven't validated. Each research type stands alone; run whichever ones bear on your decision.
See Deep Recon for the three modes, how to choose between them, and how a research run works inside.
Product Brief
What it is. A guided discovery session that produces a 1-2 page executive summary of your product concept. The AI acts as a collaborative Business Analyst, helping you articulate the vision, target audience, value proposition, and scope.
Why it's here. The product brief is the gentler path into planning. It captures your strategic vision in a structured format that feeds directly into PRD creation. It works best when you already have conviction about your concept — you know the customer, the problem, and roughly what you want to build. The brief organizes and sharpens that thinking.
When to use it. Your concept is relatively clear and you want to document it efficiently before creating a PRD. You're confident in the direction and don't need your assumptions aggressively challenged.
PRFAQ (Working Backwards)
What it is. Amazon's Working Backwards methodology adapted as an interactive challenge. You write the press release announcing your finished product before a single line of code exists, then answer the hardest questions customers and stakeholders would ask. The AI acts as a relentless but constructive product coach.
Why it's here. The PRFAQ is the rigorous path into planning. It forces customer-first clarity by making you defend every claim. If you can't write a compelling press release, the product isn't ready. If customer FAQ answers reveal gaps, those are gaps you'd discover much later — and more expensively — during implementation. The gauntlet surfaces weak thinking early, when it's cheapest to fix.
When to use it. You want your concept stress-tested before committing resources. You're unsure whether users will actually care. You want to validate that you can articulate a clear, defensible value proposition. Or you simply want the discipline of Working Backwards to sharpen your thinking.
Which Should I Use?
| Situation | Recommended tool |
|---|---|
| "I have a vague idea, not sure where to start" | Brainstorming |
| "I need to understand the market before deciding" | Research |
| "I know what I want to build, just need to document it" | Product Brief |
| "I want to make sure this idea is actually worth building" | PRFAQ |
| "I want to explore, then validate, then document" | Brainstorming → Research → PRFAQ or Brief |
Product Brief and PRFAQ both produce input for the PRD — choose one based on how much challenge you want. The brief is collaborative discovery. The PRFAQ is a gauntlet. Both get you to the same destination; the PRFAQ tests whether your concept deserves to get there.
:::tip[Not Sure?]
Run bmad-help and describe your situation. It will recommend the right starting point based on what you've already done and what you're trying to accomplish.
:::
What Happens After Analysis?
Analysis outputs feed directly into Phase 2 (Planning). The PRD workflow accepts product briefs, PRFAQ documents, research findings, and brainstorming reports as input — it synthesizes whatever you've produced into structured requirements. The more analysis you do, the sharper your PRD.