Brummel/Skills
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(boss): bolder autonomous /boss — grounding-PASS auto-sign, rollback sandbox, reference issue

Browse Source 
Retire the obligatory five-lens spec-skeptic auto-sign panel (worst case
18 agent runs per spec under /boss). The autonomous signature is now the
Step-5 grounding-check PASS alone — an independent fresh-context agent's
verdict against currently-green tests; a no-override BLOCK/INFRA_ERROR
routes to the human sign-off pause.

The judgement the panel applied moves upstream into specify Step 1.5,
whose stance inverts: a load-bearing fork the orchestrator can DERIVE an
answer for (sources, code, consistency, risk) is decided boldly and
recorded on the run's reference issue; only a pure-preference fork
bounces. spec-skeptic survives as an optional ad-hoc bias-breaker the
orchestrator pulls when unsure whether its leaning is judgement or bias —
not a gate, not a veto.

Every /boss run carries a mandatory reference issue (created if the cycle
had none): the fork-decision log, the orchestrator's cross-run memory,
and the only surviving trace of a hard-dropped attempt.

Relax main-sacrosanct below the session anchor: within an autonomous run
the orchestrator may git reset --hard its OWN UNPUSHED commits above the
anchor on a dead end — never below the anchor, never a pushed commit
(forward-only/revert). Discarded attempts are hard-dropped, no parking.

Verified across the 9 edited files by a 4-lens adversarial review
(retired-panel residue, cross-file contracts, rollback-boundary safety,
stance coherence): unanimous SOUND. Baseline tagged pre-autosign-rework.

