Docs / Workflow

Poke holes in a draft

Before you submit a draft, you can ask REEZN to poke holes in it. It reads your definition the way a sharp reviewer would, looking for what you haven’t answered, and posts each gap it finds as a question you can work through one at a time.

It is the cheapest review in the whole workflow, because it happens before the workflow starts. A vague definition is the single biggest cause of a disappointing analysis, and the author is usually the last person to spot what is missing from their own draft. Poking holes puts a critical reader in front of it while it is still yours to fix quietly.

Poking holes is available on every plan. It uses your organization’s AI key, like any other generation, and needs one to be configured.

Running it

Open a draft feature and click Poke holes in the action row, next to Edit and Submit for analysis. It works in the background and drops its questions onto the feature as comments when it finishes.

You can run it as often as you like. Edit the draft, run it again, and REEZN re-reads the definition as it now stands, so it is a loop you can tighten rather than a one-shot verdict.

Running it again clears out the questions from the previous run that you never engaged with, so the list doesn’t pile up. Anything you resolved, or replied to in a thread, is left exactly where it is: your work is never swept away by a re-run.

What it looks for

It asks for the things a definition most often leaves unsaid, the gaps that only surface later as rework:

Edge cases the definition doesn’t account for.
Failure modes with no defined behaviour: what should happen when the thing goes wrong?
Acceptance criteria that can’t actually be verified as written.
Scope that is ambiguous, where “in” and “out” leave a grey area in between.
Actors who are referred to but never defined.

Where a service on the feature has a GitHub repo connected, the questions are grounded in your real code, so it can ask about the concepts and constraints that actually exist rather than raising generic ones.

Questions arrive as comments

Each question is posted as its own comment on the definition, carrying a “Poke holes” badge, and each is resolvable on its own. That makes the output something you work through rather than a document you read once and forget:

Answer a question by editing the draft to cover the gap, then resolve the comment.
Reply in the thread to capture the reasoning, or to argue that the question doesn’t apply.
Resolve a question outright when it isn’t relevant. Nothing forces you to act on all of them.
Filter the comments sidebar to Poke holes to see just this run’s questions.

These questions are advisory, never blocking. They don’t change the feature’s state, they don’t hold up submission, and you can submit a draft with every one of them still open. The judgement about which gaps matter stays yours.

Why this exists

The quality of an analysis is capped by the quality of the definition it was written from, and a definition is written by the one person who already knows what they meant. Poking holes gives an author the experience of being reviewed before the review, when fixing a gap costs a sentence rather than a version. Delivering the findings as individual, resolvable comments rather than a wall of prose is what makes them get acted on: each one is a small, closable piece of work, and the ones you dismiss are dismissed deliberately.