Witness Brainstorm

witness-brainstorm — scope interview → confirmed recap

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.

What you produce

No canon, only evidence: a confirmed scope recap persisted by witness recap as the birth entry of the effort journal. This skill writes no spec, no plan, no brief — decompose consumes the recap after you, including after session death.

Interview protocol

One question per turn. Every question carries the same five fields the CLI's decision block uses, so a human meets one shape everywhere in this pipeline: a concrete recommendation, a one-line why, the strongest alternative, when that alternative is the right call, and the tradeoff it carries against the recommendation. Add a short note to either option only when running with it has a caveat the option itself does not state. Lock each answer before the next; walk in dependency order:

1. Class — feature | fix | chore. Recommend from the opening ask: fix restores promised behavior; chore is motion with no state change (deps, tooling); everything else is feature.
2. Problem & outcome goals — what observably changes, for whom. Number them g1, g2, …. Each goal is an outcome someone can observe — "Guests can pay by card", never "Integrate Stripe".
3. Non-goals — what this effort deliberately will not do: n1, n2, …. Push for at least one; scope without a "no" is unbounded.
4. Constraints — standing limits (compliance, performance budgets, compatibility): c1, …. Empty is fine.
5. Slice candidates — non-binding thin vertical slices you would expect decompose to cut. Plain strings.

Short forms. fix: two questions — (1) what breaks, with the observable evidence; (2) the fix boundary — what must NOT change (its non-goals). chore: two questions — what maintenance, which area it touches.

Confirmation

Render the recap as a table (class · goals · non-goals · constraints · slices) and get an explicit yes. Adjust and re-render until confirmed. The recap is decompose's input contract — a fuzzy recap poisons every stage after it.

Persist

DIR=$(mktemp -d)
cat > "$DIR/recap.json"  --file "$DIR/recap.json"`. An amendment re-arms the decompose gate's feature-class stop: scope changed, scope gets re-approved.
- The refusal repair loop applies (3 attempts, then stop with the violation list).

## Stateless by design

Session died mid-interview? Start over — nothing was persisted; that is the accepted cost. If the dashboard's efforts table already shows the effort (the recap landed), do not re-interview — hand back to /witness.

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