Skip to content
Back to skills

Splitting Stories

ASecurity

Split a story or task into smaller pieces.

  • 3 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 16, 2026
developmentgoapidatabasebackendperformance

Works with

  • api

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned November 16, 2026

npx -y skills add Acendas/shipyard --skill splitting-stories --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Splitting Stories?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Splitting Stories
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/acendas-splitting-stories/badge)](https://www.skillsdirectory.com/skills/acendas-splitting-stories)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: splitting-stories
description: Split a story or task into smaller pieces.
disable-model-invocation: true
---

# Splitting Stories

A feature or task that is too big does not get smaller by being given a smaller estimate — it gets smaller by being **split into independently valuable pieces**. The default failure mode for an LLM orchestrator is to split horizontally (UI / API / DB as separate stories), which produces tasks that are technically smaller but none of which is independently demoable. This skill exists to force vertical slicing.

The output is **a list of split candidates**, not opinions — concrete child stories/tasks each with a one-line user-observable outcome and the splitting pattern that produced it.

## When to Invoke

| Caller | Trigger |
|---|---|
| `/ship-discuss` Phase 2 (Viability Gate) | When the SPLIT signal fires ("multiple stories in a trench coat") or BUILDABLE/SIZED fails on size grounds |
| `/ship-discuss` Phase 1.5b challenge | When the user describes a feature whose acceptance criteria already exceed what fits in one sprint |
| `/ship-sprint` Stage 3 (task decomposition) | When a behavior draft fails the "and" test or any of the 11 patterns fires |
| `/ship-sprint` Stage 5 (effort) | When a task is estimated `effort: L` and the L-confirmation checklist is uncertain |
| Manual / ad-hoc | When the user says "this feels too big" |

Skip for trivial inputs (single AC, single touchpoint, S effort with one obvious Red step). The splitting overhead exceeds value.

## Inputs

- `story_text` — the feature/task draft to split (markdown). May be a `/ship-discuss` draft, an existing feature spec, or a task draft from `/ship-sprint` Stage 1.
- `acceptance_criteria` — the AC list for the input, if separate from the draft.
- `level` — `feature` (splitting a story into smaller stories) or `task` (splitting a task into smaller tasks). Default `task`.
- `domain_hints` — optional list of domain tags (`["payments", "auth", "external-api", "ui"]`) that bias which patterns fire first.
- `data_dir` — for reading `<SHIPYARD_DATA>/codebase-context.md` to ground splits in the actual stack.

## Step 0: INVEST Gate

Run before attempting to split. Check the input against INVEST minus Small:

- **Valuable** — does the story have a clear user-observable outcome? If no, **do not split** — return one finding `{ "action": "rescope", "reason": "no observable user value to split into smaller observable outcomes" }`. Splitting an unvaluable story produces unvaluable smaller stories.
- **Independent** — can it be prioritized on its own? If no (it's a sub-step of something else), the split candidates inherit the same dependency — flag it.
- **Negotiable** — is there room for design conversation? If the input is already over-specified down to implementation detail, a split may just be re-arranging the implementation rather than scope.
- **Estimable** — does the team know roughly what's involved? If no, the right output is a `Spike` (Pattern 9), not a normal split.
- **Testable** — can each resulting child have a clear done-condition? Every split candidate output must satisfy this.

## Step 1: The "And" Test

Apply before running the patterns. Any draft whose title or description contains `and` connecting two **independent** behaviors is a mandatory split.

**Split:**
- "Create user **and** send welcome email" → 2 children
- "Add migration **and** update API response shape" → 2 children
- "Implement search **and** add caching" → 2 children (Pattern 7 also fires)

**Do not split:**
- "Create record **and** return ID" — one atomic operation
- "Parse request **and** validate schema" — one guard at one boundary
- "Find **and** update" — one read-modify-write on the same record

The test: would these two clauses produce two separate failing tests? If yes, split.

## Step 2: Run the 11 Splitting Patterns

Apply in order. For each draft, walk the patterns; the first one that fires produces a split. Re-run from the top on each resulting child until no pattern fires.

**Read the catalogue:** `${CLAUDE_PLUGIN_ROOT}/skills/splitting-stories/references/patterns.md` for trigger phrases, signal words, examples, and stack-specific notes for each pattern.

Summary (pattern → trigger → split-by):

1. **Workflow Steps** — sequential process verbs ("then", "after", "followed by") → split per step; build thin end-to-end happy path first, fill middle steps after.
2. **CRUD Operations** — "manage X", multiple data verbs on one entity → split per verb (Create / Read / Update / Delete).
3. **Business Rule Variations** — "if premium…", "unless admin…", "when overdue…" → happy path first, each rule as a follow-on.
4. **Data Variations** — multiple data types/formats/sources in one pass → simplest/most-common type first; additional types as follow-ons.
5. **Interface vs. Functionality** — UI complexity bundled with backend behavior → backend (API/service) first, UI rendering on top.
6. **Happy Path vs. Edge Cases** — "and handle errors", "and validate", AC mixes success and failure → happy path first, error/validation/timeout branches as follow-ons.
7. **Make-it-Work vs. Make-it-Fast** — caching, optimization, performance, throughput keywords → correctness first, performance as follow-on. **Mandatory** — premature optimization breaks the Red step (no failing perf test before behavior exists).
8. **Major Effort (Infrastructure-Dominant)** — "set up", "integrate", "configure", "install" leads the description → infrastructure as foundation, behavior on top in a later wave.
9. **Simple vs. Complex** — a small core behavior surrounded by variations → extract the core, push variations into separate stories. Lawrence's selection-rule pairs well here: prefer the split that exposes the lowest-value variation.
10. **Paths (SPIDR)** — multiple user routes accomplishing the same goal → one path per child; ship the most-used path first.
11. **Spike (last resort)** — implementation approach is genuinely unknown, no codebase pattern to follow → time-boxed `kind: research` task first, `kind: feature` after, informed by findings.

A 12th category exists for `level: feature` only — **Hypothesis-Driven** splitting: when the parent is itself a bet ("we believe users want X"), produce a thin slice that tests the riskiest assumption. Use this when the discuss-phase research surfaced low-confidence assumptions that should be validated before building the full surface.

## Step 3: Reject Horizontal Slices Structurally

After producing candidate children, check each one with this single question:

> Does this child, on its own, produce a user-observable outcome that the user can demo or that an end-to-end test can assert on?

If the answer is no, the split is horizontal (sliced by architectural layer — UI / API / DB / migration as separate children) and **must be rejected**. Common shapes of horizontal slices to detect:

- Children titled "add database migration", "add API endpoint", "add UI component" with no behavior in any single one
- Children whose acceptance criteria are "the migration runs" or "the endpoint returns 200" without a user-facing assertion
- Children that only become demoable when the whole set lands together

Repair: re-split using a vertical pattern from Step 2. The walking-skeleton foundation task (Stage 2 of `/ship-sprint`) is the **one exception** — it is explicitly horizontal (schema + routes + types + stubs across all layers, no behavior) and lives in Wave 1 by itself precisely so every behavior task on top of it can be vertical. Outside of that, no horizontal children.

## Step 4: Selection Tiebreaker

If multiple valid splits are possible (e.g., the same draft could split by CRUD or by user role), prefer the split that:

1. **Exposes a low-value child** — the child the user can deprioritize or cut. Lawrence's rule: a split is most valuable when it makes scope-cutting possible, not just sequencing.
2. **Produces roughly equal-sized children** — avoid one giant child + several slivers; that usually means the slivers are horizontal disguise.
3. **Reduces cross-child dependencies** — same-wave dependencies indicate a missed foundation task; redo Stage 2.

If no split satisfies (1) or (2), the input may be one cohesive piece of work — return `{ "action": "no-split", "reason": "..." }` rather than forcing a split.

## Step 5: Cynefin Sensitivity

Adjust depth based on domain context (read `<SHIPYARD_DATA>/codebase-context.md` and any feature `complexity:` frontmatter):

- **Obvious** — find all children, prioritize by value, ship.
- **Complicated** — find all children, prioritize by value/risk; expect re-splitting after the first lands.
- **Complex** — do **not** try to enumerate all children. Produce 1–2 thin slices, ship, learn, then split the rest based on what was observed. Mark output `partial: true`.
- **Chaotic** — refuse to split; recommend stabilization first. Return `{ "action": "stabilize-first", ... }`.

## Output Shape

Return a structured split list. Each candidate:

```
{
  "id": "child-1" | "child-2" | ...,
  "title": "<one-line user-observable outcome>",
  "pattern": "workflow" | "crud" | "rules" | "data" | "interface"
           | "happy-vs-edge" | "perf" | "major-effort" | "simple-complex"
           | "paths" | "spike" | "hypothesis",
  "acceptance_hint": "<one-line testable done condition — basis for the Red step>",
  "depends_on": ["child-N", ...],
  "deferrable": true | false,
  "rationale": "<why this is a vertical slice, not a horizontal one>"
}
```

Wrap with metadata:

```
{
  "input_passed_invest": true | false,
  "invest_failures": ["valuable", "estimable", ...],
  "patterns_tried": ["and-test", "workflow", "crud", ...],
  "patterns_fired": ["crud", "happy-vs-edge"],
  "horizontal_rejections": [<repaired children>],
  "partial": false | true,
  "candidates": [ <child objects> ],
  "selection_notes": "<why this split over alternatives, per Step 4>"
}
```

## Output Discipline

1. **Vertical only.** Every candidate must independently produce a user-observable outcome (or be the explicit walking-skeleton foundation task). Reject and repair horizontal candidates before returning.
2. **Concrete titles.** "Submit maintenance request and store it" beats "Implement submission". A reader should be able to write the Red step from the title alone.
3. **No padding.** If only one pattern fires, return only the children that pattern produces — don't manufacture variants from other patterns to look thorough.
4. **Cite the pattern.** Every candidate has exactly one `pattern` field naming the rule that produced it. If "multiple patterns fired", split twice and re-run.
5. **Honor `partial: true` in complex domains.** Two thin slices with `partial: true` is a better answer than seven speculative ones.

## Read-Only Contract

This skill produces a split plan; it does not edit feature/step files. The calling command skill creates the resulting feature/step files (with their own probe authoring, Technical Notes, and frontmatter). Do not Write to the spec or task tree directly.

## Pairing With Other Skills

- **`extracting-acceptance-criteria`** — the input AC list often comes from this skill. After splitting, each child gets its own AC subset.
- **`discovering-edge-cases`** — runs alongside on the parent, then again on individual children once split. Edge cases discovered on a child often justify Pattern 6 (Happy Path vs. Edge Cases) splits.
- **`authoring-acceptance-probe`** — runs on each `kind: feature` child after split, deriving the smoke command from the child's `acceptance_hint`.
- **`/ship-sprint` Stage 2 (walking skeleton)** — the one sanctioned horizontal task. Splitting-stories' horizontal-rejection rule explicitly excepts it.
- **`/ship-discuss` Phase 2 viability** — when SPLIT fires, this skill produces the candidate decomposition the user picks from.

Files in this skill

  • SKILL.md11.7 KB
  • references/patterns.md12.4 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.