Source: BMAD Recon · bmad-recon.md · updated 2026-07-25 · 🔒 secret gist

Synced verbatim from gist.github.com/bl9.

BMAD Deep Recon — Complete Guide

Covers PR #2611 (merged 23 Jul 2026) and docs/explanation/deep-recon.md. Written for someone with zero BMAD background, then applied to two concrete features: user recommendation and multilingual translation.

Reading order. bmad-deep-recon-foundations.md — what every term means and where its name came from. Then bmad-deep-recon-howto.md — concept-by-concept, exactly what you type and what comes back (plus how to apply the same techniques in plain Claude, without BMAD). Then this document — applied domains, epistemology, and task-driven walkthroughs.

Contents

• 0. The short, honest answer to "how useful is this?"
• 1. Background: BMAD concepts you need first
• 2. What PR #2611 actually changed
• 3. The three modes
• 4. Research types (the "packs")
• 5. How a native Run thinks
• 6. Why the reports hold up
• 7. The run folder, and research as a living asset
• 8. Where it sits in the BMAD lifecycle
• 9. Configuration
• 10. Research checkpoints across a feature's life
• 11. The full use-case catalog
• 12. Applied: a user recommendation feature
• 13. Deep dive: privacy and regulatory research
• 14. Deep dive: security and adversarial research
• 15. Deep dive: algorithm and technique-trend research
• 16. Applied: a multilingual translation feature
• 17. Deep dive: licensing, procurement and vendor risk
• 18. Best practices
• 19. Anti-patterns
• 20. Command cheat sheet
• 21. Transferable design lessons
• 22. The epistemology underneath all of this
• 23. Worked walkthroughs for software engineers
  • Walkthrough A — Native Run: choosing an embedding model
  • Walkthrough B — Draft → Process: the MT vendor landscape
  • Walkthrough C — The compliance gate, done without fooling yourself
  • Walkthrough D — Threat-modeling a ranking surface
  • Walkthrough E — Refresh, three months later
  • Walkthrough F — Deepen one dimension
  • Walkthrough G — Headless refresh in CI
  • Walkthrough H — The anti-walkthrough
  • 23.9 Team integration patterns
  • 23.10 Calibration — what to spend where
• 24. Sources

0. The short, honest answer to "how useful is this?"

Deep Recon is decision infrastructure, not feature-building infrastructure. It pays off only when the following are all true:

• You face a choice with real switching cost (a model, a vendor, an architecture, a metric definition, a locale strategy).
• The answer is not in your repo — it lives in vendor docs, benchmark papers, pricing pages, forum threads, standards documents.
• You will otherwise decide from the model's memory, which is stale and uncited.

It is not useful for:

