AGENT SKILL

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

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 its tracker_* 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):

  1. 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:

  1. Call tracker_get_work_item(ref=<id>).
  2. Extract: title, description, the Story's points (the estimate field tracker_describe names), parent_id.

If file system path (non-artifacts path to a .md or .txt file):

  1. 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):

  1. 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:

  1. Score each driver (Escopo, Incerteza, Integrações, Dados, QA, Rollout) on the 1/2/3/5 scale.
  2. calculated_points = MAX(all driver scores).
  3. 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 with active_points = declared.
  • If declared ≠ calculated: follow the discrepancy-handling protocol in scoring-guide.md exactly — 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):

  1. Print: Story is right-sized at <active_points> pts (ceiling: <ceiling>).
  2. Print the driver breakdown (all six driver scores).
  3. 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):

  1. Present spike rationale: uncertainty dominates; scope-splitting does not reduce risk — investigation does.
  2. Show the user the specific unknown that caused Incerteza=5 (derived from the story body).
  3. Ask: "Recommend a Spike instead of a scope split. Shall I draft a Spike stub?"
  4. Wait for user confirmation before proceeding to DRAFT.
    • Confirmed → proceed to DRAFT (Spike mode).
    • Declined → STOP.

Branch C — Split:

  1. split_count = ⌈active_points / ceiling⌉.
  2. Auto-select split pattern using the decision tree in split-patterns.md.
  3. Show reasoning: one sentence per pattern considered; one winner with justification.
  4. Derive split_count sub-story titles and one-line scopes.
  5. Estimate point value per sub-story: re-apply driver scoring to the narrowed scope. Each sub-story should score ≤ ceiling after the split.
  6. 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):

  1. Draft one local file at the path harness document path --type ticket --new user-story --title "<spike title>" --parent <parent_id> prints (in Tickets/Ready/).
  2. Fill all 7 body sections using the Spike stub format from ./references/scoring-guide.md.
  3. Fill each [placeholder] with content derived from the original story.

Split mode (Branch C approved):

For each approved sub-story:

  1. Path: the one harness document path --type ticket --new user-story --title "<title>" --parent <parent_id> prints (in Tickets/Ready/).
  2. The draft keeps that name; nothing is renamed after the item is created.
  3. Frontmatter (hook-valid — no status: and no provider_id before provider creation):
---
date: <YYYY-MM-DD>
type: ticket
work_item_type: User Story
parent_id: <parent_id>
provider: local
story_points: <estimated-points>
---
  1. Body: all 7 sections per ticket-structure.md and ../../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):

  1. List every AC item from the original story.
  2. For each item, confirm it appears in exactly one sub-story's 📄 Descrição Original.
  3. If any AC item appears in zero sub-stories: STOP and report ORPHAN AC: <item> — dropped requirement.
  4. If any AC item appears in two or more sub-stories: STOP and report DUPLICATE COVERAGE: <item> — ambiguous scope.
  5. 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):

  1. 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).
  2. Assert the response carries the new item's key. If absent: STOP and report failure with the item title and the raw error.
  3. Read back: tracker_get_work_item(ref=<new key>). Assert its parent_id == parent_id. If the assertion fails: STOP and report LINK ASSERTION FAILED for <title>: expected parent <parent_id>, got <actual>.
  4. 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

Monolith-INC
Monolith-INC/monolithic-dev-harness

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.

★ 1
Monolith-INC
Monolith-INC/monolithic-dev-harness

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.

★ 1
Monolith-INC
Monolith-INC/monolithic-dev-harness

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.

★ 1
Monolith-INC
Monolith-INC/monolithic-dev-harness

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.

★ 1
Monolith-INC
Monolith-INC/monolithic-dev-harness

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.

★ 1
Monolith-INC
Monolith-INC/monolithic-dev-harness

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.

★ 1