Readiness review
Score how build-ready one spec is, get the gaps as questions you answer and fixes you approve, and keep the findings in a file.
A readiness review looks at one spec and tells you whether it is ready to build. Ask how
build-ready something is, paste a requirement you already have, or type /readiness-review.
Ready means a developer who was not in the conversation could build it and know when they were done. Longer is not readier: a long spec full of vague criteria is less ready than a short one with concrete ones.
What it looks for, and what it leaves alone
It hunts what the product does, for whom, under which rule, and what happens when things go wrong.
It does not raise endpoint shapes, data columns or library choices. Those belong to the team building it, and raising them here hands you homework that was never yours.
One exception: when the interface itself is the product, and people outside build against it, a missing error or an unstated limit is a real gap and the review says so.
What you get back
Two kinds of finding, kept apart, because mixing them is what makes a review unusable.
Open questions (OQ1, OQ2) only you can answer: what should happen, to whom, in what order.
Asked in plain words, so you never need to open anything to answer one.
Findings (F1, F2) the agent can close itself by rewriting an acceptance criterion. Each one
quotes the phrase at fault and gives you the concrete replacement, so you are approving a fix rather
than doing one.
Those handles are how you reply. "Here's OQ1." "Apply F2."
Where the findings land
In a file, at context/readiness-reviews/SPEC-12.md, one per spec, rewritten each time you review
that spec. You open it the same way you open any file the agent writes, from the plan's file drawer.
A verdict in the chat scrolls away. A file is something you work on together, and it is still there weeks later when someone who was not in the conversation opens it.
Review the same spec again and a handle keeps its number for the life of that spec. Anything you settled moves to a Resolved section that says what settled it and where it landed, so a handle never quietly disappears and a number is never reused.
The summary table
Five rows, every time, so two reviews of the same spec can be compared:
| Row | What it counts | Third cell |
|---|---|---|
| Behaviors with a criterion | Everything the spec promises, and whether a criterion pins it | The handles that close it |
| Criteria that could fail | Criteria two people could disagree about the outcome of | The handles that close it |
| What happens when it goes wrong | How many of empty, failure, and not-allowed the spec answers | Which of the three is missing |
| Inconsistencies | Two statements that cannot both be true, or a clash with the prototype | What agreed |
| Open questions | How many need your answer | Which carry over |
Every row has a third cell naming the handles that close it, which is what the extra-rows example
below appends to.
A count with a denominator reads "7 of 9" rather than a percentage, because the denominator is the honest part. Inconsistencies and open questions are a plain number.
The verdict is a word, never a score: Rough, Shaping or Ready, the same three the rest of the product shows.
A clean review still writes the whole file: the verdict, all five rows, "Open questions: 0", and the full walk through what was checked. A review that always finds problems is one nobody trusts, and a clean review with no evidence is one nobody can verify.
Extending it for your team
Your review may have to check something a general one cannot know about: a regulator you answer to, a legacy system every change touches, a document your client's contract requires. You can wrap this skill with your own.
A wrapper is a company or project skill that extends this one rather than replacing it. It does not repeat the pass. It names the review's hooks, so it keeps working when we reword a step.
| Hook | What it adds |
|---|---|
extra-criteria | More to look for while reading the spec |
extra-questions | Questions to always ask |
ready-bar | Raise what Ready requires |
extra-rows | Extra rows below the five |
extra-sections | Extra sections in the findings file |
Rows and sections are separate on purpose: the five rows are comparable across every team's reviews, so a wrapper appends below them and never renames or reorders them.
A worked wrapper
Write this under Settings → Skills. Copy it and change the parts in your own words.
Paste the body only. The settings form writes the header for you. Pasting a whole file that carries its own header gives you two, and the inner one quietly becomes body text.
Follow /skills/readiness-review/SKILL.md exactly. Everything below EXTENDS it.
The pass, where the findings go and the shape of that file are unchanged.
[HOOK: extra-criteria] - also look for:
- A rule taken from regulation with no source cited. Name it, cite where it
comes from, or record it as an open question.
- A change to shared billing behaviour described only as a delta ("as today,
but..."). Write what "today" is into the spec.
[HOOK: extra-questions] - when the spec touches money, always ask:
- Which of the two customer types does this apply to, and what happens to
the other one?
[HOOK: ready-bar] - Ready additionally requires that every rule taken from
regulation is cited in the spec. This RAISES the bar. It never lowers it.
[HOOK: extra-rows] - append below the five fixed rows:
| Rules cited | n of N | name the handles for the uncited ones |
[HOOK: extra-sections] - append to the findings file:
## Regulation
One line per rule the spec relies on: the rule, where it comes from, and
whether the spec states it or assumes it.What a wrapper cannot do
It adds criteria, questions, rows and sections, and it can raise the bar for Ready. It cannot lower that bar, send the findings anywhere but the file, or change that file's shape. A team's extra rigor must not cost the findings file its one readable form.
If a wrapper asks for any of those, the agent follows the built-in skill and tells you it did.