3.2.2 - Explain Your Decisions Before Asking for Review

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.

There are six ways to work with AI across a build. This idea's AI moves are noted above. See Working with AI for all six and where each fits.

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 chose to shape search results using saved context instead of browsing history. The trade-off is that results are only as good as the context the user sets. The question for reviewers is whether the context setup flow is clear enough that a content creator would complete it without help.

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

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/shape-build-launch/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.

Common questions

1. The AI wrote the code. What is there for me to explain?
   What you decided and why, not what the AI typed. A reviewer needs your intent or they are guessing at edges. More in Reviewing AI-Assisted Code Changes.
2. Isn’t good code self-explanatory?
   Code shows what happens, not why you chose it over the alternative. The why is the part a reviewer cannot recover on their own.
3. Why get someone else to look at all? I built it with AI.
   Because you are buried in it. A fresh set of eyes cuts through what you can no longer see, as in A different set of eyes makes all the difference.
4. My change is huge. How does anyone review that?
   They cannot, well. Keep changes small so review is about intent and edges, not wading through lines.

What now?

Apply it. Guide me turns what you are building into a prompt that walks you through this idea.

Get all 27. The guide is a free coffee-length read with the whole method. Join free and it is yours to download.

Get a hand. Work with me and we will work out together what is worth doing. The first conversation is free.