3.2.2 - Explain Your Decisions Before Asking for Review

Explain the review context: say what was decided, what trade-off it created and what question you want reviewers to answer.

Review context

Can your decisions be understood before they are reviewed?

The call

Explain what you decided before asking someone to review it. Otherwise reviewers waste time guessing your intent and feedback drifts into opinion.

Sharpen the review context with AI

This is a Launch idea, so there are two AI moves: first Sharpen the review context using the prompt below, then Build it with AI, building carefully to carry the decision into the live system. This idea also calls for Run it for real.

New here? Let your AI do this with you. Paste your problem into Guide me and it builds a prompt that walks you through this in ChatGPT or Claude. You do not need to know how to prompt.

Prefer to drive the AI yourself? Give ChatGPT or Claude this page and ask it to help. For skill.txt, the Claude Code plugin and other ways in, see how to use vibe2value.

Or copy this prompt into AI chat, replace the bracketed lines with your real review context and keep the instruction exactly as visible here. It helps you put your launch/review-context.md together by refining your three lines until two people would make the same product decision from them.

You are checking whether this review context is clear enough before you move forward.

Constraint:
The review context must be specific enough that two people would ask reviewers for the same kind of feedback from it.

Example of the standard:
Vague: "Here is the latest version, let me know what you think."
Sharp: "We decided it suggests and never drafts. The trade-off is that you still have to write the thing. The question for reviewers is whether stopping short read as respect or as a gap."
The sharp version is specific enough that two people would ask reviewers for the same kind of feedback. The vague one is not.

Working draft:
Decision made: [what was decided]
Trade-off created: [what trade-off it created]
Question for reviewers: [what reviewers should answer]

Task:
Decide whether this review context is specific enough that two people would ask reviewers for the same kind of feedback. If it already is, say so. If it is vague, rewrite it to meet the standard in the example above.

Check:
- Would two people interpret this the same way?
- Does it stay concrete enough to guide the next step?
- Can you state what was decided, what trade-off it created and what question you want reviewers to answer?

Return:
- Verdict: clear, or needs work
- The corrected three lines, or the original three if already clear
- What was vague, and the one change that fixed it

Copy this into AI chat. Replace the bracketed parts. Keep the rest unchanged. AI will likely suggest refinements based on what you enter. Use those to sharpen your thinking, not replace it.

A reviewer who knows why you chose something catches different things from one who does not, which is the fresh-eyes move. That is Review with fresh eyes, one of the ways to make the output trustworthy.

The same idea on a recipe card

When you hand a dish to another cook to judge, you say what you were going for: "I went lighter on the chilli so the kids would eat it, but is it still interesting for the adults?" Now they know what to taste for. Just sliding the plate over with "try this" gets you a shrug and a vague "yeah, nice".

Review context is that bit of explaining before the tasting. Name the decision you made, the trade-off it created and the one thing you want the reviewer to judge. Tell them what you were aiming at and you get real judgement back, not a polite guess at what you even wanted.

The recipe card is just a simple example, using everyday cooking ideas everyone understands, to make the concept clear. See the recipe card.

What it really means

Review context is not a changelog. It is the explanation of what was decided, why, and what question the reviewer should focus on. Until you can name one decision, one trade-off it created and one question for the reviewer, the review will drift. AI can help draft context, but it cannot decide what the reviewer needs to know.

Make the review context concrete

Compare the broad version with a version you can actually test.

Too vague: Here is the latest version, let me know what you think.
Concrete enough to test: We decided it suggests and never drafts. The trade-off is that you still have to write the thing. The question for reviewers is whether stopping short read as respect or as a gap.

The second version lets two people make the same decision from it.

Both versions come from consideredContent, the one project carried through all 35 ideas. See the project.

Explaining your decisions before a review hands the reviewer the why, not just the what, so their feedback lands on the real choice you made. Drop the work on them cold and they review their guess at your intent instead.

Check the review context

Pass: You can say what was decided, what trade-off it created and what question you want reviewers to answer.
Fail: If the review request still reads as have a look and share your thoughts, the context is not defined well enough yet.

Do not ask for review until this passes.

What you'll walk away with

This post is about the framing decision: the words that pin down what this idea actually means for your build, before any code. You'll come out with your own knowledge-base/launch/review-context.md written and sharpened: the review context pinned down as a decision, three worked examples to map against your own surface and an AI prompt that pressure-tests it until two people would make the same call.

Write it down

Your review-context.md is a real file in your project. The AI forgets everything between sessions. It reads this file each time to pick up what you already decided, on this idea or another part of the build. Write it down once instead of explaining it again.

knowledge-base/framework/launch/review-context.md is just a suggested name and place for this information. The name and the location are just how we organise this type of documentation, not something you have to follow. Call the file and put it wherever suits your project. What matters is that it is written down in a format that is easily understood by both people and the AI.

The .md ending is markdown, a plain text format often used for documents kept in a code repository like GitHub. It is just the common way people store this kind of writing alongside their code.

Writing it down is how you keep good context for your AI. See Keep the signal, not the noise for why this matters across a whole build.

Risk and mitigation

Risk: Asking for review without context, which turns feedback into opinion and slows decisions.
Mitigation: Include one decision, one trade-off and one question with every review request.

Key takeaway

Do not move forward until you can say what was decided, what trade-off it created and what question you want reviewers to answer.

How to document your review context

Write your review context up in full so your AI has the whole picture: the answer, why you believe it, what you are optimising for, where you might be wrong and the standing instruction it should follow. Keep it in a file with your project like this.

# Review context

## Answer
Decision made: [what was decided]
Trade-off created: [what trade-off it created]
Question for reviewers: [what reviewers should answer]

## Evidence
Why you believe this. Conversations, examples, tickets, your own experience.

## Decision
What you are optimising for and what you are saying no to.

## Risk
Where you might be wrong and what would tell you.

## AI instruction
The standing note your AI reads on this project.

Here is one filled in so you can see what good looks like, grounded in the recipe card idea from earlier.

## Answer
Decision made: I went lighter on the chilli so the kids would eat it
Trade-off created: It might be less interesting for the adults
Question for reviewers: Is it still interesting enough for grown-up palates

## Evidence
When I have handed a plate over without saying what I chose, reviewers flagged things I had already decided on purpose.

## Decision
Optimising for a review of the real open question. Saying no to letting reviewers relitigate the chilli choice.

## Risk
Reviewers might still fixate on the heat. Tell them the choice and point them at the question I actually need answered.

## AI instruction
Before asking for a taste, explain the decision: I went lighter on the chilli for the kids, which may make it less interesting for adults. Ask reviewers only whether it is still interesting enough for grown-up palates.