| name | decision-making |
| description | Make and document consequential engineering or product choices under incomplete information. Use when multiple reasonable approaches materially differ, constraints conflict, a dependency or architecture choice is needed, or the agent must decide whether to ask or proceed. |
Decision Making
Purpose
Reach a defensible decision quickly enough to preserve momentum while exposing assumptions, costs, and reversibility.
Inputs
- The decision to make and the deadline or urgency.
- Hard constraints, authorization boundaries, and success criteria.
- Repository evidence and comparable existing patterns.
- Options that are genuinely viable, including doing nothing.
Process
- Write the decision as a question with a concrete outcome.
- Separate hard constraints from preferences and guesses.
- Inspect existing decisions, code patterns, measurements, and standards before generating options.
- Keep two or three materially distinct options; remove dominated or out-of-scope choices.
- Compare correctness, compatibility, maintenance cost, reversibility, performance evidence, and delivery cost.
- Prefer the smallest reversible choice that satisfies the outcome unless evidence justifies a larger commitment.
- Ask the user only if the remaining difference is personal, irreversible, or outside current authority.
- Record material decisions with context, choice, rationale, consequences, and revisit signal.
Constraints
- Do not manufacture options merely to appear balanced.
- Do not use a numeric score when weights are subjective or unsupported.
- Do not let sunk cost decide an architecture choice.
- Do not treat popularity as proof of local fit.
- Do not hide a personal preference inside an objective-quality argument.
Verification
- The chosen option satisfies every hard constraint.
- Rejected options and their decisive tradeoffs are understandable.
- Assumptions are testable or explicitly accepted.
- The decision has a rollback or revisit condition when uncertainty is material.
- The decision did not require authority that was never granted.
Failure Modes
- Analysis paralysis over a reversible choice.
- Premature commitment before reading the repository.
- A dependency chosen because it is familiar rather than necessary.
- A vague "best practice" rationale with no project evidence.
- Asking the user a question that inspection or experimentation could answer.
Examples
Dependency: choose the proven parser when hand-written parsing would own a complex grammar; record bundle/maintenance cost.
Architecture: follow the existing module boundary for a narrow feature; create an ADR only if the public contract or ownership changes.
Sources
See ../../sources/decision-making.sources.md.
