Witness Decompose

witness-decompose — recap → sliced specs → gate

Ground rules (every witness skill)

Resolve the CLI once per session:

WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.13.0}"

• Render the CLI's decision output verbatim and in full — every line, unmodified. Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.
• The human decides; you may type it. Run a witness decide verb only when the human names an option — its number or its verb — and then run the printed string byte-for-byte: never recomposed, never reformatted, never with a placeholder you resolved yourself. The moment you compose a --note or resolve an id, you are authoring their decision. A bare affirmation ("ok", "sounds good", "yes") is not a selection — ask which option, especially where option 1 is --approve at a stop that exists because a human must look. A selection does not survive session death: killed and re-run, render the block again and ask again.
• Never edit specs/** or plans/** (the canon dirs — paths: in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under $(mktemp -d) and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)
• Read canon with witness read , never by path. Canon lives at the primary root; inside a worktree the files are absent by design, so a path read finds nothing and a stale copy cannot be mistaken for the contract. Fat artifacts: witness read --design --outline, then --lines -.
• Never invoke gate reviewers or relay verdicts. witness gate runs reviewers itself and journals what they said; your summary of a verdict is not evidence.
• Refusal repair loop: a witness verb exiting 2 prints structured violations (field · rule · got · want). Fix your input and retry — 3 total attempts per artifact, then stop, show the human the violation list verbatim, and end your turn.
• A refused or hook-blocked command is a stop, not a step to drop. Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.
• Re-entrancy: derive position from CLI output ($WITNESS next, the dashboard, log, index) — never from conversation memory. Killed and re-run, you must converge.

Inputs (rebuild them, never remember them)

$WITNESS log      # the latest recap entry is your contract: class, goals g*, non-goals n*, constraints c*
$WITNESS index            # live canon: id · summary · status · depends, grouped by dir
$WITNESS decide decompose  --show   # ONLY when re-entered after a revise

The class comes from the recap. Never ask for it again.

Route by class

• feature — slice (next section). Expect the gate to stop for scope approval afterwards: that is the standing stop working, not a failure.
• fix — find THE one spec to amend: match the broken behavior against witness index summaries; when summaries tie, grep the specs dir read-only at the primary root (searching across canon is not an artifact read, and there is no verb for it — the read rule governs reading an artifact you have already identified). Amend exactly one spec. If the fix genuinely needs a brand-new spec, write it — the gate's tripwire stops for a human, which is the designed check on your routing (on a young canon this fires often; say so rather than fighting it).
• chore — write NO specs (a chore writing spec content is refused at write time, by definition of the class). There is nothing here for you: next routes a chore straight to the plan stage, because the decompose gate refuses nothing-to-gate without written specs and write refuses spec content from a chore — the stage is unsatisfiable in both directions. The parent for the coming plan is chosen when that plan is authored. Hand back immediately if you were invoked for one.

Slicing rules (feature)

• Thin vertical slices: each spec independently shippable, observable end-to-end. Never layers ("the schema", "the client").
• Each spec answers exactly one question; no two overlap; one fact, one home. A fact needed by two slices gets extracted into its own spec, and both depends on it.
• Amending a living spec is the same write with the existing id — its status resets to draft (re-approval owed). If the CLI warns the spec has an in-flight child plan, surface that warning at the gate stop.
• Boundary changes (split, merge, extraction out of a live spec) → the new spec's manifest carries supersedes: ; rewrite every dependent's depends in the same effort — the CLI refuses dangling edges.
• Cross-cutting changes → sequenced per-slice amendments ordered via depends, expand-contract style (accept both → switch → drop old), each step independently shippable.
• Self-check totality before gating: every goal covered by ≥ 1 spec, every spec covers ≥ 1 goal.

Author each spec

Manifest + body in scratch, then the write:

DIR=$(mktemp -d)
cat > "$DIR/meta.json"  "$DIR/body.md"  --meta "$DIR/meta.json" --body "$DIR/body.md"

Get these right the first time — the dashboard trends your first-try valid rate:

• summary ≤ 120 chars: what the slice is (Motivation carries the why).
• criteria: ≥ 1 entry, unique ids, each exactly one of test (value must be @spec:) or cmd. A criterion that cannot fail is not a criterion.
• covers: the recap goal ids this spec honestly advances — the critic judges the mapping's quality.
• Body: exactly the ## Motivation and ## Behavior headings; behavior-only — internal interfaces never appear in a spec.
• id: [a-z0-9-]+; new ids land at specs/.md (or the repo's configured specs dir).
• needs: external prerequisites only, machine-checkable (env: / cmd: / manual: + satisfied).
• ui: set ui: true in the manifest iff the slice changes browser-rendered or interactive behavior (a screen, a form, client-side interaction). A browser-behavior slice without the flag, or a flag on a non-UI slice, is a slicing-critic finding. A ui spec earns a design stage before its plan — the look is approved before code (Decision 69).

Gate

$WITNESS gate decompose --effort     # append --manual when the run asked for it

• Auto-pass (green path) → done; hand back to /witness.
• Stop (standing stop, blocking findings, fix-created-spec tripwire) → render the gate output verbatim and in full, including its ranked options and run: line, and END YOUR TURN. You never decide.
• Re-entered after --revise → decide --show reconstructs the verdict + human note; findings anchor to spec headings. Fix via new witness write calls (same ids amend in place), self-check totality, re-gate. The 3-round bound is the CLI's — surface it, never fight it. --show also emits state: and exits: — a reopened or settled state means the verdict above it is history, so act on the exits: line, not on remembered findings.
• Findings implicate the scope itself (goals wrong, not slicing wrong)? Tell the human that --revise --upstream on the stop screen routes back to re-interview via witness recap --amend.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: popovych-co
• Source: popovych-co/witness
• License: MIT
• Homepage: https://www.npmjs.com/package/@popovych.co/witness

Install and usage instructions live in the source repository linked above.