| 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)
- One stage per invocation; a stage writes its own card and nothing else.
- Refutation never happens in-context — it is the
refuter agent, dispatched fresh;
its brief lists exactly what it may read.
- No silent drops: every confirmed finding gets a 07-revise row (fix, or stated override).
- Divergence law: 08-answer's pick equals the committed/revised pick; any change routes
through a 07-revise row. Script-checkable.
- Cite-trace-ids law: 08-answer's load-bearing claims cite
[NN] ids of files that
exist in the run's trace dir.
- 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) |
