split-story
Lateral story-sizing skill. Takes a single User Story and determines if it should be split, how many sub-stories to create, and what split pattern to use — then drafts sub-stories and hands them off. Use when the user asks "split this story", "is this story too big?", "analyze this story for sizing", or provides an artifacts path / tracker id / file path / raw text and wants a split recommendation. One story per invocation.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- split-story
- license
- MIT
- description
- Lateral story-sizing skill. Takes a single User Story and determines if it should be split, how many sub-stories to create, and what split pattern to use — then drafts sub-stories and hands them off. Use when the user asks "split this story", "is this story too big?", "analyze this story for sizing", or provides an artifacts path / tracker id / file path / raw text and wants a split recommendation. One story per invocation.
02 资源文件 3
- 参考文档manifest.json610 B
- 参考文档references/scoring-guide.md5.7 KB
- 参考文档references/split-patterns.md6.7 KB
03 SKILL.md 正文
split-story
Lateral story-sizing skill. Load reference files as each phase needs them.
References (shared, in ../../references/):
decomposition-rules.md— 6-driver MAX heuristic, story-point ceiling, DoR, hierarchy rules.ticket-structure.md— body sections, frontmatter constraints, content hygiene.tracker-contract.md— the tracker gateway: every read and write goes through itstracker_*tools, never a tracker's own tools.
References (skill-specific, in ./references/):
split-patterns.md— split pattern catalog with detection signals and auto-selection rules.scoring-guide.md— 6-driver scoring table, ceiling logic, spike detection rule, discrepancy handling.../../common/templates/canonical-user-story.md— read-only shape contract for split sub-story drafts (seven emoji sections). Do not edit; validate output against this template.../../common/contracts/split-story/canonical-spike.md— read-only shape contract for spike stubs. Do not edit; validate spike output against this template.
PHASE 1 — INGEST
Input: one of — local draft path, tracker id or link, arbitrary file system path, or raw text pasted inline.
Determine source from the argument:
If local draft path (path under the artifacts path, recognized by artifacts path prefix or .md
extension inside the artifacts tree):
- Read the markdown file. Parse frontmatter: extract
work_item_type,story_points,parent_id,provider_id. Parse body: identify sections by emoji + label headings.
If a tracker id or link:
- Call
tracker_get_work_item(ref=<id>). - Extract:
title,description, the Story's points (the estimate fieldtracker_describenames),parent_id.
If file system path (non-artifacts path to a .md or .txt file):
- Read the file from disk. Parse as markdown. Extract any frontmatter if present; treat body as the full description.
If raw text (multi-line pasted content, no recognizable path or ID):
- Use the pasted content directly as the body. No frontmatter to parse; treat the entire input as the story description.
Normalize into a unified artifact record:
{
title: string | null (frontmatter/title field, or first heading, or null)
body: string (full description / body text)
story_points: number | null (null if not declared in any source)
acceptance_criteria: string[] (each AC line from the ✅ Critérios de Aceite section;
empty array if the section is absent)
parent_id: string | null
provider: the selected tracker's name
provider_id: string | null
source: "artifacts path" | "tracker" | "filesystem" | "raw"
}
Extract acceptance_criteria by reading the ✅ Critérios de Aceite section and splitting on
checkbox lines (- [ ] or - [x]). For a tracker source, parse the same section from the
item's description. For raw text or filesystem source, parse from the body if the
section heading is present; otherwise acceptance_criteria = [].
If artifact cannot be parsed (empty content, unreadable file, MCP error): STOP and report the specific failure. Do not proceed.
PHASE 2 — SCORE
Read ./references/scoring-guide.md for the complete driver table, ceiling value, spike rule,
and discrepancy-handling protocol before scoring.
Apply the 6-driver MAX heuristic to the normalized artifact:
- Score each driver (Escopo, Incerteza, Integrações, Dados, QA, Rollout) on the 1/2/3/5 scale.
calculated_points = MAX(all driver scores).- Record which driver(s) are at the MAX — these are the dominant drivers.
Discrepancy check (run only if story_points is declared and non-null):
- If
declared == calculated: proceed withactive_points = declared. - If
declared ≠ calculated: follow the discrepancy-handling protocol inscoring-guide.mdexactly — show both values with driver breakdown and wait for user choice.active_points = user-chosen value.
If story_points not declared: active_points = calculated_points. No prompt shown.
PHASE 3 — ANALYZE
Read ./references/split-patterns.md for the pattern catalog and auto-selection decision tree.
Branch A — No split needed:
If active_points ≤ ceiling (default 5, or override from invocation argument):
- Print:
Story is right-sized at <active_points> pts (ceiling: <ceiling>). - Print the driver breakdown (all six driver scores).
- STOP. No files written. No further phases execute.
Branch B — Spike recommended:
If Incerteza == 5 AND Incerteza is the sole MAX driver (no other driver also scored 5):
- Present spike rationale: uncertainty dominates; scope-splitting does not reduce risk — investigation does.
- Show the user the specific unknown that caused Incerteza=5 (derived from the story body).
- Ask: "Recommend a Spike instead of a scope split. Shall I draft a Spike stub?"
- Wait for user confirmation before proceeding to DRAFT.
- Confirmed → proceed to DRAFT (Spike mode).
- Declined → STOP.
Branch C — Split:
split_count = ⌈active_points / ceiling⌉.- Auto-select split pattern using the decision tree in
split-patterns.md. - Show reasoning: one sentence per pattern considered; one winner with justification.
- Derive
split_countsub-story titles and one-line scopes. - Estimate point value per sub-story: re-apply driver scoring to the narrowed scope. Each sub-story should score ≤ ceiling after the split.
- Map which ACs from the original story belong to each sub-story.
── GATE 1: present split plan to user ──
Show:
- Pattern chosen and why (one sentence)
- Number of sub-stories
- For each sub-story: proposed title + one-line scope + estimated points
- Which original ACs map to each sub-story
Ask harness decision present --gate refinement-split before entering DRAFT.
If the user revises the plan (different pattern, different count, adjusted titles): incorporate
revisions and re-show the updated plan. Do not proceed until the plan is approved.
PHASE 4 — DRAFT
Read ../../references/ticket-structure.md and ../../references/decomposition-rules.md
before writing any files.
Spike mode (Branch B confirmed):
- Draft one local file at the path
harness document path --type ticket --new user-story --title "<spike title>" --parent <parent_id>prints (inTickets/Ready/). - Fill all 7 body sections using the Spike stub format from
./references/scoring-guide.md. - Fill each
[placeholder]with content derived from the original story.
Split mode (Branch C approved):
For each approved sub-story:
- Path: the one
harness document path --type ticket --new user-story --title "<title>" --parent <parent_id>prints (inTickets/Ready/). - The draft keeps that name; nothing is renamed after the item is created.
- Frontmatter (hook-valid — no
status:and noprovider_idbefore provider creation):
---
date: <YYYY-MM-DD>
type: ticket
work_item_type: User Story
parent_id: <parent_id>
provider: local
story_points: <estimated-points>
---
- Body: all 7 sections per
ticket-structure.mdand../../common/templates/canonical-user-story.md(in order):- 🎯 O quê
- 💡 Por quê
- 📋 Comportamento esperado
- ✅ Critérios de Aceite
- 🔧 Notas Técnicas
- 📊 Complexidade — driver breakdown for this sub-story's narrowed scope
- 📄 Descrição Original — the exact verbatim slice of the original story's ACs that this sub-story covers. No paraphrasing.
Coverage check (run after all files are written, before HANDOFF):
- List every AC item from the original story.
- For each item, confirm it appears in exactly one sub-story's
📄 Descrição Original. - If any AC item appears in zero sub-stories: STOP and report
ORPHAN AC: <item>— dropped requirement. - If any AC item appears in two or more sub-stories: STOP and report
DUPLICATE COVERAGE: <item>— ambiguous scope. - Any gap or duplicate must be resolved by revising the draft files before HANDOFF. Do not silently patch — surface the issue to the user.
PHASE 5 — HANDOFF
Present a summary:
- List each sub-story: title + point estimate + file path.
- Coverage confirmation: "All <N> original ACs covered."
Show options:
Sub-stories drafted. What would you like to do?
1. Keep as local drafts — done; continue manually or via decompose-backlog.
2. Create them in the selected tracker under the parent Feature.
3. Discard drafts — delete files and stop.
Wait for user choice.
Option 1 — Keep: Report file paths and stop. No further action.
Option 2 — Provider:
Read ../../common/providers.md. Show the drafts with harness workflow show --artifact <draft>
and ask harness decision present --gate publish-items with every draft as --artifact.
For each sub-story draft (in order):
tracker_create_work_item(kind: "user_story", Markdown description = full body from the draft,parentRef=parent_id,storyPoints= the draft's estimate as a whole number).- Assert the response carries the new item's
key. If absent: STOP and report failure with the item title and the raw error. - Read back:
tracker_get_work_item(ref=<new key>). Assert itsparent_id == parent_id. If the assertion fails: STOP and reportLINK ASSERTION FAILED for <title>: expected parent <parent_id>, got <actual>. - Update local draft frontmatter: set
provider_id: <new key>(with the local tracker, creating the item already did this). The file keeps its name.
After all items: report each title, provider identifier, and parent link status.
Option 3 — Discard:
Delete each local draft file written in PHASE 4. Report Drafts discarded. and stop.
Guardrails
- One story per run. Process only the first argument if multiple are given.
- No silent patching. Coverage gaps and duplicates surface to the user — never auto-resolved.
- No provider writes without user consent. Connector calls execute only if the user selects HANDOFF option 2.
- Gate before draft. DRAFT phase does not execute until GATE 1 is explicitly approved.
- Spike ≠ split. When Incerteza is the sole dominant driver, recommend a Spike; do not force a scope split.
04 同仓库更多 Skills
validate-artifact
Validate a single agile artifact (Epic, Feature, User Story, or Task) against the toolkit rule set. Use when the user asks to "validate this story/feature/epic", "check this ticket", "is this artifact ready?", or provides a local draft path or provider item and wants a quality report. Accepts a local draft or a tracker work item. Runs all checks non-blocking and emits a terminal report + persisted report. One artifact per invocation.
research-decision
Research a product, market, domain, competitor, user, or technical question in service of a named decision, producing a cited decision brief. Use when planning depends on current evidence rather than more ideation.
product-spec
Distill an idea, brief, PRD, UX contract, architecture spine, issue, or mixed notes into a compact canonical product contract with stable capabilities and companions. Use before backlog decomposition when intent is defined; update or validate an existing product spec through the same skill.
product-requirements
Create, update, or validate a right-sized Product Requirements Document with stable requirements, explicit scope, user journeys where useful, and measurable outcomes. Use for multi-person or multi-epic alignment; skip it when a concise product spec is enough.
product-brief
Create, update, or validate a concise product brief that captures a clear concept, its users, value, scope, and success criteria. Use when the user wants a one- or two-page product narrative before a PRD or product spec.
plan-initiative
Route a raw idea through the smallest useful discovery and product-planning path, ending in a compact product spec ready for backlog decomposition. Use when the user wants to explore, validate, plan, define, or architect an idea before creating work items or starting implementation.