Skip to content
Skills Library
Management & product · Planning

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.

Repository
manifest ↗
Licence
MIT
Last repository change
02.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 02.09.2026, without references to retired models or APIs.

Licence

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

decomposebreak this downsplit this epict refused — it
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

  1. When this runs
  2. Process
  3. Anti-patterns
Original SKILL.md headings · 178 lines, 1,224 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.