Make decisions easy to review
Explain the outcome, evidence, tradeoff, and decision you need from a client or collaborator.
Your client opens tomorrow's assignments list. They should see the product decision, the evidence behind it, and what happens next — without needing to understand how you built it — so they can judge whether the experience serves their users.
Why this matters
Vague reviews produce vague direction. A concrete task plus a point of comparison turns "looks good" into a checkable judgment about whether the ordering, copy, and flow match how the team actually works.
What to understand
Ask for feedback on a decision, not a reaction: one task, what to compare, what is real versus mocked. Explain tradeoffs in user terms — what changes for their users, not the technical name. Turn critique into observation → consequence → question, and find the concern behind "make it pop" before adding color or motion. Keep async updates to visible progress, the decision or blocker, and the next evidence.
Watch for
- Opening with "What do you think?" instead of a task and a comparison.
- Letting a simulated notification become an accidental delivery promise.
- Turning a plausible benefit into a measured outcome, or an estimate into a fact.
- Dismissing a reported problem because the build matches the design.
- Silently assigning risk acceptance to someone who never agreed to it.
Strong default
State what is real, mocked, or incomplete before the walkthrough. Name an estimate as an estimate. Treat a proposed solution as input, find the concern behind it, and record the cost of the chosen option plus who actually accepted any leftover risk.
When this doesn't apply
Do not translate everything into technical names for credibility, and do not translate everything away from them either. "Server rendering" means nothing to most clients; "the first page arrives with its content" does. Keep the user consequence, drop the mechanism — unless the mechanism is the decision.
In practice
Open the request list and find an overdue item. The new version puts urgency beside the title. Please check whether the ordering matches how your team decides what to handle next.
Ask your agent: "Draft the walkthrough script: one task, what to compare, and what is mocked."
| Weak explanation | More useful explanation |
|---|---|
| "We switched to server rendering." | "The first page arrives with its content, so users can read before interactive code finishes loading." |
| "We added optimistic updates." | "The change appears immediately. If saving fails, we restore the previous value and explain what happened." |
| "The API cannot do this." | "We can show current assignments. Historical changes require data the service does not retain; we need a smaller view or additional storage." |
| "This will increase conversion." | "The next step is more prominent. We need usage evidence to know whether more people complete it." |
For a pull request, describe the trigger and before/after behavior, explain non-obvious tradeoffs, and list relevant validation.
Verify
Can the reviewer name the decision, the evidence, and what happens next? Is mocked work labeled, are estimates labeled, and did each checked validation actually happen?
Related skills
Use prototype fidelity to set expectations and release risks when the conversation shifts from preview to real use.
Last updated on