Operations cookbook

A reference of recipes for the things you actually do day to day: generate and compare ideas, drive the planning documents, create epics and stories, run research, and (the part every guide skips) undo, revert, and recover from mistakes. Each recipe is goal, exact commands, and the notes that keep you out of trouble. Skills run in a fresh chat unless noted; commands are exact.

On this page

• Generating and comparing ideas
• Planning documents
• Solutioning: architecture, epics, stories
• Implementation
• Fixing mistakes: undo, revert, recover
• Research
• Maintenance
• Hands-on: break something, then recover three ways
• Under Claude Code: the host commands behind each recipe

Generating and comparing ideas

Generate a lot of ideas from scratch.

bmad-brainstorming
> Topic: ways to cut our onboarding drop-off

The coach pulls ideas out of you with a 60+ technique library, shifts creative domain every 10 ideas to avoid clustering, and targets 100+ before organizing. Output: brainstorm.html plus an optional brainstorm-intent.md for downstream skills. The magic is in ideas 50 to 100, so do not stop at the first dozen.

Run several ideas in parallel and pick one. There are three distinct moves, and choosing the right one saves days:

• Widen, then narrow each: brainstorm to get the candidates, then run bmad-forge-idea on each serious contender to harden or kill it. Forge takes exactly one idea, so run it once per candidate.

• Debate them together: bmad-party-mode puts your agents (PM, Architect, Dev, UX) in one room to argue the tradeoffs. Use --mode subagent for honest, independent opinions rather than one model voicing everyone.

  /bmad-party-mode --mode subagent "compare build-vs-buy for our search feature"
  

• Choose between named options on evidence: bmad-deep-recon in its select shape produces a weighted decision matrix you can re-weight.

  bmad-deep-recon
  > help me choose between Postgres full-text, OpenSearch, and Typesense for our search
  

Pressure-test the favorite before spending on it.

bmad-forge-idea
> Idea: replace our REST API with GraphQL. Goal: decide whether it deserves a spike.

An interrogator drives one question at a time in dependency order, brings two voices to every branch, and lands the idea as Hardened (writes forged-idea.md), Killed (records the cause of death), or Clearer. Reach for the adversarial on this gear to attack a specific claim to destruction while you defend it.

Refine an output that feels shallow. At any workflow pause, or on demand:

bmad-advanced-elicitation

It offers five best-fit methods for the content (pre-mortem, first principles, inversion, red-team, Socratic). Pre-mortem is the reliable first pick for any spec or plan; it finds gaps a normal review misses.

Planning documents

Pick the entry into planning. Product Brief is collaborative discovery (the gentle path); PRFAQ is Amazon Working Backwards (a gauntlet that stress-tests the concept customer-first).

bmad-product-brief        # brief.md + addendum.md, a 1-2 page summary
bmad-prfaq                # prfaq-{project}.md, press release then hard questions

Write, update, or validate a PRD. One skill, three intents; state the intent or it will ask.

bmad-prd
> Create a PRD for the saved-filters feature      # coached discovery -> prd.md + .memlog.md
bmad-prd
> Update the PRD: legal now requires audit logging  # reconciles, surfaces conflicts FIRST
bmad-prd
> Validate the PRD against our checklist            # HTML findings report, no edits

Update is the correct tool when requirements change. It reconciles the change against the existing PRD and surfaces conflicts before applying anything, which is how you avoid two documents that quietly disagree.

Design the UX (when it matters).

bmad-ux     # DESIGN.md (visual tokens) + EXPERIENCE.md (behavior, states, journeys)

Distill any intent into a machine contract.

bmad-spec
> distill this PRD (and the Slack thread) into a spec, then break it into stories

Produces SPEC.md (a five-field kernel: Why, Capabilities, Constraints, Non-goals, Success signal) plus companions, and on request an ordered stories.yaml that the autonomous loop can dispatch.

Solutioning: architecture, epics, stories

bmad-architecture                    # ARCHITECTURE-SPINE.md: explicit ADRs
bmad-generate-project-context        # project-context.md (the constitution)
bmad-create-epics-and-stories        # epic files, each with implementable stories
bmad-check-implementation-readiness  # PASS / CONCERNS / FAIL over the whole chain

Create epics and stories the right size. One story is one unit of focused context, not a whole feature. If a story's diff would be unreviewable, it is two stories. The readiness gate is the last cheap checkpoint; do not start implementation on a FAIL, and treat CONCERNS as a to-fix list, not a suggestion.

Implementation

bmad-sprint-planning   # once: sprint-status.yaml sequences the cycle
# then per story, each in a fresh chat:
bmad-create-story  ->  bmad-dev-story  ->  bmad-code-review
# after the epic:
bmad-qa-generate-e2e-tests   ->   bmad-retrospective

Small, well-understood change? Skip the ceremony:

bmad-quick-dev
> Add a --json flag to the export command

It compresses intent, routes to the smallest safe path, implements, self-reviews, commits locally, and offers a push or PR. Say checkpoint to have bmad-checkpoint-preview walk a reviewer through the change by concern.

Fixing mistakes: undo, revert, recover

This is where BMAD's file-first design pays off: almost everything is recoverable because state is on disk and changes are committed, not hidden in a chat.

Undo the last Quick Dev change. Quick Dev commits locally; roll it back with git:

git revert HEAD          # safe: makes a new commit that undoes it
# or, if not yet shared and you want it gone entirely:
git reset --hard HEAD~1

Undo an autonomous (dev-auto / loop) run. The run records baseline_revision and final_revision in the spec frontmatter, bracketing exactly what it produced. Inspect, then revert the range:

git log <baseline_revision>..<final_revision>     # what the run actually did
git revert <baseline_revision>..<final_revision>  # undo the whole run

Equal baseline and final means it made no commits. The loop commits but never pushes, so nothing left your machine.

A plan went wrong mid-sprint. Do not hand-patch the downstream files. Run:

bmad-correct-course
> the auth approach changed from sessions to JWT; reconcile the plan

It reconciles the plan and re-routes, then you let the change propagate through the artifacts.

Two documents contradict each other. Find the first divergent decision, then run Update on the upstream owner (usually the PRD) and let it flow down. Reconcile the source, do not patch every downstream file independently:

rg -n "sessions|JWT|FR-12" _bmad-output docs
bmad-prd   > Update: reconcile the auth decision   # then re-run architecture/stories as needed

A workflow "forgot" an earlier answer. It was not externalized. Check whether the answer is in the artifact or its .memlog.md; if it lived only in a closed chat, BMAD never wrote it down. The fix is to put durable facts in project-context.md or an override so they load every time.

An autonomous run came back blocked. That is a routing signal, not just a failure: unattended execution would have been unsafe. Read the blocking condition, fix the cause, and re-dispatch a fresh run. A blocked story file is permanent (later dispatches halt with story already blocked); to retry, delete the story file so the id reads as pending again.

Research went stale or a claim was wrong. Do not re-run the world:

bmad-deep-recon
> refresh the market research      # re-verifies only stale claims, appends a delta

Refresh delivers confirmed / changed / overturned, and an overturned load-bearing claim triggers a warning naming the downstream artifacts that consumed it.

A long run (research, PRD) died mid-flight. Just reopen it. Files-first design means it resumes from disk: bmad-deep-recon picks up its run folder, bmad-prd re-reads its .memlog.md, dev-auto resumes from the spec status.

Research

The research skill is its own deep dive (see the companion Deep Recon docs), but the everyday shape:

bmad-deep-recon
> competitive research on Linear and Height                # Run mode, native fan-out
> draft a deep research prompt about X for Gemini          # Draft: run it in your own tool
> there's a report at ~/Downloads/r.pdf, process it        # Process: distill into research.md
> refresh the domain research / deepen the pricing dimension

Explore is the default; add "help me choose between" for the select shape. Match the mode to the money: Draft when you have a flat-rate chat subscription, Run when you need the firewall and the staleness map, Process to unify whatever came back.

Maintenance

npx bmad-method install --yes --action update --modules bmm,bmb   # update / add a module
bmad-customize                                                     # author a sparse override
npx bmad-method install --list-options bmm                        # discover config keys

Re-run the installer after adding or removing modules so the skill set stays in sync, and remove stale skill directories from a removed module by hand (the installer does not delete them).

Hands-on: break something, then recover three ways

Three failures, three different undo tools. Reaching for the wrong one is how a two-minute recovery becomes an afternoon. Work the drill in a scratch repo.

Case 1: Quick Dev committed the wrong thing. You ran a small change (see bmad-quick-dev above), it self-reviewed clean, and it committed locally. Later you find it wrong. Quick Dev never pushed, so this is purely local history.

bmad-quick-dev
> Add a --json flag to the export command

Confirm what landed, then undo it with a new commit that reverses the diff (safe: history stays intact and the mistake stays auditable):

git log --oneline -1
git revert HEAD

a1b9f4c (HEAD) Revert "Add --json flag to export command"
7e2c0d1 Add --json flag to export command

Illustrative (run it in your own repo; not machine-verified here).

Prefer git revert HEAD over git reset --hard HEAD~1 unless the commit is unshared and you want it gone with no trace.

Case 2: Claude edited files but did not commit. No commit exists, so git has nothing to revert. This is session state, so use the checkpoint system: /rewind (or double-Esc on an empty prompt), then pick a checkpoint from before the bad turn.

/rewind
  Restore conversation only
> Restore code and conversation      <- pick this
  Restore code only

Illustrative menu.

"Restore code and conversation" rolls back Claude's Read/Edit/Write edits and the transcript together, within the last ~100 checkpoints. What it will NOT bring back: committed git history (that is Case 1's job), any Bash side effect such as a rm or mv a step already ran, and edits made by a background subagent. For those, reach for git or restore the file yourself.

Case 3: a dev-auto run to unwind. The run committed a series, never pushed, and recorded its brackets in the spec frontmatter:

baseline_revision: 7e2c0d1
final_revision:    c4d5e6f

Revert the exact range it produced, in one shot:

git revert 7e2c0d1..c4d5e6f

Illustrative.

Equal baseline and final means the run committed nothing, so there is nothing to undo. The rule underneath all three: match the undo to who owns the change. Committed goes to git; a live uncommitted edit goes to /rewind; a whole autonomous run goes to a git range read from the frontmatter.

Under Claude Code: the host commands behind each recipe

BMAD stays host-agnostic; the recipes above are moves you make through whatever runs the skills. On Claude Code each move maps to one primitive. A skill runs when you type its /<skill> command (or when Claude matches your description to it, see page 11). The rest are host mechanics.

The /rewind caveat is the load-bearing one: it is session undo, not version control. It restores Claude's Read/Edit/Write changes and the transcript within the last 100 checkpoints, but it does not touch committed git history, Bash side effects (rm, mv, a git commit), external API calls, or edits made by a background subagent. So /rewind handles the "Claude just edited the wrong file" case; anything BMAD already committed (Quick Dev, dev-auto, the loop) comes back only through git revert, exactly as the recipes prescribe. Reach for the host primitive that owns the change: checkpoints for live edits, git for history.

These recipes are the vocabulary; the next page puts them to work in four full, narrated end-to-end scenarios. 👉