• Writing the ranking service itself (that's bmad-dev / story workflows).
• Anything answerable by reading your own codebase (that's bmad-document-project).
• Facts you already know cold.

Practical read for your two examples:

Rule of thumb: if you can write the decision as "X vs Y vs Z, and I'll be stuck with it for 12 months," Deep Recon is worth 20–40 minutes. If you can write it as "how do I implement…", it isn't.

1. Background: BMAD concepts you need first

If you already know BMAD v6/v7, skip to §2.

1.1 What BMAD is

BMAD-METHOD ("Breakthrough Method for Agile AI-Driven Development") is an open-source framework that packages agentic software development into skills — structured markdown instruction sets an AI coding agent (Claude Code, Cursor, Copilot, etc.) loads on demand. It imposes a lifecycle: analysis → planning → architecture → implementation.

1.2 The vocabulary

1.3 Why "research" is a skill at all

Two failure modes drove it:

1. Hallucinated grounding. Ask a model about market size or vendor pricing and it answers from training data — confidently, uncitably, and often 18 months stale.
2. Uncaptured reasoning. Even when the research is good, it evaporates when the chat ends. Downstream planning has to re-derive it.

Deep Recon addresses both: no conclusion may rest on training data alone, and every engagement writes a durable cited research.md.

2. What PR #2611 actually changed

2.1 Consolidation

Three legacy skills — bmad-market-research, bmad-domain-research, bmad-technical-research — totalling ~5,136 lines of near-duplicate step files, were replaced by one skill, bmad-deep-recon, at roughly 650 lines. The three old names survive as v6 shims that forward with the corresponding type pre-set.

2.2 Relocation to core

The skill was moved from src/bmm-skills/1-analysis/ to src/core-skills/. Rationale: research is not code-project-specific (same precedent as brainstorming), so non-software and core-only installs get it too. On core-only installs, {planning_artifacts} falls back to {output_folder}. It also ships as a standalone marketplace plugin.

2.3 The v2 rework (the important part)

The first version was field-tested and found slow, token-heavy, and locally biased, with end-of-run verification degrading quality and subagent digests stranded in contexts that then died. The rework:

• Replaced the "acquisition mode" / engine-delegate registry with three modes: Draft, Process, Run.
• Added the research firewall.
• Went files-first — digests land on disk on arrival.
• Moved verification to landing time, not an end pass.
• Rescaled presets faster (standard is now 3 subagents / 8 sources / depth 2).
• Cut SKILL.md from ~3,989 to ~2,091 tokens by carving procedures into references/.

2.4 Determinism kit

scripts/recon_kit.py (stdlib-only, PEP 723, unit-tested) owns work the model shouldn't hand-derive:

• Citation marker ↔ appendix cross-check
• Memlog claim tally (ref= / status= convention, last status wins)
• Staleness re-check dates from per-class freshness windows
• Deterministic run-folder slugs across the draft→process→refresh lifecycle
• Escaped/validated source-appendix HTML

This is the transferable lesson: anything mechanical and verifiable should be a script, not a prompt. Models are bad at counting and date math and excellent at judgment.

2.5 Security findings addressed in review

Worth knowing because the same mistakes appear in your own agent tooling:

3. The three modes

Choosing

The trade, stated plainly: hosted deep-research products crawl wider per dollar because you've already paid for the subscription; Run costs your tokens and minutes but stays in context and can use every tool your harness has. On a bare "research X" ask, Deep Recon states this trade once and remembers your preference for the session.

4. Research types (the "packs")

A type selects a pack: a ~25-line card of prioritized dimensions, source craft, and freshness rules. Deep Recon infers the type from your ask, or you name it.

Custom types can be added via override TOML through bmad-customize.

Decision shape — a second, independent axis

• explore (default) — build understanding
• select — layers a weighted-matrix method over any type for a structured choose-between

Any type can end in a selection matrix. technical + select is the combination you'll use most for engineering decisions.

5. How a native Run thinks

Plan gate (decision, dimensions, topology, effort, time estimate)
        │ you approve
        ▼
   Topology choice
   ├── breadth-first ....... assistants split independent sub-questions
   ├── depth-first ......... assistants take different angles on one question
   └── straightforward ..... one assistant, small budget
        │
        ▼
Digests written to disk as each assistant returns
        │
        ▼
Verify load-bearing claims as material lands
        │
        ▼
Write the dimension's section (report grows in front of you)
        │
        ├── leads + budget remain? → follow the leads (next round)
        └── coverage or exhaustion → next dimension
        │
        ▼
Synthesis: cross-dimension insights, recommendations, staleness map
        │
        ▼
Mechanical citation check → research.md (+ optional HTML briefing)

5.1 The plan gate

The single hard stop. It shows the decision, the dimensions pruned to it, the topology, the knobs in force, and a realistic time estimate. Approve it and the run proceeds with light checkpoints rather than constant interrogation.

This is where you spend your attention. A bad plan gate produces a beautiful, well-cited, useless report.

5.2 Topology

Fan-out is a deliberate choice, not a default. Independent sub-questions get parallel assistants. One deep question gets several perspectives on the same material. A simple lookup gets one assistant with a handful of calls — ten agents on an easy question just burns tokens.

5.3 Effort presets

Precedence: request > pinned knob > preset. Anything you say in the request overrides.

Rounds follow leads — contradictions and unexpected connections from round one become round two's assignments. A dimension stops early when its questions are answered or a full round surfaces nothing new.

5.4 Other run craft

• Per-assistant tool-call budgets — prevents one assistant from eating the whole run.
• Short-query craft with an evaluate-before-next-call loop — read the result before firing the next search.
• Shared source-quality card — answer engines (Perplexity et al.) count as one publisher; chase their citations to the primaries.
• Stop-and-write valve — commit what you have rather than spiraling.

6. Why the reports hold up

6.1 Two standing rules, inherited verbatim by every subagent

1. No conclusions from training data. Model memory proposes questions and search strategy; every claim in the report traces to a source retrieved or imported during this engagement.
2. The research firewall. Your project files and briefs shape what gets asked, never what gets found. Assistants receive only their assignment. persistent_facts defaults to empty. A run therefore cannot come back quietly confirming whatever your local context already believed.

The firewall is the single most important idea in the whole design. Confirmation bias is the default failure mode of agentic research: give an agent your architecture doc and ask it to research alternatives, and it will find that your architecture is excellent.

6.2 Citation discipline

Every claim carries a publisher, a publication date, and an access date. Inline [n] markers resolve to a source appendix. A mechanical cross-check at finalize confirms markers and appendix agree — script, not vibes.

6.3 Verification levels

Verification runs as material lands, never as an end-of-run rewrite pass (the v1 lesson — a late pass degraded quality). The red-team pass is the single adversarial mechanism. An outcome adjusts a claim's status; it never licenses rewriting findings.

6.4 Freshness as part of truth

Each pack sets freshness windows per claim class. A market size from three years ago is reported as history, not as fact. This matters enormously in fast-moving areas — an MT quality benchmark from 2023 describes a world that no longer exists.

6.5 Files-first

Digests, extractions, and report sections hit the run folder the moment they exist. The conversation is a control channel, not storage. A run that dies mid-flight resumes from disk with nothing lost, and the report builds in front of you instead of behind a spinner.

7. The run folder, and research as a living asset

Each engagement gets one folder under your planning artifacts:

<planning_artifacts>/<run-slug>/
├── imports/      # originals, untouched
├── digests/      # extracted claims, behind the firewall
├── briefs/       # per-dimension assignments (file-based, never shell-interpolated)
├── memlog        # append-only truth
└── research.md   # the canonical cited report

research.md always exists as the machine-readable report. The HTML briefing is its regenerable face — this is the v7 artifact protocol: memlog = truth, markdown = distillation under contract, HTML = face. output_format = auto | html | md | both; auto renders HTML for interactive runs and markdown only for headless or skill-invoked runs.

The report ends with a staleness map naming which claims age fastest and when to re-check. That map powers the lifecycle:

• Refresh — re-verifies only stale claims, appends a delta report (confirmed / changed / overturned), and warns you when an overturned claim feeds a downstream artifact.
• Deepen — drills into one dimension without re-running the rest.

The overturned-claim warning is the sleeper feature. If your PRD's rationale rests on a pricing claim that just changed, you find out.

8. Where it sits in the BMAD lifecycle

bmad-deep-recon  →  research.md (+ metadata frontmatter)
        │
        ├──→ bmad-product-brief   (reads the summary; never reprocesses the original)
        ├──→ bmad-prd
        └──→ architecture / ADRs

Downstream skills consume the summary and metadata directly. That's the payoff of the fixed output shape — a PRD doesn't care whether the research came from Draft+Process or a native Run.

Entry points: /bmad-deep-recon, or through the Analyst agent (Mary), whose menu gained TS (select shape), CR (competitive), and UV (user-voice) alongside the existing research entry.

9. Configuration

9.1 Resolution layers

Per-skill config resolves through a layered merge:

1. _bmad/custom/{skill-name}.user.toml — personal, gitignored — wins
2. _bmad/custom/{skill-name}.toml — team/org, committed
3. The skill's own customize.toml — defaults

Merge rules: scalars override; tables deep-merge; arrays of tables keyed by code or id replace matching entries and append new ones; all other arrays append. There is no removal mechanism — you can't delete a base item, only override it (e.g. by code with a no-op) or fork the skill.

9.2 Deep Recon's knobs

Use /bmad-customize bmad-deep-recon rather than hand-authoring TOML.

10. Research checkpoints across a feature's life

Most teams treat research as a single event at the start of a project. It isn't. A feature passes through several gates, each with a different question, a different type pack, and a different cost of getting it wrong.

The pattern worth internalizing: almost everyone does gate 6 and skips gates 3, 4, and 5 — then discovers them during security and legal review, after the design is frozen and the sprint is committed. Gates 3–5 are cheap in week one and brutal in week ten. They're also the gates where external evidence matters most and where model memory is least reliable, which is exactly the profile Deep Recon is built for.

Gate 6 — the one everybody does — is the one where research adds the least, because you can usually just try both.

11. The full use-case catalog

The categories below are where Deep Recon earns its cost on feature work. Each maps to a type pack and a signal that tells you it's worth running.

11.1 Underrated advantages of running research as a skill rather than ad-hoc chat

Beyond the findings themselves:

• It's a durable team artifact. research.md with provenance frontmatter outlives the chat, the sprint, and the engineer. New joiners read why the decision was made instead of asking.
• It's audit evidence. Publisher + publication date + access date on every claim is precisely the shape compliance functions want. In a regulated environment, "we evaluated these options against these criteria on this date, here are the sources" is materially valuable on its own.
• It settles disagreements on evidence rather than seniority. A cited weighted matrix is harder to argue with than an opinion, and easier to change when the evidence changes.
• It's negotiation leverage. A sourced pricing and feature comparison is a real input to a vendor conversation.
• It parallelizes. Draft mode fires the expensive crawl into a subscription tool while you keep working; Process folds the result back in.
• It's automatable. The headless JSON contract means a quarterly refresh can run in CI, not on someone remembering.
• It inoculates against your own agentic pipelines. If you're building AI features, "no conclusions from training data" and the firewall are the disciplines you'll want in your own retrieval systems anyway. Deep Recon is a working reference implementation.
• It forces the decision to be written down. Half the value arrives at the plan gate, before a single search runs, because you had to state what you're actually deciding and under what constraints.

12. Applied: a user recommendation feature

Much of this feature is internal work — but the external parts are not the ones most engineers expect. Privacy and security carry more research value here than model selection does.

12.1 Decisions that genuinely need external evidence

12.2 Decisions that should not go to research

• Your index mapping, shard layout, refresh interval — read your cluster.
• Which features exist in your event stream — read your schema.
• Bucketing/assignment for A/B — that's design, not evidence.
• "How do I implement MMR" — you know this; it's twelve lines.

12.3 A worked plan-gate framing

Decision: pick the embedding model for the recommendation retrieval stage, deployable on our existing OpenSearch/HNSW infrastructure, for the next ~12 months.

Constraints: must handle our language mix; ≤200 ms p99 for the retrieval stage; self-hostable preferred; index memory budget is a hard ceiling.

Candidates to include (not to confirm): [3–5 named], plus any strong option the research surfaces.

Type: technical, select shape. Effort: deep. Validation: high.

Freshness bar: benchmark claims older than 12 months are reported as history.

Note the phrasing "to include, not to confirm." Naming candidates without that framing quietly asks the run to justify your shortlist.

12.4 What good output looks like

• A weighted matrix with your constraints as the weights, not generic ones.
• Every benchmark number carrying its dataset, date, and who ran it — vendor-run numbers flagged as such.
• An explicit "what we could not determine" section (Process mode gap-checks for exactly this).
• A staleness map that says, in effect: re-check the model landscape in 4 months; the license terms in 12.

13. Deep dive: privacy and regulatory research

Not legal advice. This produces an evidence base for a conversation with privacy counsel, not a substitute for one. The value is that you arrive at that conversation with cited primary sources and specific questions instead of vague anxiety.

13.1 Why this is the strongest case for Deep Recon

Privacy research satisfies every condition that makes the skill worth its cost, simultaneously:

• Entirely external. Statutes, regulator guidance, enforcement decisions, case law. None of it is in your repo, and none of it is inferable from your architecture.
• Jurisdiction-plural. A Toronto-built product with EU users sits under PIPEDA, Quebec Law 25, GDPR, and the DSA at once — and they don't agree on consent, notice, or automated decisioning.
• Fast-moving in exactly the layer that matters. Statute text is stable; regulator guidance and enforcement posture are not, and it's the guidance that determines whether your design passes.
• Load-bearing and expensive to reverse. You can swap an embedding model next sprint. You cannot swap a lawful basis after you've collected two years of data under it.
• The worst possible case for model memory. Legal reform moves constantly and a confidently-stated stale claim here is far more damaging than a stale benchmark. The no conclusions from training data rule is doing real work.

That last point is not hypothetical. Canadian federal privacy and AI reform has been through multiple bill cycles; I would not assert its current status from memory, and neither should any model you're relying on. That uncertainty is the argument for running the research, not a reason to skip it.

13.2 Split it into two engagements, not one

The common mistake is one sprawling "GDPR for recommender systems" run. That's two different decisions with two different source policies, and merging them produces a report that's shallow on both.

Run A — domain type: what the rules actually require

Dimensions to insist on at the plan gate:

• Lawful basis for profiling-based recommendation. Consent vs. legitimate interest, and specifically the contexts where legitimate interest has been rejected by regulators. Include the balancing-test documentation expectations.
• GDPR Art. 22 threshold. When does ranking become "automated decision-making producing legal or similarly significant effects"? Ordinary content ranking usually doesn't; ranking that gates access, pricing, or opportunity may.
• Art. 15 access and Art. 20 portability. What must you be able to show a user about their own profile? This has direct schema consequences.
• Art. 17 erasure scope. Does the right reach a trained model and derived embeddings, or only the raw interaction log? Regulator positions differ and have moved.
• Purpose limitation and secondary use. Interaction data collected for one surface being reused to train a ranker for another is a live issue.
• DSA recommender-system obligations. Parameter transparency, and the requirement to offer a non-profiling option — plus the thresholds that determine whether they apply to you at all.
• EU AI Act. Recommenders are generally not Annex III high-risk, but transparency duties and GPAI obligations can still attach if you're using a foundation model in the pipeline. Get the classification question answered explicitly rather than assumed.
• Quebec Law 25 automated-decision notice. Stricter than PIPEDA on this point and routinely missed by teams who "did GDPR."
• PIPEDA and Canadian reform status. Current, not remembered.
• US state law patchwork. Where sensitive-inference and opt-out-of-profiling provisions bite.
• Children's and minors' data. Separate, stricter, and often triggers age-assurance obligations.
• Cross-border transfer posture. Applies to embedding inference calls, which teams frequently forget are transfers.

Run B — technical type: how to actually satisfy the above

• Right-to-erasure vs. HNSW reality. Vector indexes don't truly delete — you get a soft delete plus eventual segment merge. What's the real deletion latency, is it bounded, and does a bounded-but-slow deletion satisfy the requirement? This is a genuine engineering-meets-law question with published discussion.
• Are user embeddings personal data? Increasingly treated as yes. If so, every derived vector inherits the obligations.
• Embedding inversion attacks. Published work shows embeddings can leak the attributes they were built from — which converts a "we only store vectors" argument into a liability.
• Membership inference. Can an attacker determine whether a given user was in the training set?
• Machine unlearning. What's genuinely deployable versus what's a paper with a toy benchmark. Be ruthless here.
• Differential privacy / cohort aggregation. What does the privacy budget actually cost you in NDCG?
• Retention windows. How much interaction history does the model measurably need, versus how much you're keeping by default? Data minimization is easiest to argue when you've measured the marginal value of older data.
• Consent propagation. When a user withdraws consent, what happens to precomputed recommendation caches, materialized candidate sets, and warm segments?
• Pseudonymization that survives joins. Whether your scheme actually resists re-identification given the other datasets you hold.

13.3 Configuration that matters for regulatory research

The firewall discipline is at its most valuable and most tempting to break here. The instinct to say "here's how we currently handle deletion, is it compliant?" produces a motivated report. Ask "what does the law require for deletion in vector stores?" and compare afterward.

13.4 What to hand counsel

The output should let a lawyer work in an hour rather than a week:

• Requirements traced to primary sources, with dates, not to secondary summaries
• An explicit "could not determine" section — jurisdictional gaps are the most important finding
• Conflicts between regimes surfaced as conflicts, not averaged away
• A staleness map that says which obligations to re-check and when
• Your specific open questions, framed as questions

Then keep it refreshed. The "overturned claim feeds a downstream artifact" warning is at its most valuable here: if a lawful-basis assumption in your PRD stops holding, you want the delta report to tell you, not an auditor.

14. Deep dive: security and adversarial research

Security is the other category I'd rank above component selection, and it's the one most consistently skipped until a review board forces it.

14.1 Why it fits the skill

Threat knowledge is published, adversarial, and perishable — the three properties the verification and freshness machinery exist for. It's also a domain where the model's training data is systematically incomplete: novel attack classes appear faster than they get absorbed.

14.2 Threat dimensions for a recommendation feature

Most engineers threat-model the service (authn, injection, rate limits) and skip the ranking system as an attack surface. Both belong in the run.

Manipulation and integrity

• Shilling / profile-injection attacks — coordinated fake interaction patterns that promote or bury items. Published attack models and detection approaches exist; this is a solved-ish literature that most teams have never read.
• Data poisoning of the training or feedback loop, including slow-drip attacks below anomaly thresholds
• Popularity and trending manipulation, and feedback-loop amplification
• Catalog enumeration via recommendation responses

Confidentiality and inference

• Embedding inversion — recovering source attributes from a vector (overlaps §13, but it's a security control question here)
• Membership inference — determining whether a user or item was in training data
• Cross-user leakage — inferring another user's behavior from changes in shared segments, co-occurrence surfaces, or "people also viewed"
• Model extraction — reconstructing your ranking function through systematic querying
• Cache and shared-segment poisoning

Access control

• IDOR and horizontal privilege issues on personalization endpoints — mundane, and the most commonly exploited

14.3 If there's an LLM anywhere in the pipeline

Add these dimensions explicitly:

• Indirect prompt injection via user-generated content, item metadata, or retrieved documents — the dominant risk class for retrieval-backed systems
• Tool-use boundary design and least-privilege for agentic components
• Output handling — treating model output as untrusted before it reaches a shell, a template, a query, or a browser

PR #2611 is itself the canonical worked example: a research brief was being interpolated into a double-quoted shell template, so $(), backticks, or a quote break inside researched or imported content could shape a command — amplified by a permission-skipping flag. The fix was structural, not a filter: briefs are written to a file and the template substitutes a skill-generated path, so untrusted text never touches a command line. Take that pattern wholesale into your own agent tooling. Filters on untrusted text fail; changing the channel so the text never reaches an interpreter doesn't.

14.4 Supply chain

• Model provenance — where the weights came from, what's actually verifiable
• Serialization risk in model artifacts (pickle-family deserialization remains a live RCE vector)
• Dataset provenance and whether training data carries obligations
• Dependency health — release cadence, maintainer count, open-issue and security-advisory trends
• CVE landscape for your serving stack, index, and inference runtime

14.5 Configuration for security research

14.6 Turning the report into work

The output shouldn't stop at a threat list. Convert it: threat → likelihood/impact for your deployment → control → story. Threats you consciously accept get written down as accepted, with the citation attached. That record is what makes the next security review fast, and it's the thing that's always missing when a reviewer asks "did you consider X?"

15. Deep dive: algorithm and technique-trend research

This is the weakest of the categories you raised — but it's rescuable if you reframe it.

15.1 First, disambiguate "EMA"

Two unrelated research problems share the acronym:

1. Exponential decay of user interest profiles — recency-weighted aggregation of a user's interaction vectors, so last week outweighs last year. A ranking-features question.
2. EMA teacher weights in self-supervised training — momentum encoders in the BYOL/DINO/MoCo family, where a slowly-updated copy of the network supervises the fast one. A representation-learning question.

They share nothing except the smoothing formula. A run that doesn't disambiguate produces a report that's half-relevant twice over.

15.2 Why "trends in algorithms like X" is the anti-pattern

No decision means no dimension pruning, which means unbounded scope, maximum fan-out, and an expensive encyclopedia entry you'll skim once. Convert it into a decision:

15.3 The dimension you must add by hand

Negative results, failed reproductions, and industry postmortems. Name it explicitly at the plan gate.

The literature is systematically positive-biased: papers report wins, and a survey that only aggregates claimed improvements is worse than nothing — it's confidently wrong in a specific, actionable direction. Recommender systems have a well-documented reproducibility problem in particular, where reported gains over properly-tuned simple baselines often fail to replicate.

This is also where "no conclusions from training data" pays off most, because model memory of an ML technique is weighted heavily toward the abstract of the original paper — the most optimistic sentence anyone ever wrote about it.

15.4 Read benchmark claims like an adversary

Require every reported number to carry:

• The dataset and its known idiosyncrasies
• The date — a 2023 retrieval benchmark describes a world that no longer exists
• Who ran it — self-reported vendor numbers flagged as such
• Tuning-budget parity — was the baseline tuned as hard as the proposed method? Usually not.
• Whether the gain survives at your scale and data regime, which is rarely the paper's regime

15.5 Know where research stops and your eval starts

For a parameter like an EMA half-life, research gives you the prior and the conventions — plausible ranges, how others parameterize per surface, what failure looks like when decay is too aggressive. It cannot give you the answer. Your offline replay against your own interaction logs decides it, and your A/B confirms it.

Running a deep engagement to pick a number your own data can answer in an afternoon is the clearest form of research-as-procrastination. Use quick for the prior, then go measure.

16. Applied: a multilingual translation feature

This is the higher-value case, because almost every decision is external.

16.1 Decision map

16.2 Traps this pack is built to catch

• Vendor-reported quality numbers. The source-quality card treats an aggregator as one publisher; verification at high cross-checks the claim classes the recommendation rests on. Insist that self-reported quality claims are marked as such.
• Language-coverage asymmetry. "Supports 100+ languages" is a marketing claim; per-pair quality varies by an order of magnitude. Make coverage-quality a named dimension, not a checkbox.
• Stale benchmarks. Set the freshness bar aggressively — 12 months, not 36.
• Pricing shape, not just price. Per-character vs. per-token vs. per-request vs. committed-use changes the ranking entirely at your volume. State your actual volume at the plan gate.

16.3 Suggested mode

Draft → Process → focused Run on the gaps:

1. Draft a prompt for whichever deep-research product you subscribe to. Vendor landscapes are exactly what hosted crawlers are good at.
2. Run it there; bring the report back.
3. Process it — original preserved in imports/, claims extracted, gaps flagged against the competitive pack.
4. Run natively on the two or three gaps (usually: your specific language pairs, and anything requiring internal or MCP-only sources).

16.4 Then refresh

Set a calendar reminder from the staleness map. MT pricing and model versions turn over on a roughly quarterly cadence. refresh the translation vendor research gives you a delta report — confirmed / changed / overturned — with a warning if an overturned claim underpins something you already shipped a decision on.

17. Deep dive: licensing, procurement and vendor risk

The most-skipped category, and the one that kills projects latest in the cycle — after integration, when unwinding is most expensive.

17.1 Model and dataset licensing

• Open weights ≠ open source. Many popular model licenses carry field-of-use restrictions, acceptable-use policies, monthly-active-user thresholds that flip commercial terms, or naming and attribution requirements. Several forbid using outputs to train competing models — which matters if you plan to distill.
• Dataset provenance. A permissively-licensed model trained on a non-commercial dataset is a real and common trap, particularly for multilingual and speech models.
• OSS license compatibility with how you actually distribute — SaaS, on-prem, embedded, and client-side each trigger different obligations.
• Output IP and indemnification. Who owns generated translations? Does the vendor indemnify you against third-party claims, and under what conditions do they void it?

Type: domain (or technical when it's mostly library compatibility). Preferred sources: the license texts themselves, model cards, official FAQs. Banned: summaries of licenses. Read the primary text; this is a category where paraphrase loses the operative clause.

17.2 Procurement and vendor assurance

If a vendor will process your data — an MT API, a hosted embedding endpoint — these determine whether you're allowed to use them at all, and they should be researched before you build against the API, not after:

• SOC 2 Type II / ISO 27001 status and scope
• DPA availability, SCCs, and transfer mechanism
• Sub-processor list and whether it's stable and notified
• Data residency and processing-location commitments
• Training-on-customer-data policy — the default matters, and so does whether opting out changes pricing or features
• Retention and deletion commitments, with actual timelines
• Breach notification SLA
• Exit terms and data portability — the exit cost is the real measure of lock-in
• Uptime SLA, rate limits, and what happens at the ceiling

Type: competitive. This is the research whose absence produces the sentence "legal won't approve the vendor we've already integrated."

17.3 Dependency and deprecation risk

Cheap to run, disproportionately useful:

• Release cadence and whether it's slowing
• Maintainer count and bus factor
• Open-issue and security-advisory trend lines
• Corporate backing, and whether the backer has a history of sunsetting
• Migration paths that already exist for people leaving

A quick preset run answers most of this and has saved more projects than any model comparison.

18. Best practices

18.1 Framing

1. Lead with the decision, not the topic. "Research embeddings" gets you an encyclopedia entry. "Pick the embedding model for our recommendation retrieval stage under these constraints" gets you a recommendation.
2. State your constraints as constraints. Latency budget, memory ceiling, language mix, volume, license posture, deploy target. These become matrix weights.
3. Name candidates as inclusions, never as the frame. Otherwise you get a confirmation exercise.
4. Declare your freshness bar when the field moves fast. Don't accept the pack default silently.
5. Pick the decision shape deliberately. select for choose-between, explore when you don't yet know the option space. Running select too early narrows prematurely.

18.2 At the plan gate

6. Read every dimension. This is your only hard stop. Delete dimensions that don't bear on the decision — each one costs a full fan-out.
7. Sanity-check the topology. Independent sub-questions → breadth. One contested question → depth. A lookup → straightforward. If it proposes six assistants for something simple, say so.
8. Match effort to reversibility. quick for a decision you can undo next sprint; deep + validation = high for something that becomes load-bearing.
9. Check the time estimate against your patience. Approving a 40-minute run you'll abandon at minute 12 wastes everything except what's already on disk.

18.3 During and after

10. Trust the firewall; don't defeat it. Resist the urge to paste your architecture doc "for context." Project context is legitimately framing; it is inadmissible as evidence. Feeding it in is how you get a report that agrees with you.
11. Chase answer-engine citations to primaries. If the report leans on an aggregator, that's one publisher, not three.
12. Read the "could not determine" section first. Gaps are more informative than confirmations.
13. Check the staleness map and act on it. Research that's never refreshed is research that silently becomes wrong.
14. Keep research.md in version control alongside the PRD it grounds. The provenance frontmatter is what makes the decision auditable in six months.

18.4 Cost and token discipline

15. Draft → Process is the cheap path. If you already pay for a deep-research subscription, the round-trip is one paste and it crawls wider per dollar.
16. Default to standard. The presets were rescaled downward because v1 was too slow and too token-heavy. Reach for deep deliberately.
17. Use deepen instead of re-running. Drilling one dimension is far cheaper than a fresh engagement.
18. Use refresh instead of redoing. It re-verifies only what's stale.

18.5 Hygiene

19. Turn on red_team for decisions with a strong prior. It's off by default. If you walked in already believing the answer, buy the adversarial pass.
20. Redact before quoting people. The user-voice pack now requires stripping usernames, handles, emails, and identifying URLs from verbatim quotes — carry that rule into anything you paste into a PRD.
21. Never shell-interpolate researched text. The PR's critical finding. Researched and imported content is untrusted input; pass it by file path, not on a command line — especially near any --dangerously-skip-permissions flag.

18.6 Domain-specific craft

22. Run the compliance and security gates in week one, not week ten. Their findings are design constraints. Discovered late, they're rewrites.
23. Tune source policy per domain, not once. Regulatory research wants regulators and bans law-firm blogs; security research wants NIST/OWASP/CVE and bans vendor marketing; academic research wants venues and bans press releases. The default policy is a compromise; override it.
24. Set freshness per claim class, not per run. Statute text, regulator guidance, and enforcement posture age at wildly different rates — and so do attack classes, advisories, and tooling.
25. Always add a "negative results and failures" dimension to any technique or trend research. Published literature is positive-biased and won't volunteer it.
26. Split regulatory research into requirements and implementation. One run answers "what must be true"; a second answers "how do we make it true in a vector index." Merging them makes both shallow.
27. Demand a "could not determine" section on compliance work. In regulatory research the gaps are the finding — an unresolved jurisdictional question is more actionable than five confirmed ones.
28. Convert security output into accepted-or-mitigated decisions, with citations attached. A threat list is not a deliverable; a threat register with dispositions is.
29. Know where research stops. Priors and conventions come from the literature; the actual parameter comes from your offline replay. Research that could be settled by an afternoon of measurement is procrastination.

19. Anti-patterns

20. Command cheat sheet

Legacy IDs (bmad-market-research, bmad-domain-research, bmad-technical-research) still work and forward with the type pre-set.

21. Transferable design lessons

Independent of whether you adopt Deep Recon, these generalize to any agentic system you build:

1. Consolidate near-duplicate prompt trees into one skill with data-driven variation. 5,136 lines → ~650 by turning three workflows into six ~25-line policy cards.
2. Keep the entry point lean; defer detail. ~4k → ~2.1k tokens by carving procedures into just-in-time reference files. Entry-point tokens are paid on every invocation.
3. Files-first, conversation-as-control-channel. Anything valuable goes to disk on arrival. Contexts die; disks don't.
4. Verify at landing, not at the end. A late pass degraded quality in field testing.
5. Mechanical work belongs in a tested script. Counting, cross-referencing, date math, slug generation.
6. Build an explicit bias firewall. Separate "what shapes the question" from "what counts as evidence," and enforce it at the subagent boundary.
7. Choose fan-out topology deliberately. Parallelism is a cost, not a virtue.
8. Treat tool output as untrusted input. File-based handoff over shell interpolation, protocol allowlists, escaping at the boundary.
9. Give artifacts a lifecycle. Staleness maps, delta refreshes, and downstream-impact warnings turn a document into an asset.
10. Single-writer rule for parallel agents. Fan out reads; serialize writes through the lead.

22. The epistemology underneath all of this

This section assumes no philosophy background. Every term is defined in plain language before it's used.

The PR has a section literally headed "Epistemics and reliability." That's not decoration — it's the honest label for what the whole design is. Read it this way and the mechanisms stop looking like a feature list and start looking like a single coherent argument.

22.1 What "epistemology" means

Epistemology is the branch of philosophy that asks: what is knowledge, and what makes a belief justified?

The classic starting point: knowing something requires three things.

1. It's true
2. You believe it
3. You have good reason — justification — for believing it

Miss any one and you don't have knowledge. If it's true but you have no grounds, you got lucky. If you have grounds but it's false, you're mistaken.

Why this matters here: an LLM produces sentences that satisfy #1 and #2 by accident and skip #3 entirely. It asserts things without holding beliefs, and its confidence is uncorrelated with whether it has grounds. It can tell you something perfectly true while having no justification whatsoever — the sentence just came out fluent.

There's a name for the case where you have a true, believed claim that's only accidentally right: a Gettier case (after a famous three-page paper from 1963). Picture a stopped clock that happens to show the correct time when you glance at it. You now believe something true, for a reason that gives you no actual grounds. Every uncited model output is a potential stopped clock.

Deep Recon's whole purpose is to bolt a justification layer onto a system that natively has none.

22.2 The core concepts, defined

22.3 Every mechanism is an epistemological commitment

Now the mapping. Each row is a design choice in the skill and the philosophical position it encodes.

22.4 The elegant one: the research firewall

This is the deepest idea in the design, and it's a direct implementation of a distinction from philosophy of science.

Context of discovery vs. context of justification (Hans Reichenbach, 1930s). These are two separate questions about any belief:

• Discovery: how did you come up with this idea? A hunch, a dream, a colleague's offhand remark, your existing assumptions — anything goes. There's no wrong way to generate a hypothesis.
• Justification: what makes it true? Here almost nothing goes. The grounds have to be independent of how you happened to think of it.

The classic illustration: the chemist Kekulé reportedly hit on the ring structure of benzene after daydreaming about a snake biting its tail. Perfectly fine as discovery. Utterly irrelevant as justification — the structure is right because of the evidence, not because of the dream.

The firewall implements exactly this split at a process boundary:

• Your project files, architecture docs, and briefs are allowed to shape which questions get asked — that's discovery, and your priors are a legitimate source of good questions.
• They are inadmissible as evidence — that's justification, and it has to come from outside.
• Subagents receive only their assignment. persistent_facts defaults to empty.

Why this is unusually good engineering: most bias mitigation is an instruction — "be objective," "consider alternatives." Instructions fail, because a system that wants to agree with you will find a way. This is architectural. The subagent cannot be biased by context it was never given.

The failure it prevents is the single most common one in agentic research: hand an agent your design doc and ask it to research alternatives, and it comes back explaining that your design is excellent. Not through deceit — through ordinary confirmation bias, which is what you get when the thing generating hypotheses also gets to grade them.

22.5 Where the epistemology is genuinely weak

Being honest about this matters more than admiring the design.

1. The independence assumption is shaky. Fan-out to multiple assistants borrows its logic from a result about crowds: if many judges each do slightly better than chance and their errors are independent, the majority is very reliable. But these subagents share a base model, a training corpus, and query craft. They are correlated witnesses, not independent ones. Six of them do not buy six times the reliability — they buy the same blind spot, six times, expressed differently.

2. Verification isn't independent either. The system checking a claim is the same system that produced it. That's a coherence check — does this hang together? — not corroboration, which requires a genuinely separate source. Useful, but weaker than it looks.

3. The web is not a neutral evidence base. Search ranking is itself an epistemic filter, shaped by commercial incentives. What is findable is not the same as what is true, and the gap is systematic rather than random. SEO-saturated domains — compliance, security vendors, "best X for Y" — are exactly where this bites hardest, which is why the banned-source policy is doing far more work than it appears to.

4. Citation prevents fabrication, not laundering. A well-cited report built on weak sources is more dangerous than an uncited one, because it wears the costume of justification. Rigor in the form can disguise rot in the content.

5. The plan gate is the least-examined step and the most consequential. You choose which dimensions count before any evidence exists. Every downstream mechanism assumes the question was well-posed. That's where the deepest bias enters — and nothing in the system checks it. Which is precisely why it's the one place your own judgment is irreplaceable, and why "read every dimension at the plan gate" is the most important practice in §18.

The honest summary: Deep Recon doesn't give you knowledge. It gives you auditable justification — a chain you can inspect and challenge. That's a real and unusual improvement over uncited fluency, and it's less than it can look like when the output is well-formatted and thoroughly cited.

22.6 Why this matters doubly for search and recommendation work

Here's the reflexive turn: search and recommendation systems are themselves epistemic technologies.

A ranking function is an implicit theory of relevance. A theory of relevance is an implicit theory of what is worth knowing. When you build a recommender, you are building a machine that shapes what people can come to know — you're operating on the justification side of other people's beliefs, at scale.

Which means the same concepts run in both directions:

That last row is the sharpest one, and it's worth sitting with. Deep Recon's firewall says: your context shapes the questions, never the answers. A recommendation system that lets a user's history shape what it presents as true — rather than merely what it surfaces — is doing the thing the firewall exists to prevent, to someone else, without their knowledge.

The discipline Deep Recon applies to your own knowing is the same discipline you owe your users about theirs. Provenance, defeasibility, calibrated uncertainty, source independence, visible criteria. In your research process they're hygiene. In your ranking systems they're ethics.

23. Worked walkthroughs for software engineers

Fidelity note. The session excerpts below are illustrative reconstructions. They show the shape of each interaction — the decision points, what you type, where you push back, what lands on disk. Exact prompt wording and gate formatting live in the skill's reference files and will differ in detail. The workflow, artifacts, and decision points reflect the documented design; the TOML key paths should be confirmed against your installed customize.toml.

23.0 Setup, once

npx bmad-method install          # select your IDE; deep-recon ships in core

Confirm it's there, then look at what you can change before your first real run:

/bmad-customize bmad-deep-recon

Two things worth setting on day one, before you've formed habits:

# _bmad/custom/bmad-deep-recon.user.toml   (personal, gitignored)

[workflow]
output_format = "both"      # md for the repo, html for sharing with non-engineers
validation    = "normal"    # raise per-run when the decision is load-bearing

Leave red_team off globally. Turn it on per-run, deliberately, when you notice you already believe the answer.

Walkthrough A — Native Run: choosing an embedding model

Scenario. You own multilingual search and recommendation. Retrieval runs on OpenSearch with HNSW. You need to commit to an embedding model for the recommendation retrieval stage and live with it for roughly a year, because re-embedding the corpus and rebuilding the index is a multi-week project.

This is the gate everyone runs. It's genuinely the least valuable of the gates — but it's the best one to learn the mechanics on, because the feedback loop is short.

A.1 The invocation, and the fork in the road

> /bmad-deep-recon

Deep Recon opens the floor and, on a bare research ask, states the Draft-vs-Run trade once and remembers your answer for the session. For this one, Run is right: you'll want follow-up rounds on contradictions, and some sources are technical enough that you'll want to chase citations interactively.

Now the part that determines everything downstream.

❌ What most engineers type:

research the best embedding models for multilingual search

What comes back: a competent encyclopedia entry. Every dimension is in scope because nothing was pruned. Maximum fan-out, maximum tokens, and a report that ranks models against generic criteria you don't share. You'll skim it once and decide on vibes anyway.

✅ What to type instead:

I need to pick an embedding model for the retrieval stage of our
recommendation system. Decision horizon ~12 months — re-embedding the
corpus is a multi-week project, so this is expensive to reverse.

Constraints:
- Content is multilingual; the mix is roughly [your actual mix]
- Retrieval stage budget is 200ms p99, end to end
- Index memory has a hard ceiling; dimensionality is a real cost, not a
  preference
- Self-hostable strongly preferred; API-only is a significant negative
- Must be usable commercially without a revenue-threshold clause

Include these candidates — but do not treat the list as the frame, and
surface anything stronger: [3-5 named models].

Type: technical, select shape. Effort: deep. Validation: high.
Freshness: benchmark claims older than 12 months are reported as history,
not as current fact.

Four things are doing work there:

A.2 The plan gate — the only place your attention is irreplaceable

An illustrative gate for the above:

DECISION
  Select an embedding model for recommendation retrieval; 12-month horizon,
  high reversal cost.

DIMENSIONS (6)
  1. Multilingual coverage and per-language retrieval quality
  2. Dimensionality vs. index memory and HNSW build/query cost
  3. Published retrieval benchmarks (MTEB/BEIR family) with dataset caveats
  4. Inference latency and throughput; self-host vs. hosted
  5. License terms, commercial-use restrictions, model provenance
  6. Maintenance signals: release cadence, backing, deprecation risk

TOPOLOGY   breadth-first (dimensions are largely independent)
EFFORT     deep — 6 assistants / 12 sources per round / 3 rounds
VALIDATION high; red_team off
FRESHNESS  benchmarks 12mo · license 24mo · maintenance 6mo
ESTIMATE   ~35-45 minutes

Approve, or tell me what to change.

What to actually do here — this is the whole skill:

1. Delete dimensions that don't bear on the decision. Each one costs a full fan-out. If you'll self-host regardless, dimension 4 collapses to "self-host latency only" — say so. Cutting one dimension at deep saves roughly 15% of the run.
2. Add what's missing. Two things are absent above and belong: fine-tuning and adaptation cost (if you'll adapt to your domain, a model that resists adaptation is disqualified regardless of zero-shot numbers), and how each model behaves under the filtered-search patterns your recommender actually uses. Benchmarks measure unfiltered top-k; your production path is filtered.
3. Sanity-check the topology. Breadth-first is right here — these are independent questions. If it had proposed depth-first, that would be a signal the decision was framed as one contested question rather than six separable ones.
4. Check the estimate against your patience. 40 minutes is real. If you'll wander off at minute 12, drop to standard now. Files-first means you keep what landed, but you'll have a partial report you don't trust.

A realistic reply:

Approve with changes:
- Drop dimension 4's hosted-API sub-question; we self-host, full stop.
- Add: fine-tuning/adaptation cost and whether the license permits it
- Add: behavior under filtered ANN search, not just unfiltered top-k
- Keep effort at deep

A.3 During the run

You'll see digests landing and report sections committing per dimension, because everything hits disk on arrival. Two things to watch:

• Aggregator pileup. If several digests trace back to the same summary site, that's one publisher wearing several hats. Say so: "dimension 3 is leaning on aggregators — chase the primary benchmark repos."
• Round-two assignments. Contradictions from round one become round two's work. If two sources disagree on a latency figure and round two isn't chasing it, flag it. Disagreement is the highest-value lead in the run.

A.4 What lands on disk

_bmad/planning/embedding-model-selection-2026-07/
├── briefs/
│   ├── multilingual-coverage.md
│   ├── dimensionality-index-cost.md
│   └── ...
├── digests/
│   ├── d01-mteb-multilingual-subsets.md
│   ├── d02-hnsw-memory-scaling.md
│   └── ...
├── memlog                          # append-only; claim tally lives here
└── research.md                     # the canonical cited report

research.md is the artifact. Everything else is the audit trail — and the reason a run that dies at minute 30 resumes instead of restarting.

A.5 Reading the report — where to look first, in order

1. "Could not determine." Read this before the recommendation. If per-language quality for your two most important languages is in here, the selection matrix is weaker than it looks and you should say so out loud in the ADR.
2. The selection matrix. Check that the weights are your constraints. If it weighted "ease of getting started" heavily, it defaulted to generic criteria and you under-specified at the plan gate.
3. Self-reported vs. independent numbers. Every vendor-run benchmark should be flagged. If they aren't, ask.
4. The staleness map. Turn it into calendar entries the same day. This is the step everyone skips and it's what makes the artifact a living asset rather than a snapshot.
5. The recommendation, last. By now you know how much weight it can bear.

A.6 When the matrix disagrees with you

This happens, and it's the most useful moment in the process. Two legitimate responses:

• Your constraint was wrong or unstated. Fix the weights and say why in the ADR. "We overrode the matrix because index memory is a harder ceiling than the weighting reflected" is a fine sentence.
• Your prior was wrong. Rarer, more valuable.

What's not legitimate is re-running with a different framing until you get the answer you wanted. If you're tempted, that's the moment to turn red_team on instead.

A.7 Handoff

research.md carries metadata frontmatter that downstream skills consume directly:

/bmad-prd

The PRD reads the summary without reprocessing the digests. In your repo, put the report next to the ADR it grounds:

docs/decisions/0014-embedding-model.md          # the decision
docs/decisions/0014-research.md                 # the evidence

Realistic cost: ~40 minutes wall clock, most of it unattended. Compare against the multi-week cost of re-embedding after a wrong pick.

Walkthrough B — Draft → Process: the MT vendor landscape

Scenario. You need translation for the multilingual feature. Six plausible vendors, opaque and structurally different pricing, quality claims that are all self-reported.

This is the textbook Draft case: a broad public sweep over commercial sources, which is exactly what hosted deep-research products are good at, and which you're probably already paying for.

B.1 Draft

> draft a deep research prompt for Gemini: choosing a machine translation
  vendor for [your language pairs], ~[N] million characters/month, EU +
  Canada data residency requirements, glossary/do-not-translate support
  required. Competitive type, select shape.

You get back a prompt carrying the competitive pack's craft — pruned dimensions, freshness bars, source policy, and a hard citation demand, tuned to the tool you named.

Check it before you paste. Two things:

• Does it demand citations with publication dates? If the citation demand is soft, the report will be soft.
• Does it name volume and language pairs? Pricing rankings invert with volume, and "supports 100+ languages" is a marketing claim that says nothing about your specific pairs. If those aren't in the prompt, add them by hand.

B.2 Round-trip, then Process

Paste into your subscription tool, let it crawl, save the output.

> there's a research report at ~/Downloads/mt-vendors.pdf, process it

What Process does, and why each part matters:

B.3 The gap report is the point

Typical output from the gap check on a vendor sweep:

COVERED
  pricing, language coverage, published quality claims, API surface

GAPS (not covered by the imported material)
  - sub-processor lists and data residency commitments
  - training-on-customer-data defaults and opt-out terms
  - glossary / do-not-translate feature parity across vendors
  - exit terms and data portability
  - per-pair quality for [your two lowest-resource pairs]

Note what the gaps are: every single one is a procurement or per-pair specific question. Hosted research tools crawl broad commercial surfaces well and are poor at the narrow, contractual, and specific. That's the division of labour to internalize.

B.4 Targeted Run on the gaps only

> run a focused research pass on the gaps only — sub-processors,
  training-on-customer-data terms, glossary parity, exit terms.
  Type competitive, effort standard, validation high.

Small, cheap, and it lands in the same run folder — the slug is deterministic across the draft→process→refresh lifecycle, so the report is one artifact, not three.

Net cost: one paste, one file drop, one 12-minute run. Your subscription paid for the expensive crawling.

Walkthrough C — The compliance gate, done without fooling yourself

Scenario. Design freeze is in two weeks. You need to know whether the deletion path survives a right-to-erasure request against a vector index.

C.1 The framing trap, shown concretely

❌ Here's our retention and deletion design [paste]. Is it GDPR compliant?

This defeats the firewall by hand. You've supplied the conclusion as context, and you'll get a well-cited report explaining why your design is fine. It will be persuasive. It will be worthless.

✅ What does GDPR Art. 17 require when personal data has been embedded into
   a vector index that does not support hard delete? Include regulator
   guidance on derived data and on bounded-but-delayed deletion.
   Type: domain. Validation: high. red_team on.

Then compare your design against the requirements yourself, afterward. That ordering is the entire discipline.

C.2 Source policy override — do this before running

Regulatory research is the clearest case for overriding the default source policy, because the SEO layer in this space is thick and sales-motivated:

# _bmad/custom/bmad-deep-recon.user.toml

[[workflow.source_policies]]
code = "regulatory"
preferred = [
  "eur-lex.europa.eu", "edpb.europa.eu", "ico.org.uk",
  "priv.gc.ca", "cai.gouv.qc.ca",
]
banned_kinds = ["law-firm marketing", "compliance-vendor content marketing"]

[workflow.freshness.regulatory]
statute     = "36mo"
guidance    = "12mo"
enforcement = "6mo"

Confirm the exact key paths against the shipped customize.toml; the shape and the intent are what matter.

C.3 Two runs, not one

Run 1 (domain) — what the law requires. Erasure scope for derived data, whether embeddings are personal data, Art. 22 threshold for your ranking surface, Quebec Law 25 automated-decision notice, transfer posture for inference calls.

Run 2 (technical) — how to satisfy it in your stack. Real deletion latency under HNSW soft-delete plus segment merge; whether bounded-but-delayed deletion is defensible; consent propagation to precomputed candidate sets and warm caches; embedding inversion as a residual risk.

Merging these produces a report that's shallow on both, because they want different sources and different freshness windows.

C.4 What you hand counsel

Not the whole report. A one-pager built from it:

• Requirements, each traced to a primary source with a date
• Our design's position on each — your comparison, done after the fact
• "Could not determine", verbatim. In compliance work the gaps are the finding
• Three specific questions you need a lawyer to answer

An hour of counsel time instead of a week. And when the auditor asks "how did you conclude this?", the answer is a file with publishers and access dates, not a recollection.

Walkthrough D — Threat-modeling a ranking surface

Scenario. The recommendation feature ships to authenticated users next quarter. Security review is a launch gate.

D.1 The run

> technical research: attack surface of a personalized recommendation
  ranking system serving authenticated users. Cover manipulation of
  rankings, poisoning of the interaction feedback loop, inference attacks
  against user embeddings, cross-user leakage through shared segments,
  and model extraction. Include documented incidents, not just papers.
  Validation: high. red_team on.

red_team on is deliberate. You are walking in believing the system is basically safe — buy the adversarial pass.

"Include documented incidents, not just papers" is the other lever. Academic attack papers describe what's possible; incident writeups describe what's happened, which is a much better guide to what to fix first.

D.2 The transformation that makes it useful

A threat list is not a deliverable. Convert it, in the same session:

Accepted risks get written down with the citation attached. That record is what makes the next security review fast, and it's exactly what's missing when a reviewer asks "did you consider X?" and the honest answer is "probably, in a meeting."

D.3 If there's an LLM in the pipeline

Add indirect prompt injection via item metadata and user-generated content as a first-class dimension, and take the structural lesson from PR #2611 itself: they didn't filter untrusted text out of a shell command, they changed the channel so it never reached one. Briefs went to a file; the template substitutes a skill-generated path. Filters on untrusted text fail eventually. Removing the interpreter from the path doesn't.

Walkthrough E — Refresh, three months later

> refresh the embedding model research

Only stale claims get re-verified, per the staleness map. You get a delta:

CONFIRMED (11)   license terms, dimensionality/memory figures, ...

CHANGED (3)
  [4] Model B latency benchmark — improved ~20% after a runtime release
  [7] Model C pricing — restructured to committed-use tiers
  [9] Model A release cadence — slowed; last release 5 months ago

OVERTURNED (1)
  [12] Model D commercial-use terms changed; the revenue threshold that
       made it viable for us no longer applies as documented

⚠  Claim [12] is referenced by:
       docs/decisions/0014-embedding-model.md

That warning is the whole reason the lifecycle exists. A licensing assumption underpinning a shipped decision moved, and you found out from a 6-minute refresh rather than from procurement, or a lawyer, or a blog post someone forwards you.

What you do: re-open the ADR, note the change, decide whether it changes anything. Often it doesn't. The value is that the question got asked at all.

Walkthrough F — Deepen one dimension

You committed to a model. Now you need the fine-tuning story properly, and only that.

> deepen the fine-tuning and adaptation dimension

Drills one dimension without re-running the other five. Minutes, not tens of minutes. This is the command that makes research iterative — you stop trying to front-load every question into one enormous engagement and instead pull threads as they become load-bearing.

Rule of thumb: deepen when the question was in scope but under-answered. A fresh run when the question is genuinely new.

Walkthrough G — Headless refresh in CI

The headless JSON contract means the staleness map can run itself. A quarterly job, roughly:

# .github/workflows/research-refresh.yml
on:
  schedule: [{ cron: "0 6 1 */3 *" }]      # first of the month, quarterly
jobs:
  refresh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Refresh decision research
        run: |
          bmad-deep-recon refresh \
            --headless --output-format md \
            --workspace docs/decisions/research/
      - name: Open an issue if anything was overturned
        run: ./scripts/alert-on-overturned.sh

Headless runs present canonical markdown only — output_format = auto handles that without configuration. Alert on overturned and on changed that touches a referenced claim; ignore confirmed. Otherwise you've built a quarterly notification everyone mutes by the second quarter.

This is the cheapest high-value automation in the whole system: decision rot, detected without anyone remembering to look.

Walkthrough H — The anti-walkthrough

Worth seeing the failure mode concretely, because it's what a first run usually looks like.

> research recommendation system best practices

What the plan gate proposes: eleven dimensions, breadth-first, deep, ~55 minutes. Nothing was pruned, because no decision was stated and therefore nothing could be pruned.

What you get: a well-cited, genuinely accurate survey of recommender systems. Collaborative filtering, content-based, hybrids, cold start, evaluation, MLOps. All true. All findable in any textbook. None of it weighted to a choice you face.

Cost: ~55 minutes and a large token spend, for something you skim once.

What went wrong, precisely: the plan gate is a pruning device. It prunes dimensions against the decision. No decision means no pruning function, so the run is unbounded by construction. The mechanism didn't fail — it was handed nothing to work with.

The fix is one sentence, always the same shape: "I am choosing between X, Y and Z, under constraints A, B and C, and I'll live with it for N months."

If you cannot write that sentence, you're not ready to research. You're ready to brainstorm — which is a different skill, and the right one for that moment.

23.9 Team integration patterns

Keep the research in the repo, next to the decision.

docs/decisions/
├── 0014-embedding-model.md          # ADR: what we chose and why
├── 0014-research.md                 # the evidence, with provenance
├── 0015-mt-vendor.md
└── 0015-research.md

The ADR states the decision and the reasoning. The research file carries the citations, dates, and staleness map. Six months later the ADR tells you what, and the research file tells you whether it still holds.

Review research in PRs. A research report in a pull request gets the same treatment as code: someone checks whether the plan-gate dimensions were right, whether the weights match the team's actual constraints, and whether the "could not determine" section was read rather than skipped. This catches motivated framing better than anything else, because the person reviewing didn't want the answer.

Onboarding. A new engineer reading 0014-research.md learns why the stack looks the way it does, from sources, in twenty minutes. Compare with the usual mechanism: asking whoever's been there longest and getting a partly-reconstructed memory.

Don't let it become theatre. Research that's produced, filed, and never refreshed or contradicted is a compliance ritual. The signal that it's real: someone, at some point, overrode a recommendation and wrote down why.

23.10 Calibration — what to spend where

Two patterns in that table worth naming:

• red_team is on exactly where you have a prior. Nobody walks into a privacy or security review neutral — you walk in believing you're fine. That's the condition the adversarial pass exists for.
• The cheapest runs are the most consistently underused. A six-minute dependency-health check has probably prevented more grief than any model comparison ever run.

24. Sources

• BMAD-METHOD PR #2611 — "feat(core): consolidate research trio into bmad-deep-recon", merged 23 Jul 2026 — https://github.com/bmad-code-org/BMAD-METHOD/pull/2611
• docs/explanation/deep-recon.md — https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/explanation/deep-recon.md
• docs/how-to/customize-bmad.md (config layering and merge rules) — https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/how-to/customize-bmad.md

Applied guidance in §12–§17, the epistemological analysis in §22, and the walkthroughs in §23 are my analysis, not sourced from the BMAD docs. The named philosophical concepts (Gettier, Popper, Reichenbach, Condorcet) are standard terms of art in epistemology and philosophy of science.