Initial commit

skills/create-plans/references/user-gates.md

@@ -0,0 +1,72 @@
+# User Gates Reference
+
+User gates prevent Claude from charging ahead at critical decision points.
+
+## Question Types
+
+### AskUserQuestion Tool
+Use for **structured choices** (2-4 options):
+- Selecting from distinct approaches
+- Domain/type selection
+- When user needs to see options to decide
+
+Examples:
+- "What type of project?" (macos-app / iphone-app / web-app / other)
+- "Research confidence is low. How to proceed?" (dig deeper / proceed anyway / pause)
+- "Multiple valid approaches exist:" (Option A / Option B / Option C)
+
+### Inline Questions
+Use for **simple confirmations**:
+- Yes/no decisions
+- "Does this look right?"
+- "Ready to proceed?"
+
+Examples:
+- "Here's the task breakdown: [list]. Does this look right?"
+- "Proceed with this approach?"
+- "I'll initialize a git repo. OK?"
+
+## Decision Gate Loop
+
+After gathering context, ALWAYS offer:
+
+```
+Ready to [action], or would you like me to ask more questions?
+
+1. Proceed - I have enough context
+2. Ask more questions - There are details to clarify
+3. Let me add context - I want to provide additional information
+```
+
+Loop continues until user selects "Proceed".
+
+## Mandatory Gate Points
+
+| Location | Gate Type | Trigger |
+|----------|-----------|---------|
+| plan-phase | Inline | Confirm task breakdown |
+| plan-phase | AskUserQuestion | Multiple valid approaches |
+| plan-phase | AskUserQuestion | Decision gate before writing |
+| research-phase | AskUserQuestion | Low confidence findings |
+| research-phase | Inline | Open questions acknowledgment |
+| execute-phase | Inline | Verification failure |
+| execute-phase | Inline | Issues review before proceeding |
+| execute-phase | AskUserQuestion | Previous phase had issues |
+| create-brief | AskUserQuestion | Decision gate before writing |
+| create-roadmap | Inline | Confirm phase breakdown |
+| create-roadmap | AskUserQuestion | Decision gate before writing |
+| handoff | Inline | Handoff acknowledgment |
+
+## Good vs Bad Gating
+
+### Good
+- Gate before writing artifacts (not after)
+- Gate when genuinely ambiguous
+- Gate when issues affect next steps
+- Quick inline for simple confirmations
+
+### Bad
+- Asking obvious choices ("Should I save the file?")
+- Multiple gates for same decision
+- AskUserQuestion for yes/no
+- Gates after the fact