Best Practices

Writing good questions

Use approve for gate decisions

{ "id": "ship", "type": "approve", "text": "Ready to ship?" }

Approve questions drive the page status. Use them when you need explicit sign-off.

Use choice for decisions

{ "id": "db", "type": "choice", "text": "Which database?", "options": ["PostgreSQL", "MongoDB", "DynamoDB"] }

Choice questions force a decision. No ambiguity.

Use multi for concerns

{ "id": "risks", "type": "multi", "text": "What risks apply?", "options": ["Performance", "Security", "Cost", "Complexity"] }

Multi-select is great for checklists and risk assessment.

Use text sparingly

{ "id": "notes", "type": "text", "text": "Anything else?" }

Text questions are the least structured. Use them as a catch-all, not the primary question.

Designing for async review

• Keep pages focused — one topic per page, not a mega-document
• Front-load the decision — put the question before the explanation
• 2-4 questions max — more than that and reviewers skip them
• Use descriptive titles — "Auth Migration v2 — API Spec" not "Spec"

Working with multiple reviewers

• Encourage reviewers to enter their name
• Use approve questions for unanimous decisions
• Use choice questions for polls
• Check feedback periodically — don't wait for all reviewers

Version management

• Call update() only for meaningful changes, not typo fixes
• Each update resets status to awaiting_feedback
• Previous feedback is preserved — reviewers can see what changed