goal-spec — compile a verifiable /goal brief

goal-spec — compile a verifiable /goal brief

Verifiability is the #1 determinant of whether a dispatched agent finishes. A /goal launch only goes as well as the spec + rubric you hand it. This skill turns a rough ask into a launch-ready brief so the agent can run to completion unattended — and so you stop hand-assembling context every time.

Working model: every turn that isn't a /goal should be building the brief for the next one. This skill is that build. The output is a paste-ready brief, not the work itself.

Step 1 — Pass the verifiability gate (do this first)

State the done-condition as a binary check a human or script could evaluate with no judgment call.

• Can't state it cleanly → the unit is too big or too fuzzy. Decompose until each unit has a binary done-check, then spec each unit separately.
• "Looks good / is better / handles edge cases" are not checks. "Beats the 90% holdout baseline", "exit 0 + artifact at PATH", "all N rows reconcile" are.

Step 1b — Blindspot pass (map vs territory)

The brief is a map; the agent works in the territory (real codebase, live constraints, the human's actual intent). The gap between them is unknowns — where a dispatched agent guesses. Surface all three non-obvious quadrants BEFORE emitting the brief, one move each:

• Known unknowns → turn into interview questions, one at a time, prioritizing the ones whose answer would change the architecture; write the answers INTO the brief (references over prose).
• Unknown knowns (obvious-to-the-human but unstated) → show 3–4 candidate directions to react to (grilling / a throwaway prototype) instead of asking in the abstract.
• Unknown unknowns → a dedicated blindspot list: "what would make this run wrong that neither of us has said out loud" — likely edge cases, adjacent systems, unstated invariants. More work per run ⇒ more unknowns ⇒ more places to guess wrong: a long blindspot list is a decomposition signal (back to Step 1). Also tell the dispatched agent to keep a deviations log — an unknown hit mid-build may mean the problem should be solved a different way; route it back to the plan, don't bury it.

Step 2 — Context access (give the keys, not the data)

List what the agent must reach AND the tool to reach it. Prefer live access over pasted dumps.

1. Reference material: markdown of prior experiments/decisions/numbers; the relevant docs.
2. Tools/CLIs it will drive, each with its auth source (e.g. training CLI, langsmith-cli for traces, linear/gh/bws).
3. Output location (repo / branch / dir) and any fixtures (the train + holdout sets).