# Plumbline Skill

> Plumbline — Spec Elicitation

- Skill: `mightykevster/plumbline-skill` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add mightykevster/plumbline-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mightykevster/plumbline-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mightykevster (https://skillmd.com/u/mightykevster)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mightykevster/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.