Plumbline skill

Plumbline — Spec Elicitation

Purpose: kill shoot-in-the-dark iteration. The costliest pattern in AI-assisted design work is back-and-forth where the model guesses at an unstated frame until the user's felt sense of agreement ends the loop. This skill replaces that with structured interrogation that produces a spec artifact — and no verifier or design loop can exist without one, because success criteria live here. A plumbline is a fixed reference for true: this skill establishes the one everything downstream is checked against.

Laws

1. No solutioning during elicitation. Alternatives, designs, and builds come after the spec is signed — or inside a tournament the spec authorizes. If a promising design idea surfaces mid-elicitation, park it in the spec's open-questions section; don't chase it.
2. Every success criterion names its verifier. A criterion without a check is a vibe. Acceptable verifiers: a query, an eval case, a measurable number with a threshold, an observable behavior — or an explicit "user verdict," which is allowed but must be labeled subjective so nobody mistakes it for an automatable gate. Grammar enforces this: behavioral criteria take the shape WHEN <trigger> [/ WHILE <state> / IF <unwanted event>], THEN the system SHALL <observable response>, and vague adjectives ("fast", "easy", "reliable") are contraband until they surrender a SCALE (the unit of measure) and a METER (how it's measured). An outcome criterion must also be attributable: you can tell movement caused by this change apart from movement caused by other things. If the metric would plausibly move for reasons unrelated to the work, it fails as a criterion — tighten it or pair it with a control. If no fit criterion can be written at all, the requirement is not yet understood: it goes back to elicitation, not into the spec.
3. Decompose before drilling. If the subject is multi-step or complex, propose a chunk breakdown and get it corrected before detailed questioning. Never interrogate a monolith — per-chunk elicitation is how complexity stays tractable and how partial specs stay usable.
4. Questions must earn their turn. First, resolve anything you could find yourself — read the files, configs, existing patterns, prior context — and never spend a turn on a fact you can look up; ask only about the decisions the user alone can make. Then select the survivors by impact × uncertainty (how much the answer would change the spec × how little it can be guessed) and by decision-relevance (would the answer change a decision the spec must make? if not, it is noise). The sharpest questions eliminate whole branches of work. Before each round, sweep the ambiguity taxonomy for uncovered categories — functional scope, data/state, flows, non-functionals, integrations, edge cases, constraints, terminology, done-signals — so high-impact gaps aren't crowded out by easy questions. Batch up to 4 per round (a structured multiple-choice prompt when the tooling supports it; numbered prose otherwise), each with a recommended answer where one exists. Multiple rounds are expected and normal — convergence is the stop condition, not round count.
5. Hunches enter as hypotheses. The user's assumptions get captured in the assumptions ledger as hypotheses, not silently hardened into requirements. The same rule applies to your own inferences.

Procedure

• Round 0 — Right instrument, frame, strawman. First, check the instrument fits. A signed spec assumes the problem is knowable enough to pin down before acting. For a clear or merely complicated subject, that holds — proceed. For a genuinely complex or novel one, where the shape of the answer cannot be known in advance, a spec-first move manufactures false confidence: say so, and recommend probing — small experiments that generate the understanding a spec would need — before committing to one. Naming this at the start is far cheaper than discovering it at sign-off.

  Then frame in two parts, not one:

  • The environmental frame — the current state: what exists, what's already been decided, what related work or prior art bears on this, and the desired end state the work aims at.
  • The problem frame — the gap between current and desired, mapped as a system of related problems rather than a single issue in isolation. Problems that constrain each other are noted as such.

  Restate the thing in one sentence: what it is, what problem it solves, what it touches or displaces. If the one-sentence restatement fails, that failure is the first question. When a frame feels stuck, restate the problem deliberately — paraphrase it, state its opposite, broaden it, or redirect to an adjacent framing — and see which restatement the user recognizes.

  Then draft a one-screen strawman spec before asking anything else, with every guess tagged inline as [NC: question] — never silently filled. Where a known default or prior art exists, carry it in the marker: [NC: question — default X], mirroring Law 4's recommended answers. People correct a concrete artifact better than they answer abstract questions, and markers make the unknowns enumerable. The strawman references prior-art documents — the context section is pointers, not payload. For complex subjects the strawman includes the proposed chunk breakdown. All subsequent questioning targets markers first.

  Advisory mode: when the subject is a decision or strategy question rather than a system build, the artifact is a question brief, not a spec — the decision to be made, the facts bearing on it (each classified binding / assumption-to-test / set-aside-as-hypothetical as it surfaces), constraints, what a good answer would settle, the assumptions ledger, open questions. Same laws, same markers, usually fewer rounds.

• Round 1 — Decomposition (complex subjects only). Propose the chunk breakdown: each chunk gets a goal, inputs, outputs, and dependencies. The user corrects or approves the cut before any drilling starts.

• Rounds 2..n — Clarification passes. Per chunk: constraints, success criteria, failure modes, out-of-scope. Open each round with the delta in understanding since the last round — never a full re-dump. Vary the lens: pick moves from the table below by symptom instead of re-running one default voice. Keep a running glossary of contested terms: when a term is pinned, record its canonical definition; when a later statement conflicts with a pinned term, stop and resolve the conflict before continuing — don't let a definition drift mid-spec. Expect special passes: some chunks need a dedicated round; some answers reopen the decomposition. That's the process working, not failing.

• Convergence check. Converged when no [NC] markers remain and no askable spec-changing question is left — either observed (a round returns no spec-changing answers) or declared (you state none remain; a null round is sufficient, not necessary, so Law 4 is never violated to prove convergence). Markers never survive into a signed spec: an unresolvable one is converted to an open question or a ledgered assumption by the user's explicit choice, not by default.

• Checklist gate. Before presenting the draft, run it through "unit tests for the prose" — items that interrogate the sentences, not the future system: every criterion has a verifier and a threshold or observable (no adjective without SCALE/METER); at least one outcome criterion measures the intended effect, not just task completion (building the thing right is not the same as building the right thing); at least one must-not criterion, or an explicit note that none exists; no [NC] markers; the belongs-to-humans check — does any part of this belong to a human conversation, relationship, or judgment call before a machine touches it? The test is inform vs. replace: output that serves a later human conversation proceeds; output that would model or substitute for that conversation gets flagged in the artifact. Every requirement's rationale traces to a goal or constraint; out-of-scope records what was cut, not just what was never considered; the ledger separates hypothesis from established fact. Fix or demote failures before presenting.

• Red-team the draft. Review the draft adversarially before the user sees it — internal contradictions, unverifiable criteria, missing failure modes, scope creep, unstated assumptions. Run a pre-mortem: assume the spec shipped and failed, and write the history backward. Sweep three failure classes explicitly — it didn't work; it worked but nobody used it or nothing changed; and it worked and something else should have been done instead. Then a risk pass on the failure modes: identify the hazards, rate each by severity × likelihood, and name a control for the ones that clear the bar — including at least one high-impact / low-probability tail risk that's easy to ignore precisely because it's rare. A control only counts if you can name the plausible-but-wrong outcome it would catch; if the control would also pass the bad outcome you're worried about, it isn't a real control — strengthen it or record the risk as unmitigated. Accepting a residual risk is a human decision, not yours to make silently. Fold repairable findings in; surface any framing-level finding immediately — a broken frame ends the drafting, not just the pass.

• Restate-back before sign-off. Compress the spec to its spine — goal and intent, the key tasks, the must-nots — restate it back in your own words, and ask the user to correct it. Restating in fresh words surfaces silent divergence that a yes-or-no on the full draft hides.

• Sign-off. The user signs or amends. A spec is not a spec until signed, and a signature is an explicit affirmative — silence, a topic change, or "looks interesting" is not one. A material amendment after signing re-opens sign-off; each re-sign gets its own changelog entry.

Elicitation moves

Named moves for Rounds 2..n, chosen by symptom:

Symptom	Move
Requirement feels like the wrong altitude	Ladder: up — "why does that matter?"; down — "give me a concrete example"; sideways — "what else would achieve that?"
Agreement feels abstract	Scenario walkthrough: narrate one named, concrete episode end to end; the user supplies each next step, input, and decision. Then vary: different actor, missing data, interrupted flow.
Spec is all happy path	Negative scenario / misuse: "what must NOT happen?" "who or what would want this to fail, and how?" Yields must-not criteria for §5.
A requirement can't say why it exists	Five-whys rationale: chain to a goal or constraint; a chain ending in "someone said so" flags the requirement for challenge or deletion.
Everything is priority 1	MoSCoW: force Must / Should / Could / Won't bins — the Must test is "what happens if we ship without it?"; Won't-haves are written into §6, so cut scope is a decision, not a discovered omission.
Priority hides a nonlinear payoff	Kano lens: sort each item as must-be (absence enrages, presence unnoticed), performance (more is linearly better), or delighter (absence unnoticed, presence surprises). Some "low-priority" items are delighters; some "nice-to-haves" are actually must-bes.

Spec template

A living document revised in place, with a dated changelog at the bottom. Sections:

1. Intent & end state — the purpose in one sentence, the end-state conditions that mean it is done, and the few key tasks that must hold regardless of which solution is chosen. This is the part that survives when the specifics stop fitting.
2. Situation & problem frame — what exists now, what's already decided, prior art and what this displaces (pointers, not payload), and the gap between current and desired state mapped as a system of related problems.
3. Decomposition — chunks with goals / inputs / outputs / dependencies (omit for simple subjects).
4. Constraints — hard limits: platform, budget, rules already in force; both what must be done and what must not.
5. Success criteria — numbered (SC-1…), each with its named verifier per Law 2, so downstream loops and tasks can cite which criterion they satisfy.
6. Out of scope — explicit, to keep future loops from wandering; records what was cut, not only what was never considered.
7. Assumptions ledger — each row marked hypothesis or established fact, placed by importance × evidence, and carrying a calibrated confidence. A row earns its place only if it is both likely true and load-bearing (planning can't continue without it); anything neither gets struck. For an estimated number, anchor on the base rate of similar past cases before adjusting. A load-bearing, low-confidence row is routed to open questions with a plan to confirm or deny it — high-consequence, low-evidence assumptions are what the convergence and red-team passes attack first. This section also carries the running glossary of contested terms and their pinned definitions.
8. Open questions — including parked design ideas from Law 1 and load-bearing assumptions awaiting confirmation.
9. Decision points — pre-planned responses bound to observable conditions. Each names the condition (an observable trigger), the pre-committed response, and the downstream effect on the plan. A tripwire that trips silently, with no one having decided in advance what it means, is how plans fail late.
10. Ownership & change control — the named owner, who decides a contested criterion, the escalation path, and how an amendment is signaled so downstream work knows the spec moved.
11. Sign-off & changelog — signed date, then dated amendments. The conversation is the elicitation log; the changelog records each round's spec-delta in one line and never duplicates question-by-question history into the artifact.

Question briefs (advisory mode) follow the same discipline in lighter form.