Review technical decisions before they become implementation.
Give ADRs, design docs, rollout plans, operational guidance, project knowledge bases, and acceptance-gate forms a readable review surface before teams or agents depend on them.
Commentary keeps tradeoffs, consequences, source context, and follow-up comments attached through the GitHub review flow.
- ADRs
- Design docs
- Review forms
- Decision context
Technical decisions lose context in line comments.
ADRs and design docs are about tradeoffs, consequences, rollout order, and ownership. A raw patch rarely gives reviewers the shape of the decision.
Commentary keeps the proposal readable while still giving engineers source, branch, and diff context.
Decision docs get the same durable review model as PRs.
Markdown Review keeps proposals readable, Forms add ADR/design-review acceptance gates, and Knowledge Brain adds repository-memory context when work changes source notes, runbooks, or generated wiki pages.
- Decision narrativeRead the problem, alternatives, consequences, and rollout plan as a coherent document.
- Engineering contextKeep branch, repository, and diff evidence available for the parts that need exact source review.
- Acceptance gatesUse structured Forms for rollout checklists, risk signoff, ADR acceptance, and git result sync.
- Knowledge contextUse Brain navigation, backlinks, health signals, and source comparison when decisions update repository memory.
Engineering review is about the decision, not only the patch.
The diff is evidence. The accepted document is the thing future teams will depend on.
Patch-only review
- Tradeoffs are split across line comments and chat.
- Rejected alternatives are hard to scan before approval.
- Follow-up work drifts away from the accepted text.
Decision review
- Reviewers read the complete proposal in order.
- Comments land on alternatives, risks, and rollout sections.
- Accepted context stays attached for implementation handoff.
Commentary gives engineering docs a review surface.
Use rendered Markdown as the default, inspect diffs when needed, and route accepted plans toward implementation.
A decision review from proposal to merge.
Keep the ADR readable while the team resolves the engineering questions that block implementation.
- 01
Open the ADR, design doc, or rollout plan.
- 02
Review context, alternatives, and consequences.
- 03
Resolve objections on the relevant section.
- 04
Capture acceptance-gate and risk-signoff answers when rollout decisions need structure.
- 05
Merge the accepted plan and preserve follow-up.
Review the next technical decision in context.
Use Markdown Review for ADRs and design docs, or Brainstorming Reviews when the plan needs explicit consensus.