# Witness Decompose > Slice a witness effort's confirmed recap into vertical spec slices, or route a fix to the one spec it amends — manifests handed to witness write, then the decompose gate. Chores never reach this stage. Normally invoked by /witness with the effort slug. - **Type:** Skill - **Install:** `agentstack add skill-popovych-co-witness-witness-decompose` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [popovych-co](https://agentstack.voostack.com/s/popovych-co) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [popovych-co](https://github.com/popovych-co) - **Source:** https://github.com/popovych-co/witness/tree/main/plugin/skills/witness-decompose - **Website:** https://www.npmjs.com/package/@popovych.co/witness ## Install ```sh agentstack add skill-popovych-co-witness-witness-decompose ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # witness-decompose — recap → sliced specs → gate ## Ground rules (every witness skill) Resolve the CLI once per session: ```bash 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) ```bash $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: ```bash 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 ```bash $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](https://github.com/popovych-co) - **Source:** [popovych-co/witness](https://github.com/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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-popovych-co-witness-witness-decompose - Seller: https://agentstack.voostack.com/s/popovych-co - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.