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.
It reads your code first
When a repository is connected, the review opens it before it judges the spec, because the gaps that hurt are rarely in what the spec says. They are in what it never knew it had to say. It looks for the things whoever builds this hits in their first hour: this screen already exists, so does the spec replace it or sit beside it? The code already applies a rule here and the spec says something different, so which one wins? The spec describes one way in and the product has three. There is already data written the old way. The same path also serves something else.
Each of those comes back as an ordinary question or fix, in product words ("the plan list already sorts by last opened; should the archive tab match, or show newest first?"), never as a file path or a code change, which stay the building team's business. When no repository is connected, the review says so under the table rather than implying the code agreed.
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.
They are written into the spec, in its Open Questions section, alongside any you saved
yourself: one list per spec, wherever a question came from. The review's own file cites the
handles rather than repeating the questions, so there is a single place to answer them and a single
count of what is outstanding. Answering one moves it to that spec's Decision Log, and the review's
next run reads that log to say what has been settled since.
Numbering follows the spec, not the review: a handle is spent once and means the same thing in every later review and every conversation about that spec.
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. These stay in the review file: they are the agent's work, not yours.
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.
Once the spec is in your issue tracker, the review's heading, its card in the chat and the agent's
replies all name it by its issue tracker key, such as PAY-142. The file keeps the spec's own id, so
it never moves when the spec is pushed.
A team that wraps the review can file it under one other recognized folder instead, with the same filename, the same shape and the same lineage, so a team that calls this an "análisis predesarrollo" can keep its own word for it. A folder outside that set is refused, because the review card in your chat is what would silently disappear.
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.
Answering a question or applying a finding updates that same file the moment the spec saves, whichever door the edit came through: the chat, the question control on the spec, the editor, the API or the CLI. The handle you closed moves into the Resolved section, the rows your change touched are recalculated, and the spec is re-scored, in your language, whatever model is doing the talking. In the chat a "Review updated" card names the new readiness word. The agent then recounts the one or two rows that need judgment and tells you what is still open, questions and findings counted separately, because no questions open is not the same thing as nothing left to do. It runs the review again only when you ask it to.
Two cases are left to the agent, and it says so. A review written before this shipped has no markers for the product to work from, so the first time you answer a question on one the agent updates it by hand and tells you that a new review of that spec will update on its own from then on. And a finding whose criterion changed in a way other than the rewrite the finding proposed stays open until the agent has read the edit; retiring it on a guess would tell you a finding was applied that you never approved.
The summary table
Ten rows, every time, so two reviews of the same spec can be compared. Each row carries a status you can read at a glance, a count, and the handles that close it:
| Row | What it says | Not applicable when |
|---|---|---|
| Structure | The sections your format requires are present and in shape | never |
| Coherence | Two statements that cannot both be true, or one thing called two names | never |
| Specification gaps | What is still undecided: a TBD, an unanswered empty / failure / not-allowed, a rule the code already applies that the spec neither confirms nor overrides | never |
| Criteria coverage | Everything the spec promises, and whether a criterion pins it | never |
| Criteria testability | Criteria two people could disagree about the outcome of | never |
| Flows and states | The journey walked end to end, with its empty and error branches | The spec has no screen |
| Data model | What the spec says it stores, in its own words: things, fields, relations, rules. Never columns, types or keys, which stay the building team's | It stores nothing |
| API contract | The endpoints promised, with their requests, responses and errors | The API is not the product |
| Open questions | How many need your answer, and which carry over | never |
| Prototype consistency | Behavior the prototype shows that the spec does not state | There is no prototype |
The status is the part you read first, and it says who unblocks the row:
| Status | Means | Who unblocks it |
|---|---|---|
| 🟢 Pass | Nothing to do here | Nobody |
| 🟡 Approve | The review already wrote the fix; it is an Fn waiting on your word | You, in a click |
| 🔴 Answer | The row carries an open question, or the spec is missing that dimension entirely | You, in words |
| ⚪ n/a | The row does not apply to this spec, with the reason written in the cell, never a blank | Nobody |
A check that could not RUN is not white. If there is no repository to read, or a dimension nobody assessed, the row is red and says "not assessed", because "we did not check" is not evidence of readiness. White means the spec itself makes the row inapplicable: it has no screen, it stores nothing, its interface is not the product.
Each cell carries the mark and its word, so the table still reads when the colour does not: on a colourblind screen, in a plain-text paste, or through a screen reader.
The verdict follows from the table rather than from judgement: Ready when every row is green or white, Rough when Structure, Coherence or Criteria coverage is red, and Shaping for everything in between. The split is about what fixes it. A red on the first rows means the spec has to be rewritten; a red anywhere else is a question you can answer. Criteria coverage is the row that can never be waved through: a spec with a behavior nobody pinned is not ready, whatever else is green.
Every row also has a Handles 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. Rows that count occurrences, like coherence, gaps and open questions, are a plain number where zero is the good one.
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 ten 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 ten |
extra-sections | Extra sections in the findings file |
Rows and sections are separate on purpose: the ten rows are comparable across every team's reviews, so a wrapper appends below them and never renames or reorders them. A team row carries the same four cells, and its status counts in the verdict the same way: it can hold a spec back, never wave one through.
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.
Set Extends to Readiness review on the form, then paste this as the body. 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 ten fixed rows, same four cells:
| Rules cited | 🟡 Approve | 3 of 4 | F4 cites the uncited one |
[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 can also file the findings under one other recognized folder. It cannot lower that bar, invent a folder of its own, 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.