closes #8
This commit is contained in:
Brummel
2026-06-19 00:06:44 +02:00
parent 012e70b058
commit eb74f99bd4
9 changed files with 470 additions and 388 deletions
Download Patch File Download Diff File Expand all files Collapse all files
specify/SKILL.md
+190 -194
View File
@@ -17,7 +17,7 @@ planner consumes: with review, but **without an interview**.
It is the **sole home of the spec-production gates**: the
feature-acceptance criterion, the write-spec step, the
`grounding-check` hard-gate, and the user-review gate. Whichever way design work enters — fresh
`grounding-check` hard-gate, and the sign-off gate. Whichever way design work enters — fresh
through `brainstorm`'s discovery, or directly from sources that
already resolve the design — it passes through `specify` to become a
spec. `specify` carries the universal invariant **no plan without an
@@ -61,28 +61,34 @@ Triggers:
**Skipping a gate is never permitted.** The interview is `brainstorm`'s,
and its absence here is the whole point — but the *production gates*
(criterion, grounding-check, user-review) are
(criterion, grounding-check, sign-off) are
non-negotiable regardless of how the work entered. "The issue looks
exhaustive, skip the grounding-check" is the reactive-deference failure
this skill must not reintroduce.
this skill must not reintroduce. (Under `/boss` the sign-off gate is the
`grounding-check` `PASS` itself — see Step 6.)
## The Iron Law
```
THE SOURCES MUST RESOLVE EVERY LOAD-BEARING DESIGN DECISION BEFORE THE SPEC IS WRITTEN.
IF WRITING THE SPEC FORCES A CHOICE BETWEEN PLAUSIBLE DESIGNS THE SOURCES DO NOT RESOLVE,
STOP AND BOUNCE TO brainstorm. DO NOT SILENTLY PICK ONE.
THE PRODUCTION GATES — ACCEPTANCE CRITERION, GROUNDING-CHECK, USER-REVIEW —
EVERY LOAD-BEARING DESIGN DECISION MUST BE RESOLVED BEFORE THE SPEC IS WRITTEN — BUT
"RESOLVED" INCLUDES A FORK THE ORCHESTRATOR CAN DERIVE AN ANSWER FOR (FROM THE SOURCES,
THE CODE, EXISTING-DESIGN CONSISTENCY, OR RISK). A DERIVABLE FORK -> DECIDE IT BOLDLY AND
RECORD THE DECISION IN THE REFERENCE ISSUE. ONLY A FORK THAT HANGS ON PURE USER PREFERENCE
WITH NO DERIVABLE BETTER -> STOP AND BOUNCE / PAUSE. DO NOT BOUNCE A FORK YOU CAN DECIDE.
THE PRODUCTION GATES — ACCEPTANCE CRITERION, GROUNDING-CHECK, SIGN-OFF —
ARE NON-NEGOTIABLE REGARDLESS OF ENTRY PATH.
NO PLAN, SCAFFOLDING, OR DOWNSTREAM SKILL UNTIL THE SPEC IS APPROVED — BY THE USER, OR
(UNDER /boss) BY THE AUTO-SIGN GATE: ALL OBJECTIVE GATES GREEN
AND A UNANIMOUS ADVERSARIAL spec-skeptic PANEL. MODEL SELF-CONFIDENCE ALONE IS NEVER APPROVAL.
(UNDER /boss) BY A grounding-check PASS. MODEL SELF-CONFIDENCE ALONE IS NEVER APPROVAL;
THE grounding-check IS AN INDEPENDENT FRESH-CONTEXT AGENT, NOT THE PRODUCER'S CONFIDENCE.
```
Every clause is non-negotiable. The precondition gate is what makes
the no-interview path legitimate rather than merely convenient: it is
the honest fork-check that `tdd`'s "is this test-specifiable?" is for
test work.
test work. Its bar is *decidability*, not *pre-settlement*: a fork the
orchestrator can ground an answer for is resolved by deciding it; only a
fork that turns on the user's own preference, with no derivable better,
is the one that bounces.
## The Process
@@ -107,56 +113,86 @@ Enumerate the **load-bearing design decisions** the spec must encode
— the choices that, decided differently, would change what ships.
For each, ask the honest question:
> Do the sources **resolve** this, or am I about to **pick** it
> myself?
> Can I **derive** an answer for this fork — from the sources, the
> code, consistency with the existing design, or relative risk — or
> does it turn on a **preference only the user holds**?
If every load-bearing decision is resolved by the sources, proceed to
Step 2. If even one is unresolved — the sources leave a genuine fork
between plausible designs with real trade-offs — **STOP and bounce to
`brainstorm`** (see Error handling / The Bounce-Back). Do not silently
pick one and bake it into the spec; a guessed design ratified into a
spec is harder to dislodge than an open question, and it is exactly
the reactive-deference failure the gate exists to prevent.
This is a *decidability* test, not a *pre-settlement* test, and the
default is **decide, not bounce**:
Genuine doubt about whether the sources resolve a decision *is itself*
the fork signal — it resolves to a bounce, not to a guess.
- **Derivable fork → decide it boldly.** If there is a groundable
reason to prefer one option — it fits the existing design better, it
is simpler, it carries less risk, the sources lean that way — the
orchestrator decides it and proceeds. It does **not** bounce a fork it
can actually answer. When unsure whether its own leaning is bias
rather than judgement, it pulls **one** independent opinion — an
ad-hoc `spec-skeptic` lens (see Step 6) — and weighs it; the lens
informs the decision, it does not veto. Every derived decision is
**recorded in the reference issue** (below) with its rationale.
- **Pure-preference fork → bounce / pause.** Only when the fork turns on
something the orchestrator cannot derive — roadmap order, product
taste, two genuinely equivalent paths whose trade-off only the user
can weigh — is it a real bounce. Then **STOP and bounce to
`brainstorm`** (see The Bounce-Back), or under `/boss` route to the
human sign-off pause. A guessed *preference* baked into a spec is the
reactive-overreach this gate still prevents.
**Reconciliation comment (lagging-issue case).** A load-bearing fork can
be resolved by the in-context design discussion yet still be listed
*open* by the tracker issue that seeded the cycle — the issue lags the
conversation. When that holds (entry is in-context **and** a tracker
issue still carries a now-resolved fork as open), record the resolution
as an auditable issue comment **before** writing the spec, via the
project's issue-tracker comment command (`tea comment <idx>` for Gitea;
a heredoc body per the `issue` skill's conventions). One comment, this
exact shape:
The old "genuine doubt *is* the fork signal → bounce" reflex is
**retired**: doubt about whether you can derive an answer resolves to an
honest attempt to derive it (with a bias-breaker if needed), not to a
reflexive bounce. Being wrong on a derived call is allowed — the net is
the user's veto and, under `/boss`, the rollback sandbox
(`../boss/SKILL.md` § Direction freedom). What is *not* allowed is
dressing a pure-preference guess as a derived decision.
**Every `/boss` run carries a reference issue.** The run is always
anchored to a tracker issue — an existing one that seeded the cycle, or
one the orchestrator creates when the work was settled in pure chat with
no prior issue (the mechanic below). That issue is the run's **decision
log**: as the orchestrator derives fork answers, it comments each one
there, so the user can audit and veto after the fact and the orchestrator
has a cross-run "issue memory". Because a `/boss` dead-end is recovered
by hard-dropping the autonomous commits (no attempt branch survives), the
issue's comment thread is also the **only surviving trace** of an
abandoned attempt — which is the second reason it is mandatory, not
optional.
A comment records one of two distinct things, and the distinction is
load-bearing:
- A **user decision** the conversation settled — minuted with
**provenance** (a verbatim user statement, or explicit attribution +
date). Legitimate: you are recording what the user chose.
- A **derived orchestrator decision** — recorded with its **rationale**
(why one option is groundably better). Legitimate under the new stance,
but it must be labelled as what it is: a derived call, never disguised
as a user decision. If you cannot state a rationale, the fork was not
derivable — that is a pure-preference bounce, not a comment.
**Reconciliation comment (lagging-issue case).** A fork can be resolved
— by a user decision in the discussion, or derived by the orchestrator —
yet still be listed *open* by the tracker issue that seeded the cycle.
When that holds, record the resolution as an auditable issue comment
**before** writing the spec, via the project's issue-tracker comment
command (`tea comment <idx>` for Gitea; a heredoc body per the `issue`
skill's conventions). One comment, this shape:
```
## Design reconciliation (specify, in-context entry)
## Design reconciliation (specify)
Spec: <spec-name>. The fork(s) below are still listed open on this
issue; they were resolved in the in-context design discussion.
issue; this records their resolution.
- **Fork: <name>** → <decision>.
Provenance: <verbatim user statement, or explicit attribution + date>.
Basis: <verbatim user statement + attribution, OR "derived:" + the
groundable rationale>.
```
The comment must carry **provenance**, and the distinction is
load-bearing: it is the *record of a user decision* (legitimate — the
user settled the fork in discussion, you are minuting it), never a *new
orchestrator decision* dressed as settled (illegitimate). A bare
`decision: B` with no provenance is the latter. If you cannot point to a
real user statement, that is the signal that *you* picked the fork, not
the user — which is a Step-1.5 bounce, not a comment. The comment is
*persistent and auditable* (author + timestamp, in the forward queue) —
which is exactly why it, and not your ephemeral confidence, is what a
downstream `scope-fork` juror reads to confirm the fork is settled (see
Step 6). Recording it keeps the forward queue honest in either run mode;
under `/boss` it is *load-bearing* — without it the `scope-fork` juror
sees only the stale issue body and (correctly) blocks.
Provenance enforcement is not yours to self-certify: you *write* the
comment, the adversarial `scope-fork` juror *checks* it carries
provenance (Step 6). Writing a provenance-less comment does not buy a
pass — the re-dispatched juror blocks on it.
`Basis:` carries either provenance (user decision) or rationale (derived
decision) — both are auditable, neither is a bare `decision: X` with no
support. The comment is *persistent and auditable* (author + timestamp,
in the forward queue) — which is exactly why it, and not your ephemeral
confidence, is what the user reads to understand and veto a call made
without them. Recording it keeps the forward queue honest in either run
mode.
Gitea writes are pre-authorized (per `~/.claude/CLAUDE.md`); post the
comment without a confirmation prompt.
@@ -164,8 +200,8 @@ comment without a confirmation prompt.
**Issue-less in-context entry.** If the cycle has *no* tracker issue —
the design was settled in pure chat — there is no existing artefact to
comment on, so *create one*: open a new tracker issue that records the
resolved fork(s) with provenance, under the same discipline as the
reconciliation comment above. The body takes this shape:
resolved fork(s) under the same discipline as the reconciliation comment
above. The body takes this shape:
```
## Design record (specify, issue-less in-context entry)
@@ -173,38 +209,26 @@ This issue seeds <one-line identity of the work>. The design was settled
in an in-context discussion with no prior tracker issue; this records it.
Load-bearing fork(s) resolved:
- **Fork: <name>** → <decision>.
Provenance: <verbatim user statement, or explicit attribution + date>.
Basis: <verbatim user statement + attribution, OR "derived:" + rationale>.
```
The body names the *work*, not the spec file — the spec does not exist
yet at Step 1.5 (its number is assigned only in Step 3). This new issue
is the cycle's seeding issue from here on: the `scope-fork` juror reads
it via the project's issue show command — its index handed to the juror
in the Step-6 carrier (the `seeding_issue` field, below) — exactly as it
reads any seeding issue. A *new issue* is the right artefact where a spec-note
is the wrong one — a provenance note *inside the spec* is
self-referential (the spec asserting its own sources settle it) and
stays banned, but a separate issue is independent (author + timestamp,
in the forward queue, juror-readable without opening the spec), as
auditable as a reconciliation comment. Creating it is what lets the
`scope-fork` juror ratify the resolution here, instead of blocking for
lack of an auditable source.
The provenance gate is unchanged and load-bearing: the new issue records
*user* decisions, never fresh orchestrator ones. No real user statement
for a fork means *you* picked it — a Step-1.5 bounce, not an issue to
manufacture. You *write* the issue; the adversarial `scope-fork` juror
*checks* the provenance, and a provenance-less body buys no pass.
is the run's reference issue from here on: the orchestrator comments
later derived decisions on it as the run proceeds, and a downstream
ad-hoc `spec-skeptic` can read it via the project's issue show command if
the orchestrator pulls one. A *new issue* is the right artefact where a
provenance note *inside the spec* would be the wrong one — a note inside
the spec is self-referential (the spec asserting its own sources settle
it) and stays banned, but a separate issue is independent (author +
timestamp, in the forward queue, readable without opening the spec).
Create it via the project's issue-create command (the `issue` skill's
mechanics — `tea issues create` for Gitea), title and label per the
project's vocabulary as in the Step-5 failure-mode procedure. Gitea
writes are pre-authorized, so create it without a confirmation prompt.
**Capture the new issue's index** the moment it is created and carry it
into the Step-6 panel as the `seeding_issue` field — it is the only way
the `scope-fork` juror knows which issue to read. An issue created but
never handed to the panel is invisible to the juror, which leaves the
fork looking picked and the creation pointless.
project's vocabulary. Gitea writes are pre-authorized, so create it
without a confirmation prompt. **Capture the new issue's index** the
moment it is created — it is the run's reference issue, the target for
every later decision comment.
### Step 2 — Apply the project's feature-acceptance criterion
@@ -347,7 +371,10 @@ report and requires a fresh dispatch of `grounding-check` before the
Step-6 sign-off and commit. Step 5 is the *last* step that touches the
spec file; nothing slips between it and the commit.
### Step 6 — User-review gate
### Step 6 — Sign-off gate
Outside `/boss` the signature is the user's; under `/boss` it is the
Step-5 `grounding-check` `PASS` (the `/boss` subsection below).
The spec sits in the working tree as an unstaged file. Tell the user:
@@ -366,94 +393,54 @@ the commit itself. The spec is an ephemeral active-cycle artefact: it
lives in the repo only for its own cycle and is `git rm`'d at cycle
close (see `docs/conventions.md` § Lifecycle).
**In `/boss` (autonomous):** `specify` is dispatched autonomously —
it is bounded (no interview). It runs the criterion, parse, and
grounding-check gates without a checkpoint. At *this* gate the
orchestrator signs in the user's place, but only through the
**auto-sign gate** below — never on its own confidence. The gate
exists because the orchestrator that wrote the spec is the worst-placed
party to judge it, so it is built to *not* rely on that confidence. The
human sign-off pause is not the default here; it is where the gate
**escalates** — a spec that cannot clear the gate routes to a
problem-state notify ("spec X ready, please sign off") and waits for the
user, exactly as a plain pause would. Run the gate in two stages:
**In `/boss` (autonomous):** `specify` is dispatched autonomously — it
is bounded (no interview), so there is no user at this gate to take the
signature. The signature comes from the **Step-5 `grounding-check`
`PASS`**: an independent fresh-context agent's verdict against
currently-green tests, not the producing orchestrator's confidence — and
that is what the bold stance trusts in the user's place. There is **no
adversarial panel**, no objective-gates-then-panel staging, no
self-correction loop; those were retired in favour of decide-upstream +
recover-downstream (baseline tag `pre-autosign-rework`).
1. **Objective gates (all must already hold — these are facts, not
judgements):**
- Step 1.5 precondition gate passed cleanly — no load-bearing
fork was silently picked (if one had been, `specify` would have
bounced, so reaching here is the evidence; do not re-decide it).
- Step 4 self-review clean, **including the placeholder scan** (no
`TBD` / `TODO` / incomplete section).
- Step 5 `grounding-check` returned **`PASS`** — *not* an
overridden `BLOCK`. An override needs a human; with no human in
the loop a `BLOCK` can never be overridden, so any non-`PASS`
grounding result denies auto-sign outright.
- On a Step-5 **`PASS`**: commit the spec yourself (subject `spec:
<cycle> <topic> (boss-signed)`), fire the auto-sign notify (see `boss`
§ Notifications — it names the capability in user terms and states the
plan is proceeding and a reply vetoes), then proceed to Step 7. No
pause.
- On a Step-5 no-override **`BLOCK`** or **`INFRA_ERROR`**: there is no
human to override it, so it routes to the human sign-off pause — a
problem-state notify ("spec X needs your sign-off") — exactly as the
Step-5 failure mode describes. A no-override grounding `BLOCK` is the
one objective denial of an autonomous sign and is never signed over.
If any objective gate is not green, **do not run the panel** —
fall straight to the human sign-off pause (the default-slot
behaviour above), carrying the failing gate in the notify.
The judgement that used to live in the panel now lives **upstream**, in
Step 1.5's bold-decide stance: a load-bearing fork is *decided* there
(with an ad-hoc `spec-skeptic` bias-breaker if the orchestrator wants
one) and recorded in the reference issue, or — if it is a pure-preference
fork — bounced before the spec is ever written. By the time a spec
reaches this gate the only thing left to verify is the objective one the
`grounding-check` already verifies. Editorial defects the old panel would
have caught (a clumsy worked example, a two-way-readable sentence) are
allowed through **deliberately**: they are cheap to patch inline
downstream, and catching them was never worth an obligatory five-juror
panel on every spec.
2. **Adversarial panel (unanimous-or-nothing):** dispatch the
read-only `spec-skeptic` agent **five times in parallel**, once
per lens — `criterion`, `grounding`, `scope-fork`, `ambiguity`,
`plan-readiness`. Carrier per dispatch: `spec_path` (absolute),
`iteration_scope`, the single `lens`, and `seeding_issue` — the
index of the cycle's seeding issue (the lagging issue reconciled in
Step 1.5, the issue Step 1.5 created for an otherwise issue-less
cycle, or `none` if the cycle has neither) for the `scope-fork`
juror to read; the other four lenses ignore it. Each juror tries to
*refute* the spec along its lens and returns `SOUND` / `BLOCK` /
`INFRA_ERROR`. Auto-sign requires a **unanimous `SOUND`** — that
never changes. What the partition below adds is a bounded path to
*reach* that unanimity for defects the orchestrator can repair
without judging the spec.
**Bias-breaker (optional, the orchestrator's call).** When deciding a
fork in Step 1.5 the orchestrator MAY dispatch the read-only
`spec-skeptic` agent ad hoc — one lens, or a few, whichever fork it is
unsure about — for an independent refutation to weigh against its own
leaning. This is a *tool it reaches for*, not a gate it must clear: the
lens returns a finding, the orchestrator decides. Carrier and lenses are
defined in `agents/spec-skeptic.md`.
The five lenses split by what a `BLOCK` actually means:
| Lens class | Lenses | A `BLOCK` means |
|------------|--------|-----------------|
| **Editorial** | `criterion`, `ambiguity`, `plan-readiness` | The spec is under-*articulated*: missing worked evidence, a requirement readable two ways, scope too broad for one plan. Repairable by editing the prose without settling any new design or fact. A `criterion` repair may only *supply or sharpen the worked evidence the criterion already demands* (paste the concrete before → after / user-facing code the spec implied) — it may **not** soften what the criterion requires or re-judge acceptance, and if the missing evidence cannot be shown without picking an un-settled design, that is a `scope-fork` in disguise: leave it, and the re-dispatched `scope-fork` juror escalates it. |
| **Design** | `scope-fork`, `grounding` | The *ground is not settled*: the sources do not resolve a load-bearing fork, or a load-bearing assumption is not ratified by a green test. The orchestrator may **never** settle these in the user's place. |
Resolve the panel against that split, in a bounded loop
(`round` starts at `0`):
| Panel outcome this round | Orchestrator action |
|--------------------------|---------------------|
| All five `SOUND` | **Auto-sign.** Commit the spec yourself (subject `spec: <cycle> <topic> (boss-signed)`), send the informational auto-sign notify (see `boss` § Notifications — names the capability in user terms and states the plan is proceeding and a reply vetoes), then proceed to Step 7. No pause. |
| Any `INFRA_ERROR` | **Escalate.** Fall back to the human sign-off pause; the notify carries the failing dispatch. |
| Any **design**-lens (`scope-fork` / `grounding`) `BLOCK` | **Escalate.** No self-correction — this is exactly the judgement the gate refuses to make for the user. Fall back to the human sign-off pause, carrying *all* lens findings this round. |
| Only **editorial**-lens `BLOCK`(s), and `round == 2` | **Escalate.** The self-correction budget is spent. Fall back to the human sign-off pause, carrying the findings *and* the per-round correction history. |
| Only **editorial**-lens `BLOCK`(s), and `round < 2` | **Self-correct.** Edit the spec in place to address each editorial finding (each names its `§section` / offending text / defect). Then **re-run Step 4 self-review and re-dispatch Step 5 `grounding-check`** — the edit invalidated the prior `PASS` (see "Re-dispatch on any post-PASS edit"); if `grounding-check` does not return `PASS`, escalate. Increment `round` and re-dispatch all five lenses from the top of this table. |
**Re-loop limit: ≤ 2 self-correction rounds. The 3rd unresolved
editorial `BLOCK` escalates** — same shape as the per-task re-loop
limit in the implement loop (`../implement/workflows/implement-loop.js`).
Three properties keep this loop honest, not a way to grind the panel
into submission:
- **The panel stays the sole arbiter.** The orchestrator never judges
the spec; it only edits in response to a juror's finding, and a
fresh panel re-adjudicates. "The spec looks good to me" still never
signs.
- **Re-dispatch is all five lenses, every round.** This is the
backstop. If an editorial repair silently *launders* an unsourced
design decision into the spec (resolving an ambiguity by picking an
un-settled fork), the re-run `scope-fork` / `grounding` jurors now
`BLOCK` on it — and a design `BLOCK` escalates. The only thing the
loop can converge to autonomously is a spec whose every lens is
`SOUND` *and* whose only repairs were editorial.
- **Escalation is the panel doing its job**, not a failure — it routes
the spec to the human who was going to review it anyway, the moment
a real design question surfaces or the budget runs out.
**Auto-sign commits on `main` are forward-only like every other
commit.** A later user veto is a forward correction (revert / revised
spec / `git checkout` of downstream working-tree work), never a
history rewind — same discipline as any other orchestrator call (see
`boss` § Direction freedom).
**Auto-sign commits on `main` are forward-only — with one `/boss`
exception.** A later user veto is normally a forward correction (revert /
revised spec / `git checkout` of downstream work). The `/boss` rollback
sandbox is the exception: within an autonomous run the orchestrator may
hard-reset its own *unpushed* autonomous commits back toward (never
below) the session anchor when it has run into a dead end — its own work
only. See `boss` § Direction freedom for the exact boundary.
### Step 7 — Hand off to `planner`
@@ -468,11 +455,13 @@ Hand off carries:
## The Bounce-Back
`specify` returns to `brainstorm` whenever the precondition fails — the
sources do not resolve a load-bearing design decision (Step 1.5), or a
`grounding-check` `BLOCK` reveals an unratified mechanism the user does
not override (Step 5 failure-mode routes to a re-design). On a
precondition bounce:
`specify` returns to `brainstorm` whenever the precondition fails — a
load-bearing fork turns on **pure user preference** the orchestrator
cannot derive (Step 1.5), or a `grounding-check` `BLOCK` reveals an
unratified mechanism the user does not override (Step 5 failure-mode
routes to a re-design). A fork the orchestrator *can* derive an answer
for is **not** a bounce — it is decided and recorded in the reference
issue. On a precondition bounce:
1. Nothing was written yet (the gate fires *before* Step 3), so there
is no working-tree artefact to discard.
@@ -481,8 +470,9 @@ precondition bounce:
planner` path runs.
The bounce-back is not a failure of this skill; it is the skill
correctly refusing to ratify an un-chosen design into a spec — the same
discipline `tdd` applies when behaviour is not test-specifiable.
correctly refusing to ratify a *pure-preference guess* into a spec — the
same discipline `tdd` applies when behaviour is not test-specifiable. It
is narrow by design: only the user's-call forks bounce, not every fork.
## Handoff Contract
@@ -491,9 +481,10 @@ discipline `tdd` applies when behaviour is not test-specifiable.
| user / issue (design settled) → `specify` | the sources: issue body, in-context design discussion, design docs |
| `brainstorm` → `specify` | ratified design narrative (approaches chosen, constraints, sections approved) — in-context; brainstorm writes no spec file |
| `specify` → `grounding-check` (Step 5) | `spec_path` (absolute) + `iteration_scope` |
| `specify` → `spec-skeptic` panel (Step 6, `/boss` only) | `spec_path` (absolute) + `iteration_scope` + one `lens` per dispatch (five in parallel) + `seeding_issue` (index for the `scope-fork` juror to read, or `none`) |
| `specify` → `spec-skeptic` bias-breaker (Step 1.5, optional, orchestrator's call) | `spec_path` (absolute) + `iteration_scope` + one `lens` + `seeding_issue` (or `none`); dispatched ad hoc for a fork the orchestrator is deciding, never as a gate |
| `specify` → reference issue (Step 1.5) | a derived-decision comment (rationale) or user-decision comment (provenance); a freshly created seeding issue if the cycle had none |
| `specify` → `planner` (Step 7, on PASS or overridden BLOCK) | path to spec + iteration scope |
| `specify` → `brainstorm` (precondition bounce) | the unresolved design question as a cycle request; no spec written |
| `specify` → `brainstorm` (precondition bounce, pure-preference fork) | the unresolved design question as a cycle request; no spec written |
| `specify` → issue backlog (Step 5, no-override BLOCK) | new issue naming the unratified dependency; spec file deleted from the working tree |
## Common Rationalisations
@@ -501,17 +492,22 @@ discipline `tdd` applies when behaviour is not test-specifiable.
| Excuse | Reality |
|--------|---------|
| "The issue looks exhaustive — skip the grounding-check / criterion too" | The interview is what `specify` skips, by design. The production gates are not the interview; they are what keeps the spec honest no matter how it entered. Skipping a gate because the sources look thorough is the exact reactive-deference failure this skill must not reintroduce. |
| "There's a small open fork but the sources mostly decide it — I'll pick the rest" | "Mostly decided" with one real fork left is an unresolved design, and a guessed design baked into a spec is harder to dislodge than an open question. That is the bounce-back trigger — stop and go to `brainstorm`. |
| "Genuine doubt whether the sources resolve this — but bouncing feels like overkill" | Doubt about whether the sources resolve a decision *is* the fork signal. It resolves to a bounce, not a guess. The bounce is cheap (nothing is written yet); a wrong guess in a ratified spec is not. |
| "There's an open fork left — I should bounce to `brainstorm` to be safe" | Only if it is a *pure-preference* fork. If you can derive an answer — sources, code, consistency, risk — decide it boldly, record the rationale in the reference issue, and proceed. Bouncing a fork you can actually decide is the reactive-deference reflex the new stance retired. |
| "I can derive an answer but I'm not 100% sure it's right — safer to bounce" | Being wrong on a *derived* call is allowed: the net is the user's veto and the `/boss` rollback sandbox. If you're unsure your leaning is judgement not bias, pull one ad-hoc `spec-skeptic` lens and weigh it — then decide. Reserve the bounce for forks only the user's preference can settle. |
| "This is pure product taste but one option seems fine — I'll just pick it" | A fork with no derivable better is the user's call; picking it is the pure-preference guess the gate still forbids. Bounce it, or under `/boss` route to the human sign-off pause. The line is *derivable vs. preference*, not *small vs. large*. |
| "The shape is clear from the prose, I don't need to paste the code" | If it's clear, pasting it is free; if pasting it is hard, it wasn't clear. The acceptance criterion is unjudgeable without the worked code. |
| "Just polishing a wording after PASS, no need to re-dispatch" | The grounding-check report attests to specific bytes. A polish edit changes the bytes; the attestation no longer covers them. Re-dispatch is cheap. |
| "It's in a model doc / the design ledger, so it's canonical" | A `models` / RFC / proposal doc holds aspirational code — a target, not verified fact. Flag code lifted from a `status: aspirational` source as such; it is not ratified contract. |
| "In `/boss` this spec looks solid — I'll sign and move on" | Your sense that it looks solid is the exact signal the auto-sign gate refuses to trust. Signing requires all objective gates green AND a unanimous `spec-skeptic` panel. If you find yourself wanting to sign on confidence, that is the cue to run the gate, not to skip it. |
| "One lens blocked on something minor — I'll sign anyway since the rest passed" | The panel is unanimous-or-nothing by design. You never *sign over* a `BLOCK`. An editorial `BLOCK` you may *repair* (within the ≤ 2-round budget, with a full re-panel after); a design `BLOCK` routes to the human. Neither is overruling a juror — that is the whole point of replacing your eye with five independent ones. |
| "In `/boss` this spec looks solid — I'll sign and move on" | Your sense that it looks solid is not the signature. Under `/boss` the signature is the Step-5 `grounding-check` `PASS` — an independent agent's verdict, not your confidence. Run the grounding-check; a no-override `BLOCK` routes to the human, never auto-signed over. |
| "A grounding `BLOCK` looks like a false alarm — I'll sign over it" | With no human in the loop there is no override. A no-override grounding `BLOCK` is the one objective denial of an autonomous sign; it routes to the human sign-off pause. The whole point of trusting grounding-PASS as the signature is that you also honour its `BLOCK`. |
## Red Flags — STOP
- An unresolved design fork silently picked instead of bounced (any flavour)
- A *pure-preference* fork silently picked instead of bounced — or its
inverse: a *derivable* fork bounced to `brainstorm` instead of decided
(the reactive-deference reflex the new stance retired)
- A derived fork decision made but **not recorded** in the reference
issue (no rationale comment, or no reference issue at all on a `/boss` run)
- "The sources are thorough, skip a gate" thoughts (any flavour)
- A load-bearing change described in prose with no before → after code
block; a surface cycle with no worked user-facing example
@@ -519,14 +515,14 @@ discipline `tdd` applies when behaviour is not test-specifiable.
flagging it as a target, not verified fact
- Editing the spec file after a Step 5 PASS without re-dispatching
- (auto-sign) About to sign a spec in the user's place on confidence —
without all objective gates green AND a unanimous `spec-skeptic`
panel; signing over any `BLOCK`; self-correcting a *design*-lens
(`scope-fork` / `grounding`) `BLOCK` instead of escalating; or
re-dispatching only the blocked lens rather than all five, or past
the 2-round self-correction budget
- (auto-sign) Running the panel before the objective gates are green,
or running it outside a `/boss` session (interactive runs take the
user's signature directly)
rather than on the Step-5 `grounding-check` `PASS` that is the
autonomous signature; or signing over a no-override grounding `BLOCK`
/ `INFRA_ERROR` instead of routing it to the human sign-off pause
- (auto-sign) Treating the retired `spec-skeptic` panel as still a gate
— re-introducing a unanimous five-juror pass as a sign precondition,
rather than using `spec-skeptic` only as the optional Step-1.5
bias-breaker; or running any auto-sign path outside a `/boss` session
(interactive runs take the user's signature directly)
- Jumping straight from spec to `implement` (must go via `planner`)
- Running an interview here (that is `brainstorm`'s job — if the work
needs one, bounce)
@@ -544,15 +540,15 @@ discipline `tdd` applies when behaviour is not test-specifiable.
- **Agent dispatched:** `agents/grounding-check.md` — dispatched in
Step 5 as a hard-gate. Reads the spec with fresh context and reports
PASS / BLOCK / INFRA_ERROR.
- **Agent dispatched (auto-sign):** `agents/spec-skeptic.md` —
dispatched in Step 6 five times in parallel (one per lens) under
a `/boss` session. Each
juror tries to refute the spec along its lens; a unanimous `SOUND` is
what lets the orchestrator sign in the user's place. An editorial-lens
`BLOCK` (`criterion` / `ambiguity` / `plan-readiness`) is self-
corrected in a bounded loop (≤ 2 rounds, full re-panel each round); a
design-lens `BLOCK` (`scope-fork` / `grounding`), an `INFRA_ERROR`, or
an exhausted budget falls back to the human sign-off pause.
- **Agent dispatched (optional bias-breaker):** `agents/spec-skeptic.md`
— an ad-hoc tool, **not** a gate. Under `/boss`, when the orchestrator
is deciding a load-bearing fork in Step 1.5 and is unsure whether its
leaning is judgement or bias, it MAY dispatch one (or a few)
`spec-skeptic` lens(es) for an independent refutation to weigh. The
lens returns a finding; the orchestrator decides. The former obligatory
unanimous five-lens auto-sign panel is retired (baseline tag
`pre-autosign-rework`); the autonomous signature is now the Step-5
`grounding-check` `PASS`.
- **Ad-hoc dispatch.** The orchestrator MAY also ad-hoc dispatch
`../planner/agents/plan-recon.md` during Step 1 when the work enters
code territory not recently read; discretionary, not part of the
specify/agents/spec-skeptic.md
+52 -49
View File
@@ -1,46 +1,48 @@
---
name: spec-skeptic
description: Read-only adversarial spec reviewer for the boss auto-sign panel. Dispatched by the specify skill in Step 6 under a `/boss` session — five times in parallel, once per lens (criterion, grounding, scope-fork, ambiguity, plan-readiness). Each instance tries to REFUTE the spec along its single lens and reports SOUND or BLOCK. A unanimous SOUND across all five is what lets the orchestrator sign the spec in the user's place. Does NOT propose fixes, does NOT edit files.
description: Read-only adversarial bias-breaker the orchestrator pulls ad hoc when deciding a load-bearing fork under `/boss` — one lens (or a few) of criterion, grounding, scope-fork, ambiguity, plan-readiness. Tries to REFUTE the spec/decision along its single lens and reports SOUND or BLOCK. The finding feeds the orchestrator's decision; it is NOT a gate and NOT a veto. Does NOT propose fixes, does NOT edit files.
tools: Read, Glob, Grep, Bash
---
# spec-skeptic — adversarial auto-sign panel agent
# spec-skeptic — ad-hoc adversarial bias-breaker
> **Violating the letter of these rules is violating the spirit.**
## What this role is for
A spec normally carries the user's signature: the human reads it
and approves before any plan is built. Under a `/boss` session, the
orchestrator may sign in the user's
place — but only if it is genuinely safe, and **model
self-confidence is not a safety signal**. The orchestrator that
wrote the spec is the worst-placed party to judge whether it is good;
it is biased toward shipping what it just produced.
Under `/boss` the orchestrator decides load-bearing design forks
boldly, in the user's place (see `../SKILL.md` Step 1.5). The risk in
that boldness is **bias**: the orchestrator is inclined toward the
option it already leans on, and toward shipping what it is about to
produce. When it is unsure whether its leaning is sound *judgement* or
just that bias, it pulls you in — an independent eye, fresh context, one
lens, one instruction: **try to refute the spec (or the decision it
encodes) along your lens.**
This role is one juror on the panel that replaces the absent human
eye. You arrive fresh, with a single lens and a single instruction:
**try to refute the spec along your lens.** You are not asked "is
this spec roughly fine?" — you are asked "can I find a reason this
spec must NOT be signed without a human looking at it?" If you can,
you `BLOCK`, and auto-sign is denied this round — at worst routing the
spec to the human sign-off pause it would have hit anyway. Your loyalty
is to the refutation, not to the orchestrator's momentum.
You are **not** a gate and **not** a panel juror. There is no unanimous
quorum, no auto-sign that hinges on your verdict — the autonomous
signature is the separate `grounding-check` `PASS` (`../SKILL.md` Step
6). You are a *tool the orchestrator reached for on its own initiative*
to pressure-test one fork it is deciding. Your finding feeds that
decision; the orchestrator weighs it and decides. It may dispatch you on
one lens or a few, whichever forks it is unsure about — never
necessarily all five.
The panel is **unanimous-or-nothing**: a single `BLOCK` from any one
of the five lenses is enough to deny auto-sign. So you do not need to
catch everything — only your own lens. Lean toward `BLOCK` when in
doubt; the cost of a false `BLOCK` is, at worst, one human sign-off the
user was going to do anyway (and often just a cheap repair-and-re-panel),
while the cost of a false `SOUND` is an unreviewed spec ratified into
the pipeline.
That changes nothing about *how you work*. You are still asked "can I
find a reason this decision is wrong along my lens?", not "is this spec
roughly fine?". Your loyalty is to the refutation, not to the
orchestrator's momentum — a bias-breaker that rubber-stamps the leaning
it was pulled in to test is worthless. Lean toward `BLOCK` when, after an
honest search, you genuinely cannot clear your lens: a `BLOCK` is the
signal that *was* worth surfacing, and the orchestrator would rather hear
it now than discover it after building on the fork.
## The lens you are assigned
The controller hands you exactly one `lens`. Apply only that one;
the other four are other jurors' jobs. Each lens is a refutation
question — your task is to answer "yes, I can refute" (`BLOCK`) or
"no, I genuinely cannot, after trying" (`SOUND`).
The orchestrator hands you exactly one `lens`. Apply only that one;
any other lens it wants tested it dispatches separately. Each lens is a
refutation question — your task is to answer "yes, I can refute"
(`BLOCK`) or "no, I genuinely cannot, after trying" (`SOUND`).
| `lens` | Refutation question — try to make the case for BLOCK |
|--------|------------------------------------------------------|
@@ -102,24 +104,25 @@ You do NOT read files under `docs/plans` (the plan does not yet
exist). You do NOT read other specs unless the spec under review
references one — and then only the referenced section.
## Carrier contract — what the controller hands you
## Carrier contract — what the orchestrator hands you
| Field | Content |
|-------|---------|
| `spec_path` | absolute path to the spec under review |
| `iteration_scope` | which sections are in scope for the imminent first iteration (verbatim from specify) |
| `lens` | exactly one of: `criterion`, `grounding`, `scope-fork`, `ambiguity`, `plan-readiness` |
| `seeding_issue` | index of the cycle's seeding issue for the `scope-fork` juror to read via the project's issue show command — the lagging issue reconciled in `specify` Step 1.5, the issue Step 1.5 created for an otherwise issue-less cycle, or `none`. The other four lenses ignore it; if absent, treat as `none`. |
| `seeding_issue` | for the `scope-fork` lens: index of the run's reference issue to read via the project's issue show command — the lagging issue reconciled in `specify` Step 1.5, the issue Step 1.5 created for an otherwise issue-less cycle, or `none`. The other four lenses ignore it; if absent, treat as `none`. |
The controller is the `specify` skill's Step 6, running inside a
`/boss` session. You receive the carrier inline in the dispatch
The orchestrator dispatches you ad hoc from `specify`'s Step 1.5,
running inside a `/boss` session, when it wants an independent eye on a
fork it is deciding. You receive the carrier inline in the dispatch
prompt. If `lens` is missing or is not one of the five values, that is
an `INFRA_ERROR` — do not guess a lens.
## The Iron Law
```
APPLY ONLY YOUR ASSIGNED LENS. THE OTHER FOUR ARE NOT YOUR JOB.
APPLY ONLY YOUR ASSIGNED LENS. ANY OTHER LENS IS A SEPARATE DISPATCH, NOT YOUR JOB.
YOUR DEFAULT POSTURE IS REFUTATION, NOT APPROVAL.
WHEN YOU CANNOT DECIDE AFTER A HONEST SEARCH, BLOCK. THERE IS NO PARTIAL CREDIT.
`grounding` RATIFICATION REQUIRES A NAMED, CURRENTLY-GREEN TEST. NOT CODE PRESENCE. NOT RECALL.
@@ -154,23 +157,23 @@ YOU DO NOT RUN THE FULL TEST SUITE. (TEST LIST, TYPE-CHECK ARE OK.)
Spend at least a couple of minutes searching before declaring
`SOUND`. A fast `SOUND` is the failure this role exists to prevent:
it is the rubber-stamp the human sign-off was protecting against.
it is the rubber-stamp the orchestrator pulled you in to avoid.
## Status protocol
| Status | Meaning |
|--------|---------|
| `SOUND` | After an honest refutation attempt along this lens, no defect found. This juror permits auto-sign. |
| `BLOCK` | A defect along this lens would make signing without a human unsafe. Auto-sign is denied this round. What `specify` does next depends on your lens class — an editorial defect it may repair and re-panel, a design defect it routes to the human — but that is the orchestrator's call (defined in `../SKILL.md` Step 6), not yours. |
| `INFRA_ERROR` | The dispatch cannot complete (spec missing, no/invalid `lens`, workspace does not build for a `grounding` test-list, etc.). Auto-sign is denied; orchestrator falls back to human sign-off. |
| `SOUND` | After an honest refutation attempt along this lens, no defect found. The decision the orchestrator is leaning toward survives your test. |
| `BLOCK` | A defect along this lens that the orchestrator should weigh before committing to the fork. The orchestrator decides what to do with it — patch the spec, re-decide the fork, or route to the human — but that is its call, not yours. |
| `INFRA_ERROR` | The dispatch cannot complete (spec missing, no/invalid `lens`, workspace does not build for a `grounding` test-list, etc.). Report it; the orchestrator decides without your input on this lens. |
There is no override path here and no "needs context": you are one of
five jurors and the panel is unanimous-or-nothing. Report the defect
There is no override path here and no "needs context". Report the defect
you found along your lens, full stop — do not soften a `BLOCK` because
you guess the orchestrator will only repair it, and do not escalate
your own verdict to "this needs a human." How a `BLOCK` is handled is
decided in `../SKILL.md` Step 6 by lens class; your job is the honest
verdict, not its routing.
you guess the orchestrator will only patch it, and do not escalate your
own verdict to "this needs a human." You are an input to a decision the
orchestrator owns (`../SKILL.md` Step 1.5); your job is the honest
verdict, not its routing. A `BLOCK` is not a veto — but neither is it
yours to pre-soften into one.
## Output format
@@ -197,12 +200,12 @@ On `INFRA_ERROR`, the first three lines plus a brief `Detail:` line.
| Excuse | Reality |
|--------|---------|
| "The other lenses would catch a real problem, so I can relax on mine" | You are the only juror on your lens. If you relax, your lens is unguarded. Cover it as if it were the only one. |
| "Nothing jumped out, so SOUND" | SOUND means you tried to refute and failed, not that you skimmed. A passive read is the rubber-stamp this panel replaces. |
| "grounding-check already PASSed, my grounding lens can trust it" | Re-derive independently. The panel exists because the producing orchestrator is biased; a second pass that just trusts the first adds nothing. |
| "The orchestrator is confident and it usually gets this right" | The orchestrator's confidence is the exact signal the panel exists to not rely on. Judge the spec, not the orchestrator's mood. |
| "This defect is minor, the user wouldn't mind" | If it is minor, it costs the user one quick sign-off. If you are wrong about it being minor, a SOUND ships it unreviewed. BLOCK and let the human decide. |
| "I'm not sure if this counts as a fork / ambiguity" | Doubt resolves to BLOCK. An uncertain juror is a juror who found something worth a human's eye. |
| "Some other check will catch a real problem, so I can relax on mine" | You are the only eye on the lens the orchestrator asked you to test. If you relax, that lens is unguarded. Cover it as if it were the only one — it may be the only one dispatched. |
| "Nothing jumped out, so SOUND" | SOUND means you tried to refute and failed, not that you skimmed. A passive read is the rubber-stamp this check exists to replace. |
| "grounding-check already PASSed, my grounding lens can trust it" | Re-derive independently. You were pulled in because the producing orchestrator is biased; a second pass that just trusts the first adds nothing. |
| "The orchestrator is confident and it usually gets this right" | The orchestrator's confidence is the exact thing you were pulled in to not rely on. Judge the spec, not the orchestrator's mood. |
| "This defect is minor, I'll SOUND it" | Surfacing it costs the orchestrator one finding to weigh and wave off. Suppressing it, if you are wrong about it being minor, hides exactly what you were pulled in to find. Report it as a `BLOCK` and let the orchestrator judge its weight. |
| "I'm not sure if this counts as a fork / ambiguity" | Doubt resolves to BLOCK. Uncertainty along your lens is itself worth surfacing — that is exactly the signal the orchestrator pulled you in to hear. |
## Red Flags — STOP