Make small decisions explicit

The idea

Agents encounter dozens of small forks: introduce a dependency, reuse an abstraction, ask for clarification, or keep moving. A lightweight decision model makes the criteria visible so the same discussion does not start from scratch every time.

For this draft, “decision model” means explicit options, constraints, and a short rule for choosing between them. The jev example will help refine that definition.

When it helps

Use this for recurring, bounded choices where the team already has preferences. A few clear criteria are especially helpful when a choice is reversible and prolonged discussion costs more than trying it.

Put it into practice

Record the question, the non-negotiable constraints, the available options, and the deciding factor. Ask the agent to leave a short rationale with the change. Keep the model small enough to actually use.

Decision: add a package or use the platform?

Constraints:
- Must work in the deployment runtime.
- Must meet the actual feature requirements.

Rule:
1. Prefer the platform if it meets the requirements simply.
2. Otherwise, compare a maintained package with a local solution.
3. Escalate if the choice changes a public API or data format.

Record: choice, decisive reason, and what would change our mind.

Where it breaks down

A scoring table can make subjective guesses look precise. A hard constraint should not lose to a weighted average. If evidence is missing, investigate it rather than inventing a score.

Revisit the model when its assumptions change. High-impact decisions still need appropriate review, even if a rule suggests an answer.

Connect the patterns

Link a frequently used decision model from the relevant AGENTS.md. Keep the full rationale nearby, and load it when the decision actually arises.