# Decompose

> Decompose the active Architect workflow's plan.md into a runnable tracer and dependency-ordered vertical tickets. Use only when the user invokes $decompose.

- Skill: `sergdort/decompose` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add sergdort/decompose`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sergdort/decompose/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: sergdort (https://skillmd.com/u/sergdort)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sergdort/decompose

---


Operate in the main thread as Architect. Decompose the reviewed plan into
independently implementable tickets under `tickets/`. Do not write product code.
Draft and validate the cut before asking for approval.

Use any path accompanying the invocation to resolve the plan:

- A named Markdown file is the plan path.
- A named directory resolves to `<directory>/plan.md`.
- Otherwise use `plan.md` in the current working directory.

Read the plan first. If it is missing, tell the user to invoke `$plan-feature`
and stop. Read `decision-brief.md` next to it when present. Tickets live in
`tickets/` next to the plan.

## Existing Tickets

If the tickets directory already contains files:

1. Derive completed ids from commit messages with a full line exactly equal to
   `Ticket: <id>`.
2. Classify the request as an accidental collision, a full replacement with no
   completed work, or an incremental re-decomposition.
3. Stop and explain the proposed treatment.
4. Get explicit approval before writing or removing ticket files.

For a full replacement, replace open or blocked tickets with fresh ids. For an
incremental re-decomposition, preserve completed ticket files and ids unchanged,
replace only open or blocked tickets with fresh ids, and add corrective tickets
when the new plan invalidates accepted behavior. Never rewrite an accepted
ticket or reuse its id.

This approved replacement is part of the active workflow. It does not authorize
end-of-workflow cleanup or replacement of artifacts from a different workflow.

## Cut Rules

Every ticket must be implementable by a fresh `developer` from only the ticket,
plan, brief, repository seeds, and an optional correction brief.

1. **Start with a runnable tracer.** The first behavior ticket has
   `tracer: true` and delivers the smallest observable path through the system.
   It proves the path at the closest real browser, CLI, API, integration, or
   public library boundary. Every later behavior ticket depends on it directly
   or transitively.
2. **Use a contract ticket only when justified.** It may precede the tracer only
   for a narrow, stable external or shared boundary that consumers require
   first, such as a schema, protocol, or ABI. State the justification. Typed
   code and easy stubs are not justification.
3. **Cut later work vertically.** Each behavior ticket owns observable behavior
   end to end and carries a subset of the plan's Gherkin scenarios.
4. **Size for review and proof.** Prefer a diff one person can review in one
   sitting, roughly 100-200 hand-written changed lines when practical. Explain
   larger slices that cannot split without losing end-to-end proof.
5. **Declare ownership.** Each ticket has a `scope`. Inspect sibling overlap;
   deliberate serial overlap can be valid for routers, schemas, and registries.
6. **Place checkpoints.** The tracer always has `checkpoint: human`. In a
   high-risk workflow, mark load-bearing, migration, security, persistence, and
   hard-to-reverse slices the same way. Final human review remains required.
7. **Preserve effective history.** Keep a completed tracer if it still proves
   the path. If invalidated, create a fresh correcting behavior ticket with
   `tracer: true` and `corrects: [<old-tracer>]`.

## Proposed Cut And Approval

Draft the full cut in memory. Present each ticket's id, title, type, tracer,
checkpoint, dependencies, expected scope, scenarios, and Observable Proof.
Present preliminary gate results. Wait for explicit user approval before
creating, changing, or removing ticket files.

## Ticket Schema

After approval, write one file per new ticket at `tickets/<id>.md`:

```md
---
id: auth-001
title: <short imperative title>
type: behavior
tracer: true
checkpoint: human
status: open
deps: []
corrects: []
scope:
  - Sources/Auth/Login.swift
  - Tests/AuthTests/LoginTests.swift
gherkin:
  - "@must Login succeeds with valid credentials"
seeds:
  - Sources/Auth/AuthService.swift
verification: test-first
---

## Goal
One or two sentences.

## Contract
The interface slice this ticket materializes, referencing the plan's Execution
Sketch. A contract ticket also justifies its behaviorless predecessor.

## Acceptance Criteria
Concrete criteria derived from the assigned scenarios.

## Observable Proof
How to exercise the slice through a real boundary. A public-interface test is
acceptable for pure library work. A contract ticket names its compile, schema,
or compatibility check.

## Notes
(left empty at creation; escalation notes only)
```

Allowed frontmatter values:

- `type`: `behavior` or `contract`
- `tracer`: exactly one effective behavior ticket is `true`
- `checkpoint`: `human` or `none`
- `status`: `open` or `blocked`; never store done, ready, or in-progress
- `verification`: `test-first`, `implementation-first`,
  `characterization-first`, or `manual-verification`, plus a command when useful

A contract ticket owns no Gherkin scenarios and normally has `tracer: false`.

`corrects` retires each named completed ticket from current-plan ownership in
full. A correcting behavior ticket carries every still-current, non-deferred
scenario from the historical ticket plus the corrected behavior. Use an
extension ticket without `corrects` when old behavior remains current. Only the
tip of a correction chain is effective.

## Mechanical Gate

Run these checks before presenting the cut and again against disk after writing:

- **Coverage:** every non-deferred scenario belongs to exactly one effective
  behavior ticket; deferred scenarios belong to none.
- **Tracer:** exactly one effective behavior ticket is the first observable
  slice, and later behavior reaches it through dependencies.
- **Contract justification:** any predecessor is narrow, stable, and has named
  consumers.
- **DAG and references:** dependency and correction graphs are acyclic. Deps
  resolve to effective or preserved completed tickets. `corrects` resolves only
  to preserved completed tickets.
- **Observable proof:** every behavior ticket reaches a real boundary.
- **Human review:** tracer and high-risk checkpoints match the plan.
- **Reviewability:** likely large tickets are flagged and justified.
- **Scope overlap:** every sibling overlap is reported as deliberate and serial
  or corrected as a bad cut.
- **Verifiability:** every ticket declares a method.
- **Seeds exist:** check every seed path mechanically against the current disk.
  Future files belong in Contract, not seeds.
- **Scope sanity:** flag scope paths whose parent directory is also missing.
- **Id hygiene:** filename stem equals frontmatter id; new ids are unique and do
  not already appear as an exact `Ticket: <id>` trailer. Preserved completed ids
  are exempt.

## Write And Re-check

After approval, preserve completed files, write the approved fresh files, and
remove only replaced open or blocked files from this active workflow. Rerun the
gate against disk and full commit messages.

Ticket files are temporary and remain uncommitted. Never stage or commit the
brief, plan, or tickets. The user owns final cleanup.

If decomposition reveals a wrong program design, stop and send the user back to
`$plan-feature`. Do not hide the flaw in ticket wording.

## Final Response

Report:

- plan and tickets paths
- preserved, created, replaced, and removed tickets
- coverage, tracer, DAG, proof, review, scope, seed, and id gate results
- open questions
- the next explicit invocation: `$start-work`