Contract decompose

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:

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:

# 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.