Use this when a user story is too large to complete in 1-3 days and needs to be broken into smaller stories that each deliver independent end-to-end value. Rejects technical-layer splits (no "frontend story" + "backend story"). Also handles epic-level decomposition -- breaking a large design area or feature into delivery workstreams with scope boundaries.
Related skills: For story-level mapping across user activities, use
/story-map. For individual story writing within an epic, use/story-write. For a full design-to-epic decomposition skill, use/epic-breakdown.
Process
Step 1: Gather the story
Ask the user:
- Paste the full story you want to split (title, description, acceptance criteria, technical details -- whatever you have).
- Why do you think it needs splitting? (Too many scenarios? Too many unknowns? Team estimated it too large?)
- Decomposition level -- story split (default) or epic decomposition? Use epic decomposition when you have a design area, feature set, or initiative that needs to be broken into delivery workstreams before individual stories are written.
If the user provides just a title or brief description, ask for the acceptance criteria — you need them to split well.
Step 2: Analyze the story
Review the story and identify:
- Natural split points — distinct user workflow steps, separate scenarios, or independent pieces of value
- Persona boundaries — does the story serve multiple personas? If so, splitting by persona is often a natural and high-value split (e.g., "buyer views order" vs. "admin views all orders"). Check whether the original story names a persona — if it says "user" generically, that's a signal it may be covering multiple personas.
- Why it's too big — too many acceptance criteria, multiple user personas, multiple workflows, or technical unknowns that should be isolated
- Dependencies — which pieces must come before others
Present your analysis to the user before proposing splits.
Step 3: Propose the split
For each proposed split story, output:
### Split N: (Story title)
**One-line description:** (What slice of value this delivers)
**Description:**
As a (user persona), I want to be able to (action), so that (purpose/value).
**Key acceptance criteria (summary):**
- (Scenario 1 — brief description)
- (Scenario 2 — brief description)
- (Additional scenarios as needed)
**INVEST check:**
- Independent: (Yes/No — explain if No)
- Valuable: (What value this delivers on its own)
- Small: (Estimated at 1-3 days? Yes/No)
**Dependencies:** (None / depends on Split N)
After listing all splits, provide:
- Split summary: a table showing all proposed stories and their dependencies
- What was removed or deferred: anything from the original story that didn't make it into any split
Step 4: Review and refine
Ask the user:
- Does each split deliver real value on its own?
- Are the dependencies acceptable, or should we reorder?
- Should any splits be combined or further divided?
- Is anything missing from the original story?
Iterate until the user is satisfied with the split.
Remember: this draft multiplies your output, not your judgment. You own the final narrative.
Step 5: Write full stories (optional)
If the user wants complete stories for any or all splits, write each using the full story structure:
- Title, Description (As a/I want/So that), Acceptance Criteria (Gherkin), Technical Details, Out of Scope, Added Context
- Cross-reference sibling stories in the Out of Scope section
Epic decomposition mode
When the user chose epic decomposition, replace Steps 2-4 with this flow:
-
Analyze the feature/design area for natural workstream boundaries:
- By user journey phase (e.g., onboarding, core usage, admin)
- By capability domain (e.g., search, payments, notifications)
- By dependency chain (what must exist before other things can be built)
-
For each proposed epic, output:
### Epic N: {{epic_title}}
**Scope boundary:** (what's in this epic, what's not)
**Dependencies:** (which other epics must come first, or None)
**Approximate size:** S / M / L
**Key acceptance themes:** (3-5 high-level outcomes, not individual stories)
-
Output a sequencing summary showing epic order and parallelization opportunities.
-
Cross-reference: Once epics are agreed, use
/story-writeor/story-mapto break each epic into stories.
Splitting guidelines
- Always split vertically — each story delivers a thin slice of end-to-end value (user can do something new). Never split by technical layer.
- Preferred split strategies (in order of preference):
- By user workflow step — e.g., "search for item" → "add to cart" → "checkout"
- By scenario or variation — e.g., "pay with credit card" vs. "pay with PayPal"
- By user persona — e.g., "buyer views order" vs. "admin views all orders"
- By happy path vs. edge cases — ship the happy path first, handle errors in a follow-up story
- Reject these splits:
- Frontend / backend / database (technical layers)
- "Set up infrastructure" as a standalone story (wrap it into the first user-facing slice)
- Splits where one story has no user-observable value
- Each split must pass INVEST — especially Independent and Valuable. If a split can't stand alone, it's not a good split.
- 2-5 splits is typical. If you're proposing more than 5, the original story might be an epic.
Output location
Present the split analysis and stories as formatted text in the conversation for the user to copy into their project tracker.
Example Output
Input
- Story title & description: "Vendor Onboarding" — As a new vendor, I want to register on the Maplewood Marketplace platform so that I can start selling products to customers.
- Acceptance criteria (pasted in full): Vendor fills out business profile (name, address, tax ID, logo); uploads bank account details for payouts; submits identity verification documents; receives email confirmation; admin reviews and approves/rejects the application; vendor is notified of approval or rejection; approved vendor can log in and see their seller dashboard; vendor can list their first product.
- Why splitting: Team estimated 21 points. Too many unknowns around the identity verification integration (third-party KYC provider not yet selected).
- Decomposition level: Story split (default)
Output (abbreviated)
Story Split Analysis — Vendor Onboarding
Analysis
Why it's too big: The original story spans at least three distinct workflows (vendor self-registration, admin review, and first product listing) plus two personas (vendor and admin). The KYC integration is an unknown that should be isolated so it doesn't block the rest of onboarding.
Natural split points identified:
- Vendor submits their business profile and bank details (self-service registration)
- Identity/KYC document upload — isolated because the third-party provider is unresolved
- Admin reviews and approves or rejects the application (separate persona: admin)
- Approved vendor accesses their seller dashboard and lists a first product
Dependency chain: Split 1 → Split 2 → Split 3 → Split 4
Split 1: Vendor Submits Registration Profile
One-line description: A new vendor can complete their business profile and bank details and submit an onboarding application.
Description: As a new vendor, I want to fill in my business profile and payout details and submit my application, so that I can begin the approval process to sell on Maplewood Marketplace.
Key acceptance criteria (summary):
- Vendor can enter business name, address, tax ID, and upload a logo
- Vendor can enter bank account details for payouts
- Vendor can submit the completed form and receives an on-screen confirmation
- Incomplete submission shows inline validation errors
- Submitted application is stored with status "Pending Review"
INVEST check:
- Independent: Yes — no external integrations required
- Valuable: Vendor completes a real step toward selling; platform captures structured onboarding data
- Small: Yes — estimated 2-3 days
Dependencies: None
Split 2: Vendor Uploads Identity Verification Documents
One-line description: A vendor in "Pending Review" status can upload KYC documents to satisfy identity verification requirements.
Description: As a vendor awaiting approval, I want to upload my identity verification documents, so that Maplewood Marketplace can confirm my legitimacy before I start selling.
Key acceptance criteria (summary):
- Vendor can upload government-issued ID and business registration document (PDF or image)
- Upload triggers submission to the KYC provider (stubbed with a mock if provider not yet selected)
- Vendor sees a "Documents received" status on their application page
- Failed upload (wrong file type, size exceeded) shows a clear error
INVEST check:
- Independent: Yes — document upload UI and stub integration can ship without the live KYC provider
- Valuable: Unblocks admin review; isolates the integration risk
- Small: Yes — 2-3 days with stub; KYC live integration is a separate technical spike
Dependencies: Split 1 (application must exist before documents can be attached)
Split 3: Admin Reviews and Approves or Rejects Vendor Application
One-line description: An admin can review a submitted vendor application and approve or reject it, triggering a notification to the vendor.
Description: As a Maplewood Marketplace admin, I want to review vendor applications and approve or reject them, so that only verified vendors can sell on the platform.
Key acceptance criteria (summary):
- Admin sees a queue of applications in "Pending Review" status
- Admin can view all submitted profile fields and uploaded documents
- Admin can approve or reject with a required reason for rejection
- Vendor receives an email notification with outcome and next steps
- Application status updates to "Approved" or "Rejected" in the system
INVEST check:
- Independent: Yes — delivers a complete admin workflow
- Valuable: Platform can enforce vendor quality control end-to-end
- Small: Yes — estimated 2-3 days
Dependencies: Split 1 (requires submitted applications to review)
Split 4: Approved Vendor Accesses Seller Dashboard and Lists First Product
One-line description: An approved vendor can log in, view their seller dashboard, and publish their first product listing.
Description: As an approved vendor, I want to access my seller dashboard and create a product listing, so that I can start selling on Maplewood Marketplace.
Key acceptance criteria (summary):
- Approved vendor can log in and land on their seller dashboard
- Dashboard shows account status, payout info summary, and active listings count
- Vendor can create a product listing (title, description, price, images, inventory count)
- Listing is saved in draft; vendor can publish it to the storefront
- Rejected or pending vendors who attempt to access the dashboard see an appropriate status message
INVEST check:
- Independent: Yes — dashboard and listing creation stand alone once approval exists
- Valuable: This is the moment the vendor can actually sell — the goal of the entire flow
- Small: Yes — estimated 3 days
Dependencies: Split 3 (vendor must be approved before dashboard is accessible)
Split Summary
| # | Story Title | Persona | Size Est. | Depends On |
|---|---|---|---|---|
| 1 | Vendor Submits Registration Profile | Vendor | 2-3 days | None |
| 2 | Vendor Uploads Identity Verification Documents | Vendor | 2-3 days | Split 1 |
| 3 | Admin Reviews and Approves or Rejects Application | Admin | 2-3 days | Split 1 |
| 4 | Approved Vendor Accesses Dashboard and Lists First Product | Vendor | 3 days | Split 3 |
What Was Deferred
- Live KYC provider integration — Split 2 ships with a stub. The real third-party integration should be a separate technical spike once the provider is selected.
- Vendor edits a rejected application and resubmits — not in any split above; recommend as a follow-on story after Split 3 is validated.
- Payout account verification (micro-deposit flow) — mentioned implicitly in bank account capture but not in the original ACs; flag for Product to decide scope.
Does each split deliver real value on its own? Are the dependencies acceptable, or should we reorder anything?