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.

Why it matters

Explaining decisions before asking for review means reviewers can evaluate the trade-off instead of guessing the intent. AI can summarise changes quickly, but human judgement decides whether the explanation makes the decision reviewable. The difference is between useful review and noise that slows everyone down.

Explainer

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.

The code that brings these decisions to life lives in the build-in-public repos (subCancel, ghostMarketingFlow and flowRun), which are works in progress growing alongside the writing. We work through the code together each week in the free weekly workshops; that is where these ideas get put into practice with hands on the keyboard.

If you sign up, this idea continues with how it all fits together, a worked example, how to use it with AI, how to evaluate it on a real change, the risks worth naming and how to mitigate them, the key takeaways and a copy-paste AI prompt you can drop straight into your next chat. Examples are shown on the Cloudflare Workers stack with AI-assisted coding tools; the ideas apply equally on any other platform.