contract-decompose
/contract-decompose
Turn a Large contract into a dependency-ordered sequence of Small/Medium child contracts, with risky parts (migrations, auth) flagged as human-led. Use when a contract is sized Large and the user says "decompose", "break this down", "split this epic", or invokes `/contract decompose <ID>`. Large isn't refused — it's made tractable.
- Author
- iampawan ↗
- Repository
- manifest ↗
- Licence
- MIT
- Last repository change
- 02.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 02.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Turn a Large contract into a dependency-ordered sequence of Small/Medium child contracts, with risky parts (migrations, auth) flagged as human-led. Use when a contract is sized Large and the user says "decompose", "break this down", "split this epic", or invokes `/contract decompose <ID>`. Large isn't refused — it's made tractable.
Triggers from the description
Original author description
Turn a Large contract into a dependency-ordered sequence of Small/Medium child contracts, with risky parts (migrations, auth) flagged as human-led. Use when a contract is sized Large and the user says "decompose", "break this down", "split this epic", or invokes `/contract decompose <ID>`. Large isn't refused — it's made tractable.
How it works
- When this runs
- Process
- Anti-patterns
SKILL.md preview
---
name: contract-decompose
description: Turn a Large contract into a dependency-ordered sequence of Small/Medium child contracts, with risky parts (migrations, auth) flagged as human-led. Use when a contract is sized Large and the user says "decompose", "break this down", "split this epic", or invokes `/contract decompose <ID>`. Large isn't refused — it's made tractable.
---
# Contract decomposer (smart Large support)
A Large contract shouldn't be agent-shipped on a 24/72h timer — but it
shouldn't be thrown over the wall either. Your job: break it into a
sequence of independently-shippable Small/Medium child contracts,
ordered by dependency, so a multi-week epic becomes a series of
24h/72h pieces. The Large contract stays as the **epic** that owns the
overall success metric and tracks aggregate progress.
## When this runs
- A contract was sized `large` by the validator, and the user wants to
proceed (rather than abandon).
- Invoked via `/contract decompose <ID>` or routed here from
`/contract promote` when it detects a Large contract.
## Process
### 1. Read the Large contract
Read `.manifest/contracts/<ID>.md`. Confirm `complexity: large`.
Pull the goal, success metrics, all behaviors, and the critic findings
(the critics still ran on the Large spec — use their edge cases and
regression notes to inform the split).
### 2. Find the natural seams
Decompose along the lines that make each piece independently
shippable and valuable. Good seams, in rough priority:
- **Platform**: ship web first, then iOS, then Android (each a child).
- **Behavior cluster**: group behaviors that share a surface or data
model into one child; split unrelated ones.
- **Risk isolation**: pull migrations, auth/billing changes, and new
infrastructure into their OWN children, flagged human-led (see §4).
- **Enablement → feature**: a child that adds the backend endpoint
(behind a flag, no UI) before the child that adds the UI consuming
it. The first ships safely with nothing user-visible.
- **Read before write**: ship the read/display path before the
mutation path when that lets you validate data independently.
Each child should be Small or Medium on its own. If a proposed child
is still Large, recurse — decompose it further.
### 3. Order by dependency
Build a DAG: which children must ship before which. A child that
consumes an API can't ship before the child that adds the API
(unless flag-gated to be inert). Produce a linear order that respects
the DAG, with parallelizable children noted.
### 4. Flag the human-led children
Some children genuinely shouldn't be agent-implemented:
- Schema migrations on hot tables
- Auth / billing / payment primitive changes
- New service / infrastructure standup
- Anything the security or scalability critic flagged as blocker-level
on the Large spec
Mark these `implementation: human-led`. They still get a full
contract (spec + critics + ACs + tests), but a human writes the code;
the pipeline does verify + ship. This is the honest part — Manifest
helps spec and verify the risky pieces without pretending to safely
auto-implement them.
### 5. Write the epic + children
Update the parent contract frontmatter to mark it an epic:
```yaml
type: epic
complexity: large
children: [AUTH-12a, AUTH-12b, AUTH-12c, AUTH-12d]
successMetric: <the overall metric — measured across the whole epic>
```
Create each child as its own contract at
`.manifest/contracts/<childId>.md`, with:
- `parent: <ID>` in frontmatter
- `dependsOn: [<other-childIds>]` for ordering
- `implementation: agent | human-led`
- **`repo: <name>`** — which repo this child lands in, from
`.manifest/repos.yml` (the seam is usually per-repo already: a backend
child → the backend repo, a web child → the web repo, mobile → mobile).
- **`owner: <dev>`** — the person on the hook for this child. Multi-person
features map naturally: two web children can carry two different FE owners
and run in parallel; the backend child carries the BE owner they both wait on.
- Its own behaviors, instrumentation, perf, comms, ACs (a real
Small/Medium contract — run `/contract verify` on each)
- A slice of the parent's goal
**Assign owners before finishing.** Decomposition produces the *shape* (which
children, in what order, in which repo); the dev/lead assigns the *people*. Ask
once, in one batch: "Who owns each child?" — e.g. *"SC-a (backend) → @be-dev;
SC-b + SC-d (web) → @fe-dev-1; SC-c (web) → @fe-dev-2."* Default `owner` to the
picker-upper if they don't split it. Record each on the child's frontmatter so
the rollup (below) can show the feature by person.
Write a decomposition plan to `.manifest/contracts/<ID>.decomposition.md`:
```markdown
# AUTH-12 decomposition
Epic goal: <one line>. Success metric: <metric> (measured across all children).
## Ship order
1. AUTH-12a — Backend: add /auth/v2 endpoint behind flag (Medium, agent)
repo: backend · owner: @be-dev · depends on: none
2. AUTH-12b — Data: migrate sessions table (Small, HUMAN-LED — hot table)
repo: backend · owner: @be-dev · depends on: AUTH-12a
3. AUTH-12c — Web: new login UI on /auth/v2 (Small, agent)
repo: web · owner: @fe-dev-1 · depends on: AUTH-12a, AUTH-12b
4. AUTH-12d — iOS + Android: mobile login on /auth/v2 (Medium, agent)
repo: mobile · owner: @fe-dev-2 · depends on: AUTH-12c
## Notes
- 12b is human-led: migration on the sessions table (security critic
flagged session-token handling as blocker-level on the epic spec).
- 12c and 12d can overlap once 12b ships.
```
### 5b. Create the JIRA tickets (opt-in) — the planning tracker
After the shape and owners are set, offer to mint the tickets so the tracker
mirrors the plan *before* anyone starts building. **Ask once, confirm the project
key:**
> "Create JIRA tickets for this epic now, in project `<KEY>`? (1 epic
> + <N> child issues, dependency links included.)"
On yes, follow `reference/JIRA-SYNC.md` §2:
- **Epic** = the parent, carrying the overall goal + success metric + gate code.
- **One child issue per child contract**, each with its full detail (behaviors,
ACs as a checklist, design link), **assignee = the child's `owner`**
(`lookupJiraAccountId`), labels `manifest` + size, and `human-led` where flagged.
- **Hierarchy**: link each child to the epic (Epic-Link / parent).
- **Dependencies**: turn each `dependsOn` into an "is blocked by" `createIssueLink`
between the corresponding child keys — so the DAG is visible in JIRA, not just
in the decomposition plan.
- **Store keys** on each child's frontmatter (`jira: <KEY>`) and on the epic
(`jira: { epic: <KEY>, project: <KEY> }`), plus mirror them in the parent's
`children` rollup block. These are what `implement` and the verify/launch steps
update as each child moves.
If Atlassian isn't connected or the dev declines, skip cleanly and note it — the
decomposition still stands; tickets can be created later at `/contract promote`.
### 6. Report
Tell the user:
- The epic and its N children, in ship order, with size + agent/human,
**owner + repo**
- Which children are human-led and why
- **The one-glance feature view:** `/status <epic-ID>` rolls the children up —
critical path, who's blocked on whom, and "the feature lands when all children
land." Point the dev/lead there for coordination.
- "Each child is a normal contract. Verify and promote them in order:
start with `/contract verify AUTH-12a`. The epic tracks the overall
metric; you'll see it land when the last child does."
## Anti-patterns
- Don't create children that are still Large — recurse until each is
Small/Medium.
- Don't mark a migration or auth change as agent-implementable to make
the plan look cleaner. Human-led is the honest call; respect it.
- Don't lose the success metric — it lives on the epic and is measured
across all children, not per-child.
- Don't decompose into so many tiny children that coordination
overhead exceeds the benefit. Aim for the fewest independently-
shippable pieces, not the most.
- Don't auto-promote children. The user verifies and promotes each in
dependency order.
Versions
The database has no other skills named contract-decompose.
Database snapshot: 13.11.2026 · package version 72e56a53b165 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100make-groups
Break a large plan, architecture proposal, or feature document into sequenced implementation groups for the make-plan pipeline. Use when user says "make groups", "group requirements", "sequence groups", or wants to decompose a large document into ordered implementation units. - 90decompose-gates
Decompose a hard or multi-part task into independently checkable pieces with explicit verification gates and risk-weighted ordering. Use when planning corridor-sized work, writing lane briefs for subagents or Codex, or whenever a task is too large to verify as a whole. - 82ase-task-dissect
Dissect the current or given task plan, treated as an epic, domain-wise and logically into cohesive parts and materialize each part as its own separate task plan. Use when the user calls to "dissect", "split", "break up", or "decompose" a large "task" or "plan". - 90decompose-goal
Break a fleet goal (or an epic, an audit area, a large ticket) into small, independent, testable tickets with one owner each — choose how to split (by slice, component, concern or file ownership), put contracts at the seams, draw a shallow dependency graph and staff the critical… - 100task-decomposition
Breaks down complex software, writing, or research tasks into small, atomic, independently completable units with dependency graphs and milestone breakdowns. Use when the user asks to plan a project, decompose a feature, create subtasks, split up work, or needs help organizing a… - 100epic-breakdown
Decompose large epics into sprint-ready sub-epics using 9 splitting patterns. Use this skill when: - A spec is approved and you need to break a large feature into estimable work items for engineering - You want to split an epic that is too large for a single sprint - You need…