When blocked by ambiguity, choose the best reversible option, document the debt, and ship. Do not wait for perfect information. Do not build the minimal hack.
When blocked by ambiguity, do not wait for perfect information. Do not build the minimal hack. Build the best non-minimal decision — the option that:
Classify the ambiguity. Tag each open question:
reversibility: high — changing this decision later is bounded (one module, one config change, one interface swap)reversibility: low — changing this decision later has cascading effects (governance policy, data format, public API)impact: governance — affects access control, enforcement, trust boundariesimpact: implementation — affects how something is built, not what it doesimpact: cosmetic — affects presentation, naming, or UX detailsApply the routing rule:
reversibility: high → soft gate. Agent resolves it: choose the more-flexible option, build the seam, document the trigger, proceed.reversibility: low OR impact: governance → hard gate. Write a structured decision request. Pipeline blocks for the system operator.For soft gates — decide in 5 minutes of analysis, not 50:
For hard gates — write a structured decision request to tasks/decisions/{spec-name}.md:
## {section-id}: {short-description}
- status: awaiting-operator
- reversibility: low
- impact: governance
- context: {what you were doing when you hit this}
### Options
- **(a)** {option description}
- **(b)** {option description}
- **(c)** {option description}
### Recommendation
{your recommendation and reasoning, if you have one}
When an agent makes a decision under ambiguity (soft gate), document it:
## {section-id}: {short-description}
- decision: {what was chosen}
- status: auto-resolved
- reversibility: high
- rationale: {why this option, in one sentence}
- seam: {where in the code the decision is parameterized}
- refactor-trigger: {condition under which this should be revisited}
- cost-to-change: low | medium | high
"If I change my mind tomorrow, how much breaks?" If the answer is "everything," this is a hard gate — stop and ask the operator. If the answer is "this one module," make the call and ship it.