---
name: spec
description: Reach shared understanding before work starts — on anything, not only code.
license: MIT
metadata:
  version: "0.2"
  source: https://weindie.com/spec
---

# /spec

**What are we actually trying to do?**

Most disappointing AI work is not badly executed. It is well executed against a
goal nobody established. This skill spends the first minute of a task making
sure both sides understand the same thing, and then gets out of the way.

It is not a coding skill. Use it before planning something, researching a
purchase, writing a message you are not sure how to pitch, making a decision,
or thinking an idea through out loud. Code is one case, not the point.

The test is not "is this specified?" It is:

> Do we understand this well enough to move?

## Useful when

- There is more context in your head than you have actually said out loud.
- The request is short and the work it implies is large.
- Several reasonable readings of the request lead somewhere different.
- The work is expensive, public, or hard to undo.

## Probably not needed when

- The task is small, reversible and unambiguous.
- The goal was established earlier in the same conversation.
- Asking would cost more than trying it and adjusting.

Re-establishing an established goal is just delay. If the context is already
clear enough, say so and start.

## How to run the check

1. **Use what is already there.** Read the conversation, the files, the ticket.
   Never ask something that has already been answered.
2. **Sort what you have** into five piles: known, reasonably inferred,
   answerable by your own research, still ambiguous, and genuinely needs a
   decision from the human.
3. **Close the first three yourself.** Infer sensible defaults and say them out
   loud. Look up what can be looked up.
4. **Ask only about the last pile** — decisions that are actually the human's to
   make, where different answers lead to materially different work.
5. **Surface contradictions** rather than quietly picking a side.
6. **Stop when there is enough to move.** The goal is confidence to proceed, not
   a complete specification.

## Reporting

- Lead with the goal in one sentence, then what "done" would look like.
- Say the inferences out loud, so they are cheap to correct.
- Recommend. A question that comes with a suggested answer is worth three open
  ones; a skill that only interrogates is a questionnaire, not a collaborator.
- Keep the understanding shorter than the work it precedes.
- Once work is underway, raise important new ambiguity instead of guessing
  silently — but use judgement. Not every small unknown is worth an interruption.

## Defaults you can change

These are the adjustable lines of this skill. A customised copy from
<https://weindie.com/spec> replaces them and records what changed.

- **Questioning level.** Ask at most two or three questions, and only where different answers would lead to materially different work.
- **Question style.** Offer a short list of options whenever the answer can sensibly be reduced to choices, and fall back to an open question only when it cannot.
- **Small tasks.** Skip this check for small, reversible, unambiguous tasks and begin the work directly.
- **What survives.** Keep the working understanding in the conversation. When the work is done, preserve only what genuinely needs to outlive it, in whichever ticket, document or note it naturally belongs to.