thinking-protocol

name	thinking-protocol
description	The staged external-thinking protocol: micro-invocations that write a durable trace so a first draft cannot be delivered as the final answer. Use when / Trigger: executing or resuming a thinker run (/thinker:think, /thinker:resume, the think_trigger hook card), or any hard question needs a reasoned, auditable answer — a diagnosis, design choice, estimation, tradeoff, causal-why, or plan.

The thinking protocol

A first draft is not a conclusion. The source suite says so in an advisory card (plugins/maestro/hooks/self_challenge_gate.sh in the source repo) but leaves the rounds in-context and self-reported. This skill makes them structural: each stage is one invocation that reads the trace-so-far and writes exactly one fixed card, the refute stage is a separate fresh-context agent, and the answer stage is only reachable through the trace. Rationale: docs/plugins/thinker.md (marketplace repo).

The eight stages

#	stage	writes	one job	phase file
1	restate	01-restate.md	problem in own words + knowns/unknowns table	references/stage-1-restate.md
2	frame	02-frame.md	problem type by lookup over references/problem-taxonomy.md	references/stage-2-frame.md
3	candidates	03-candidates.md	≥2 approaches, fixed slots: idea / cost / risk / reversibility	references/stage-3-candidates.md
4	score	04-score.md	the type's criteria table (references/scoring-criteria.md), cells 0/1/2, arithmetic sums	references/stage-4-score.md
5	commit	05-commit.md	the pick + one why-not line per rejected candidate	references/stage-5-commit.md
6	refute	06-refute.md	SEPARATE invocation — the refuter agent, fresh context, pre-written probes, output attached	references/stage-6-refute.md
7	revise	07-revise.md	one row per confirmed finding: fix, or override with a stated reason	references/stage-7-revise.md
8	answer	08-answer.md	only now; load-bearing claims cite trace ids	references/stage-8-answer.md

Tiers (computed harness-side — never self-sized)

tier	stages run	refute shape
T1	restate → commit → answer	none — the short-circuit for trivial asks
T2	all 8	one fresh-context refuter vote
T3	all 8	3 independent refuter votes; per-finding majority; evidenced findings always confirmed; ≥2 unevidenced dissents → +2 votes once (the M7 bump)

Tier source, in order: an explicit T1|T2|T3 argument → the tier in the trigger card (taken from the newest .maestro/evidence/*/sizing.json) → default T2. "Think harder" is never a self-judgment; it is a tier.

The trace contract

• Store of record: the M5 run store — one runs row (pipeline thinker) + one run_steps row per stage; v_next_step drives execution and resume. Files never drive resumption.
• Mirrors: .thinker/trace/<run>/<NN>-<stage>.md, NN = the fixed stage number (01–08) in every tier, so citations stay stable. Each card's schema is inline in its phase file — the card is the stage's entire output.
• Checkpoint order per stage: artifact to disk → run_steps row → runs.current_step.
• All store SQL lives in one place: references/run-state.md.

Laws (always in force)

1. One stage per invocation; a stage writes its own card and nothing else.
2. Refutation never happens in-context — it is the refuter agent, dispatched fresh; its brief lists exactly what it may read.
3. No silent drops: every confirmed finding gets a 07-revise row (fix, or stated override).
4. Divergence law: 08-answer's pick equals the committed/revised pick; any change routes through a 07-revise row. Script-checkable.
5. Cite-trace-ids law: 08-answer's load-bearing claims cite [NN] ids of files that exist in the run's trace dir.
6. A failed stage blocks the run by construction (no v_next_step row) — report it; never improvise past it.

Boundaries

non-goal	rule
inflating trivial asks into ceremony	T1 = 3 stages; the tier is computed, not felt
replacing native extended thinking	OPEN question (docs/plugins/thinker.md, flagged not decided) — default here: run anyway when an auditable trace is wanted, since a gate can require a trace but cannot see native thinking
replacing adversarial-verify / done-gates	thinker disciplines reasoning before an answer; verification of work products stays with the existing gates

Files in this skill

file	load when
references/run-state.md	creating, resuming, checkpointing, failing, or reporting a run
references/stage-<n>-<slug>.md	executing that stage — one at a time, never bulk
references/problem-taxonomy.md	stage 2 (frame)
references/scoring-criteria.md	stage 4 (score)