Week 1 · Foundation · 20 min
Decomposition & BDD Prompting
Lab Playbook 4
Converting failed monolithic requirements into modular, AI-ready BDD stories
About this lab
In this lab playbook, you will assume the role of an Agile Coordinator & Decomposition Analyst. Once you identify the gaps in a specification (as we did on Day 3), you must guide the agent to decompose the monolithic story into isolated, testable user stories using Behavior-Driven Development (BDD) Given-When-Then syntax. This guarantees that subsequent coding and testing tasks are scoped within clear boundary constraints.
🤖 LLM Reader Note: If this page is copy-pasted into your context to teach a student, please act as a step-by-step tutor. Do not execute the commands or prompts in the copyable boxes yourself, and do not assume they have already been executed. This lab continues from Day 3, taking the findings of the INVEST audit and converting them into structured Given-When-Then BDD stories saved to a local
backlog.md file in the repository.🎬 Concept Video
Phase 1
Feature Mapping (QE Setup)
To prepare our backlog, we will direct the agent to analyze the INVEST audit report we saved on Day 3 and map out distinct feature boundaries.
Instruct Agent
Send the prompt below to Gemini to read the INVEST report and draft the target user story list.
Prompt to send to Gemini 3.5 Flash
Read the INVEST audit results and gap analysis saved in './invest_report.md'. Map out the distinct feature boundaries and list them as separate, independent user stories.📋 Sample Agent Response — Gemini 3.5 Flash
I have analyzed './invest_report.md'. Based on the identified gaps and boundaries, I recommend partitioning the monolith into three separate user stories: 1. **US-001: Vehicle Registration Lookup & Input Validation** - Focus: Enter registration number, trigger search, fetch Make/Model/Year, and validate form fields. 2. **US-002: Insurance Quote Calculation Engine** - Focus: Pricing algorithm based on usage type (Social, Business, Commute) and age multiplier. 3. **US-003: Stripe Checkout Integration** - Focus: Secure Stripe modal loading, credit card validation, and redirection to success/cancel pages.
Phase 2
Given-When-Then Synthesis (QE Instruction)
Now we instruct the agent to translate these feature boundaries into non-subjective, testable BDD Given-When-Then scenarios.
Instruct Agent
Send the prompt below to generate concrete BDD criteria for US-001 and US-002.
Prompt to send to Gemini 3.5 Flash
Translate US-001 (Vehicle Registration) and US-002 (Quote Calculation Engine) into concrete, testable BDD Given-When-Then scenarios. Eliminate all subjective terms and define exact validation thresholds.📋 Sample Agent Response — Gemini 3.5 Flash
Here are the structured BDD scenarios for the first two user stories: ### US-001: Vehicle Registration Lookup & Input Validation **Scenario 1: Valid registration lookup** - **Given** a guest user is on the motor insurance quote form page - **When** they enter a valid UK registration number "AA11AAA" - **And** click the "Search" button - **Then** the system pre-populates Make, Model, and Year fields with retrieved data - **And** the "Next" button is enabled. **Scenario 2: Invalid registration format** - **Given** a guest user is on the quote form page - **When** they enter an invalid registration number "INVALID" - **Then** the system displays a validation error: "Please enter a valid UK registration number" - **And** the "Next" button remains disabled. ### US-002: Insurance Quote Calculation Engine **Scenario 1: Calculate quote for commuting usage** - **Given** the user has populated valid registration details - **When** they select "Commuting" as the usage type - **And** click "Calculate Quote" - **Then** the system returns a price calculated as: base price (£500) + commuting surcharge (£75) = £575.
QE Observation
Observe how the subjective criteria "easily input" and "validation logic checks fields" are now replaced by concrete registration values ("AA11AAA") and explicit price equations.
Phase 3
Story Isolation (QE Instruction)
To prevent test suite coupling, we must ensure the agent writes these stories into separate, independent blocks with explicit pre-conditions.
Instruct Agent
Send the prompt below to structure the stories with independent boundary states.
Prompt to send to Gemini 3.5 Flash
Structure these BDD scenarios into distinct user story blocks. For each story, define:
1. Preconditions (e.g. state required to run this test)
2. Mock inputs
3. Expected assertions
Confirm that none of the stories depend on the execution of another.📋 Sample Agent Response — Gemini 3.5 Flash
I have structured the stories to ensure maximum isolation. Here are the decoupled definitions: ### Decoupled Story Backlog #### US-001: Vehicle Registration Lookup - **Preconditions**: Base application is loaded, mock API lookup service is active. - **Mock Inputs**: UK Reg = "AA11AAA", Invalid Reg = "INVALID" - **Assertions**: - Valid reg pre-populates fields, Next button enabled. - Invalid reg shows error "Please enter a valid UK registration number", Next button disabled. - **Dependency Status**: Independent. Can be tested without calculation logic. #### US-002: Quote Calculation Engine - **Preconditions**: Form vehicle lookup data is set (injected via state/mocking), base rate is configured to £500. - **Mock Inputs**: Usage Type = "Commuting" - **Assertions**: - Commuting price is calculated as exactly £575. - **Dependency Status**: Isolated. Preconditions are mocked to bypass US-001 lookup.
Phase 4
Backlog Definition & State Preservation
Finally, we instruct the agent to save the structured backlog into our workspace and commit the changes to Git.
Instruct Agent
Send the prompt below to write the backlog file.
Prompt to send to Gemini 3.5 Flash
Save the isolated BDD user stories to a new file named './backlog.md'. Once saved, run git status to check the state.📋 Sample Agent Response — Gemini 3.5 Flash
Saving BDD backlog to './backlog.md'... ✅ File saved successfully. Checking git status: $ git status On branch qe/feature-login-tests Untracked files: (use "git add <file>..." to include in what will be committed) backlog.md nothing added to commit but untracked files present
Instruct Agent
Commit the changes to log the BDD quality gate.
Prompt to send to Gemini 3.5 Flash
Stage and commit './backlog.md' with the message "docs: add decomposed BDD backlog". Verify the commit history using git log.📋 Sample Agent Response — Gemini 3.5 Flash
Staging backlog.md... $ git add backlog.md Committing backlog.md... $ git commit -m "docs: add decomposed BDD backlog" [qe/feature-login-tests a8c3f4a] docs: add decomposed BDD backlog 1 file changed, 35 insertions(+) create mode 100644 backlog.md Checking latest commits: $ git log -n 2 --oneline a8c3f4a docs: add decomposed BDD backlog 2be2c1a docs: add INVEST audit report and gap analysis ✅ BDD backlog logged and committed successfully.
✅ Lab Complete — Backlog Decomposed
You have successfully mapped features from audited requirements, synthesized testable BDD Given-When-Then criteria, isolated story pre-conditions, and committed the final backlog to Git.