Walkthrough: researching the next feed, end to end

Time to do it. The team owns the capstone feed, the quarter starts in two weeks, and four candidate directions are on the table, every one of them raised by our own instrumentation:

One team, one quarter, one choice. This chapter runs the decision through the four phases of Chapter 31, using the research skill of Chapter 32, and then does the thing the tables only promised: it follows one finding from a research report all the way down to a story a dev agent implements, through every persona in between.

A note on the outputs below: BMAD drives an LLM, so its artifacts vary run to run, and the excerpts here are illustrative in form (matching v6's documented templates), while the research findings inside them are real, verified sources you can check in References. Where a snippet is a command you can type, it is exact.

Stage 0: ground truth first (Analysis, brownfield)

Ours is a brownfield project, so before any research, Mary needs the codebase to be a source she can cite instead of imagine:

/bmad-document-project
/bmad-generate-project-context

The first scans newsreco/ and writes orientation documents; the second distills the conventions and constraints into project-context.md (temporal splits only, profile updates idempotent under replay, the deletion SLO, required evaluation guardrails). Now Mary's research questions and John's PRD refer to the actual modules, and the firewall of Chapter 32 has something honest to keep research separate from. Do not browse the literature yet if the team cannot even define a "valid view"; that unknown lives inside the repo, not in a paper.

Stage 1: frame before you search

The most common research failure is not bad searching; it is researching an unframed question. BMAD puts two skills in front of the search box.

bmad-brainstorming runs a facilitated session; in its Facilitator stance the agent is explicitly forbidden from contributing ideas ("you never supply ideas"), it only elicits and structures yours. Twenty minutes turns four vague candidates into sharper statements of what we do not know.

bmad-forge-idea then pressure-tests the favorite through Socratic questioning. Ours went in as "add image embeddings to the profile" and came out humbler:

forged-idea.md (excerpt, illustrative)

Idea (revised): image signal may improve CARD RANKING even if it does not
improve PROFILES; the two claims have different evidence and different cost.

Weakest assumption (round 2): "thumbnail content reflects story content."
Our Chapter 27 rubric has a headline-image-coherence criterion precisely
because this is often false.

Kill criterion: if a text-strong baseline erases the image lift offline,
stop; serving cost is not justified by parity.

That kill criterion is the gift. Forge takes exactly one idea and interrogates it until it is hardened (with a named weakest assumption and a falsifiable stop) or dead. The session, plus the brainstorm, reduces to three research questions:

• Q1: do image embeddings on cards lift engagement, against a strong text baseline?
• Q2: which EMA half-life (or profile shape) fits news interest drift?
• Q3: does MMR-style diversity re-ranking cost short-term clicks?

Forging before searching is what keeps research affordable: without it, Deep Recon would fan out on "image embeddings, tell me everything," at several times the cost and half the relevance. Chapter 34 makes the same point with numbers: sharper questions, better allocation.

Stage 2: the research

Now hand the three questions to bmad-deep-recon. The mechanics are Chapter 32's subject; here we watch it used. Q1's literature is broad and public, so we Draft a prompt and rent a crawler:

/bmad-deep-recon draft an academic-lit research prompt about image
embeddings in news-card ranking vs a strong text baseline (Q1), for Gemini

The generated brief.md carries the pack's craft into the outside tool (primary sources only, venue + year on every claim, industrial deployments outrank offline-only papers, negative results reported), you run it on a flat-rate subscription, and the report comes back through Process mode. Q2 and Q3 we Run natively, approving the plan gate (breadth-first, standard preset, three dimensions) before anything crawls. The run grows research.md as material lands:

research.md (excerpt — illustrative format, real checkable findings)

## Q1: image signal in ranking
- Visual features folded into ranking have a decade of positive evidence,
  from VBPR's CNN features in a BPR factorization [3] to Pinterest's unified
  visual embedding, validated offline, in user studies, AND in an online A/B
  [4]. Confidence: high for "signal exists."
- CAUTION (contested): lift against *strong text baselines* is thinner and
  several results predate modern text embeddings. Recommend own ablation
  before committing serving cost. Confidence: medium. [8]

## Q2: profile shape and recency
- Pinterest's PinnerSage argues AGAINST a single averaged user vector:
  averaging disparate interests lands the vector in a region matching none
  of them; they cluster a user's items and keep one medoid per cluster [5].
  Directly challenges our single-EMA design (Chapter 5).
- Recency weighting itself is well anchored: time-decayed weighting of
  interactions goes back to time-weighted CF [6]. Our half-life is the right
  *kind* of knob; its value is untested.

sources: [3] He & McAuley, AAAI 2016 · [4] Zhai et al., KDD 2019 ·
[5] Pal et al., KDD 2020 · [6] Ding & Li, CIKM 2005

and it ends, as Chapter 32 requires, with a staleness map: the "engagement lift from visual features" claim is empirical and aging (re-check before we commit), the PinnerSage multi-embedding design is architectural and stable, and "a strong text baseline erases the lift" is contested until our ablation settles it. Notice what the firewall bought: outside assistants established that decay and multi-interest profiles are credible patterns; not one of them was allowed to claim our users' interests decay in seven days. That number comes from telemetry or an experiment, never from a borrowed paper.

Stage 3: research outputs an experiment, not a constant

The report's job is not to declare a winner; it is to locate the uncertainty precisely enough that the first story becomes the cheap test that settles it. So the synthesis ends in a decision table, not "further study is needed":

Adopt one EMA if:
- it beats a tuned last-N baseline on temporal replay in the target segments;
- lift is robust across at least two adjacent half-lives;
- diversity and freshness guardrails do not regress;
- incremental update and deletion meet the serving SLO.

Prefer multi-interest profiles if:
- EMA lift saturates while multi-topic users remain the failure segment;
- clustered K>1 wins the same replay without unacceptable storage/latency.

Stop personalizing if:
- neither family beats popularity + recency after leakage-safe tuning.

and it proposes the smallest matrix that can separate the hypotheses, because "add EMA" hides at least six assumptions (a view is positive feedback; one vector can represent a person; newer views matter more; exponential decay is the right curve; one half-life fits everyone; offline next-click predicts a better feed):

evaluated on a chronological replay (build the profile from events strictly before cutoff $t$, retrieve only items eligible at $t$, predict the next interaction), because a random split leaks future interests into the past and flatters slow-decay profiles. For an event $i$ of age $a_i$ the half-life parameterization keeps the weight interpretable, $w_i = 2^{-a_i/h}$, so $h$ is the age at which an event keeps half its weight, and the profile is a confidence-weighted, time-decayed average, $p_u = \frac{\sum_{i} q_i w_i s_i}{\sum_{i} w_i s_i}$, which cleanly separates time decay $w_i$ from feedback quality $s_i$.

Stage 4: evidence becomes spec

Here is the payoff of researching inside an SDD tool rather than in a loose doc: the output has a customer. Watch one finding, PinnerSage's argument against a single averaged vector, ride the whole chain, each hop a named persona and skill with a human review in between:

research.md            brief.md                prd.md                   ARCHITECTURE-       story-profile-
 [5] PinnerSage:   ->   "Opportunity: our  ->   FR-7: profile store  ->  SPINE.md        ->  ablation.md
 single averaged        single-EMA profile      MUST support K taste     profile item         "AC-2: offline
 vector matches         may under-serve         vectors per user;        schema: K vectors    recall@10 for
 no interest;           multi-interest          OQ-3: K=1 vs K=3         + per-vector         K=3 clustered
 cluster + medoid       users (evidence:        ablation gates the       decay params         vs K=1 EMA on
 per cluster"           research.md [5])"       epic                     (extends ch. 28)     the MIND sample"
   Mary/Deep Recon        Mary: bmad-product-      John: bmad-prd          Winston:             John: bmad-create-
                          brief                                            bmad-architecture    epics-and-stories

• Mary's bmad-product-brief consumes the research summary directly (the docs are explicit: downstream skills read the metadata, no reprocessing) and writes brief.md, framing PinnerSage's finding as an opportunity rather than a fact to be re-derived.
• John's bmad-prd turns the brief into functional requirements and keeps a decision log; FR-7 makes the profile store carry K taste vectors, and open-question OQ-3 (K=1 vs K=3) is explicitly gated by the ablation.
• Winston's bmad-architecture answers FR-7 with a schema change to the Chapter 28 profile item: K vectors plus per-vector decay parameters, "favoring boring technology," reusing the single-item DynamoDB design so deletion stays one DeleteItem.
• John's bmad-create-epics-and-stories cuts it into stories, and the first one is not "implement EMA in production." It is the ablation: arms A-E on the leakage-safe replay, with forged-idea.md's kill criterion as an acceptance criterion. The production write path comes only after that story returns a decision.

That is what "research sits at the head of spec-driven development" means in practice: not a phase you complete and file, but the supplier of every claim the spec makes, with citations that survive review and a staleness map that says when to look again.

Stage 5: the gate, then the build (Solutioning → Implementation)

Before any dev agent runs, bmad-check-implementation-readiness grades the whole chain PASS / CONCERNS / FAIL: is every FR traceable to evidence or a gated experiment, does the architecture answer every constraint, does each story have acceptance criteria? A CONCERNS on "the ablation story has no defined guardrail metric" is caught here, as a paragraph, not in code review.

On PASS, Implementation runs the loop: bmad-sprint-planning initializes sprint-status.yaml, bmad-create-story emits the next focused story, Amelia's bmad-dev-story implements it test-first ("file paths and AC IDs are my vocabulary"), and bmad-code-review grades the result. The story here builds the replay harness and runs arms A-E; its "output" is a decision, which flows back up through bmad-prd's Update intent and closes OQ-3. The traceability the whole chain preserves:

source [5] / internal replay
  -> claim R-17 (3d and 7d EMA tie for active users)
  -> product decision D-4
  -> PRD FR-12 / NFR-7
  -> architecture decision ADR-profile-3
  -> story EMA-2 / AC-4
  -> acceptance test run

Every arrow is a file with an owner, a consumer, and a review, which is why a fresh chat per workflow loses nothing: the contract is on disk, not in scrollback.

The supporting cast, and the order they run in

Half a dozen skills produce something you could loosely call "insight," which is why first-timers run the wrong one and get a session that feels productive and changes nothing. They separate on two axes: which way the funnel points and where the truth comes from.

Don't be confused: brainstorming vs. forge-idea is the pair people mix up most, and the test is cardinality. Brainstorming takes zero ideas and produces many; it refuses (in Facilitator stance) to judge them. Forge takes exactly one idea and interrogates it. Running brainstorming on an idea you have already chosen produces decoration; running forge before you have alternatives produces a rigorous defense of the only thing on the table. Elicitation vs. recon is the same distinction one level up: both gather facts you lack, but elicitation's source is a person in your org and recon's is the world. If a named colleague could answer it in ten minutes, it is an elicitation question, not a research question.

The order this chapter followed is the default, and each step makes the next cheaper:

0 document-project   ground truth first (brownfield only)
1 brainstorming      widen: get real alternatives on the table
2 forge-idea         narrow: weakest assumptions + kill criteria
        |            forge's weakest assumptions ARE recon's questions
3 deep-recon         test the surviving assumptions against the world
4 product-brief      consolidate, with citations
5 party-mode         pre-mortem the brief before the PRD spends on it

Deviate deliberately: if leadership already fixed the candidate, skip brainstorming and start at forge (you are locating risk, not choosing); if you know too little to pressure-test, run a Quick recon first to learn the vocabulary, then forge, then the real recon; point party mode at a draft, never a blank page; reach for the CIS module when the built-in brainstorming feels thin; swap bmad-prfaq in for the brief if your leadership reads Amazon-style working-backwards docs; and pull in TEA (Murat) to turn research-identified risks into a test strategy before implementation.

Best practices for the whole cycle

1. Frame before you search. A question with a kill criterion is worth ten open-ended prompts.
2. Fresh chat per workflow. State lives in files; mixing three workflows in one chat is how documents contradict each other.
3. Match the mode to the money. Draft when you have flat-rate engine subscriptions; Run when you need the firewall and the staleness map; Process to unify whatever came back.
4. Respect the plan gate. Sixty seconds reading the proposed sub-questions is the highest-value review in the cycle.
5. Verify the load-bearing claims adversarially. For any claim the PRD will cite, spawn a skeptic to refute it against the primary source. Our own research for this book caught real errors this way: version numbers, renamed commands, retired products.
6. Negative and contested results go in the report. The text-sufficiency caution above is the most valuable line in research.md; a report with only supporting evidence is advocacy.
7. Let research output experiments, not just conclusions. The best finding is "here is the cheap test that settles it."
8. Keep the staleness map honest. Date every claim; refresh on the map's schedule, not on anxiety.
9. Version the documents like code. research.md, brief.md, prd.md live in the repo, reviewed in PRs. A spec that lives in a chat scrollback does not exist.
10. Skip the ceremony when a prototype is cheaper. If the experiment costs less than the literature sweep, the experiment is the research; bmad-quick-dev exists for exactly this.

The walkthrough treated the machinery as given: subagents fanned out, claims landed in a report, and "which question gets the remaining budget" was decided by feel. Each hides real structure, and the next chapter opens it: when parallel agents help and when they burn tokens, how a pile of claims becomes a queryable graph, and what decision theory says about spending research hours. 👉