Learn and Adjust
Learn and Adjust
Use this page when an epic’s stories are all built, when a requirement changes in the middle of the work, or when findings set aside by builds pile up. Learn and adjust decides what to change. Each story passed its own review, so this stage judges the epic as a whole and sends what it finds back to the document or ticket that owns it.
| Learn and adjust | |
|---|---|
| You start with | An epic whose stories are all built, done, or dropped; a change; or deferred findings |
| You produce | epic-<slug>-retrospective.md with a verdict and action items, a closed epic, and updated tickets |
| It is done when | The verdict is recorded, the epic is closed, and each action item and finding is filed or dropped with a reason |
| Skip it when | Rarely at the end of an epic: it is the check no single story’s review makes. Mid-epic, only when a change or a finding calls for it |
| What comes next | Plan the Work, where the findings change requirements, the spine, or the stories; the next epic |
Finish an Epic
Section titled “Finish an Epic”When every story is built, check that the epic’s bugs and spikes are finished
too: the retrospective accepts an epic only when none of its tickets is
unfinished. Then check the stories still at built and mark them done, with
one command per story:
/bmad-agent-po mark story 1.8 doneThen start a fresh chat and run bmad-retrospective on the epic,
with its folder, id, or slug. It reads the epic’s plans, commits, and diffs rather than
anyone’s memory, judges the epic against its own Done when, and reviews the
whole changeset for the problems no single story’s review could see. It writes
epic-<slug>-retrospective.md in the epic’s folder, with a verdict of
accepted, accepted-with-open-items, or rejected and proposed action
items. It creates no tickets and changes no status.
/bmad-retrospective 1Then have Sofia validate and close the epic. She checks it against its Requirements and Done when, and you confirm:
/bmad-agent-po close the door check-in epicDecide what to do with each action item.
Finish an Epic covers what the retrospective looks for.
To review the epic’s changes yourself, block by block, you can also run
bmad-walkthrough on the epic’s PR or on one commit at a time.
A Change Mid-Flight
Section titled “A Change Mid-Flight”Tell Sofia “this changed, what now”, with what changed and where it came from. She reads the affected ticket, its history, its breakdown, and the work already finished, and says whether what is required changed or only how it is delivered. Then she proposes a way forward: adjust the remaining stories, roll back built work, or cut scope. You decide.
- When what is required changes, she updates the ticket’s requirements first, keeping every id, and names the stories whose requirements changed.
- When the breakdown changes, she re-slices the affected epics. Finished work is never rewritten; it stays as the record, and a new story carries the change.
- She drops work that no longer belongs, records the reason, and clears what waited on it.
- When the change reaches the design or the spine, she notes what it
invalidates and offers
bmad-uxorbmad-architecture; she never edits their files.
She records the reason as a dated Decision: line in each ticket she touched.
A change that starts upstream goes through the skill that owns that document
first: John updates the PRD, bmad-ux the design. Then Sofia updates the
initiative from it. On the organization path, follow the order in
Plan Inside an Organization.
Deferred Findings
Section titled “Deferred Findings”Builds stay focused on one goal, so real findings that belong elsewhere are set
aside. bmad-build and bmad-code-review add them to deferred-work.md in
the initiative’s folder; bmad-build-auto lists them under deferred in its
plan instead. Nothing turns them into tickets on its own. Before the next epic
is planned, go through them with Sofia: each becomes a story or a bug in
backlog/, or is dropped with the reason recorded.