Preview — full styling will appear after the next deploy completes.

bmad-method

Solutioning

Technical design as a grooming step

Solutioning is the grooming pattern where the Architect persona produces a lightweight technical design for a story before implementation begins. It prevents the Developer persona from making uncontrolled architectural decisions mid-implementation.

flowchart TD
    ST([Story — AC complete<br>scope correct]) --> CTQ{Contains<br>architectural decisions?}
    CTQ -->|No| DEV([Direct to Developer<br>no Solutioning needed])
    CTQ -->|Yes| ARC[Architect Persona<br>Solutioning Session]
    ARC --> DN[Design Note<br>approach · data structures<br>error handling · ADR constraints]
    DN --> DEV2[Developer Persona<br>implements within design note]
    DEV2 --> DEV2D{Deviation<br>needed?}
    DEV2D -->|No| RD([Story complete])
    DEV2D -->|Yes| ADR[New ADR<br>human review]
    ADR --> RD

Implementation ambiguity is not always about requirements. A story can be requirement-complete — the acceptance criteria are clear, the scope is correct — and still leave the Developer persona with unresolved architectural decisions. Which data structure? Which API design? Which error-handling strategy? If these decisions are not made in advance, the Developer makes them silently, and they may conflict with decisions made in adjacent stories. Solutioning makes these micro-architectural decisions explicit before they are implemented.

Solutioning is an Architect persona session triggered by stories that contain implementation decisions above a certain complexity threshold. The Architect reads the story and produces a lightweight design note: the approach, the key data structures or interfaces, the error handling strategy, and any constraints from existing ADRs that apply. This note becomes part of the story before it is handed to the Developer. The Developer implements within the design note — any deviation requires a new ADR.

Solutioning is not full architecture work. It is not an ADR. It is a focused mini-design that answers the questions the Developer persona would otherwise answer silently. The right scope is: what are the decisions in this story that, if made poorly, would be expensive to reverse? Solutioning answers those questions and only those questions. Everything else is left to the Developer's judgment.