think — work an idea backwards into a buildable spec

The skill is named `think`; the product/CLI it drives is `devague`. (The forward leg — turning a converged spec into a plan — is the sibling `/spec-to-plan` skill, which drives devague plan.)

think turns a vague feature idea into a buildable spec by working backwards: you start from the announcement you'd make if it had already shipped, then build an Announcement Frame by capturing claims, pressure -testing them, parking what's still genuinely unknown, and only exporting once the frame converges.

The CLI is deterministic and move-driven — it is not a wizard. There is no fixed sequence of prompts. You (the agent) choose the next move; the CLI just tracks state and tells you what's still missing. Run devague learn for the canonical ten-stage arc and devague explain <move> for any single move.

This skill is the operator: a portable wrapper that resolves the CLI and forwards every move verbatim — including status, the read-only verb that reads the convergence gate and tells you the recommended next move.

How to run

The entry point is scripts/think.sh. Invoke it from the repository you are speccing (frames persist under .devague/ in the current directory):

bash .claude/skills/think/scripts/think.sh <move> [args...]
bash .claude/skills/think/scripts/think.sh status

It resolves the CLI portably — an installed devague on PATH (the normal case), falling back to uv run devague when you are inside the devague checkout. If neither resolves it prints an install hint (uv tool install devague). Every move — including status — is forwarded verbatim, so you can equally call the CLI directly (devague <move> …) when it is installed; the wrapper exists only for portable resolution.

Moves

Claim kinds: announcement, audience, after_state, before_state, why_it_matters, boundary, success_signal, open_question, non_goal, requirement, assumption, decision. Vagueness kinds: unknown_nonblocking, unknown_blocking, out_of_scope, follow_up.

These are exactly the kinds the shipped CLI enforces (CLAIM_KINDS / VAGUENESS_KINDS in devague/frame.py) — the skill documents the surface as built, so every command here passes the CLI's choices= validation. requirement is spec-affecting (needs a confirmed honesty condition); non_goal / decision are descriptive; an unconfirmed assumption is a convergence warning, not a blocker. The formal entity model, the (state × origin) vocabulary, and the per-move input/output/transition/error contract are documented in docs/spec-contract.md (issue #5); for the authoritative live shape of any move, run it with --json (or devague learn --json / devague explain <move>).

status — the next-move verb

status is a first-class, read-only CLI verb (devague status, internalised from this wrapper in 0.11.0 — issue #30). It composes list + converge and prints where the current frame stands, the remaining gaps, and the recommended next move; it never mutates state (the drafting↔converged transition stays in converge). It reports ready_for_spec, lists the blockers and warnings, and shows required_next_moves[0] as the recommended move. Pass --json for the same fields as a structured payload ({frame, total, ready_for_spec, blockers, warnings, parked_items, required_next_moves}).

frame: my-feature    (1 frame total)
convergence: NOT passed — 2 gap(s):
  - missing a 'boundary' / non-goal claim
  - claim c2 has no confirmed honesty condition

recommended next move (first gap):
  devague capture --kind boundary "<text>"

Run it whenever you're unsure what to do next.

Hard rules (do not violate)

These are the point of the method — convergence must mean something.

• LLM proposals stay proposed. A claim captured with --origin llm, and any

honesty condition you (the agent) propose, lands as proposed. Never `confirm` your own proposal. Confirmation is a user-only decision — surface the proposal and let the user confirm or reject it. Proposed content must not silently become an authoritative requirement.

• Honesty conditions route through the user. Propose them freely with

interrogate --honesty; the user owns whether they hold.

• Converge, don't vibe. export is gated on converge passing. Never claim

the frame is ready on a hunch — run converge (or status) and resolve every listed gap. The gate requires confirmed announcement / audience / after_state, a before_state or why_it_matters, a boundary, a success_signal, a confirmed honesty condition on every spec-affecting claim, and no unresolved blocking vagueness or hard question.

• Park real unknowns; don't paper over them. If something is genuinely

unknown, park it (blocking or non-blocking) rather than fabricating an answer. Blocking vagueness holds back convergence — by design.

Output contract

Results go to stdout, diagnostics and errors to stderr — a strict split you can rely on when parsing. Pass --json to any move for a structured payload on the same stream. Exit code 0 on success, non-zero on user error (with a hint: line). Frames live under .devague/ in the current directory.

Worked example

A short end-to-end session (the kind you'd run to spec a feature like devague#5):

d() { bash .claude/skills/think/scripts/think.sh "$@"; }

d new "Devague ships a documented spec contract"
d capture --kind audience "devague + the assisting LLM"
d capture --kind after_state "a vague idea becomes a buildable, pressure-tested spec"
d capture --kind why_it_matters "specs converge on evidence, not vibes"
d capture --kind boundary "not a full PRD generator; no fixed wizard"
d capture --kind success_signal "a frame exports only after the gate passes"

# Pressure-test a claim, then let the USER confirm the condition:
d interrogate c1 --honesty "the contract round-trips: save -> load -> identical frame"
# ...user reviews and runs: d confirm h1

# Park a genuine unknown instead of guessing:
d park "exact JSON schema versioning policy" --kind unknown_nonblocking

d status        # what's left + the next move
d converge      # gate; resolve any listed gaps
d export        # writes docs/specs/<slug>.md once converged

The exported spec-md is a buildable artifact.

After export — commit, then hand off

Once export writes the spec and the user has reviewed it, close the idea→spec leg cleanly before moving on:

1. Commit the spec. Commit the exported docs/specs/<slug>.md (along with

the .devague/<slug>.json frame state and any review artifact under docs/reviews/) so the converged frame is durable in history, not just on disk. Use a focused message, e.g. git commit -m "spec: <slug> (devague /think)". The frame and the spec are the evidence trail for every confirmed claim — keep them together. (Per the repo's standing convention this normally becomes a branch + PR via the cicd skill; commit-only is fine when the user asks for it.)

1. Hand off to `/spec-to-plan`. The forward leg is the sibling skill:

devague plan new --frame <slug> seeds a plan from the converged frame and works it forward into a buildable plan (it can equally feed superpowers:writing-plans or a normal implementation PR).

Don't pause for a "what next?" menu after a reviewed export — the standing flow is commit, then `/spec-to-plan`.

Provenance

This is a first-party skill — its origin is agentculture/devague, where the devague agent maintains it alongside the tool it operates (dogfooding). It is the inverse of the other skills under .claude/skills/, which devague vendors from steward. When this skill is ready, steward pulls it from devague and broadcasts it to the rest of the AgentCulture mesh. The cite, don't import policy still holds: downstream repos copy it, they don't symlink or depend on it. See docs/skill-sources.md.