nix-decision-protocol

Purpose

• Turn a vague choice question into a clearly structured decision problem: options, criteria, trade-offs, reversibility, and confidence must all be explicit.
• Help the user make a choice, defer the choice, proceed in stages, or first reduce decision risk, rather than merely introducing the topic.

Applicable scenarios

• decision framing
• recommendation requests
• trade-off analysis
• prioritization / sequencing
• build vs buy
• Choice questions requiring explicit criteria, such as strategy, policy, and investment

Inapplicable scenarios

• The main task is writing a knowledge object, not making a choice
• The main task is implementing or debugging code
• The main task is modifying AGENTS, skills, or the instruction system

First frame the decision

Before giving advice, first clarify or reasonably infer:

• What decision needs to be made
• What the goal is
• What the constraints are
• What the time horizon is
• Whether there are key stakeholders
• What will happen by default if the decision is not made now

Organize the answer by option

When the user is choosing among multiple paths, the answer should preferably be organized around these fields:

• options
• decision criteria
• trade-offs
• reversibility
• risks / failure modes
• missing information
• recommended next step

Recommendation discipline

• Give a recommendation only when the criteria are explicit or can be reasonably inferred.
• Distinguish: observed facts, assumptions, inferences, and value judgments.
• Do not exaggerate the strength of the evidence.
• Explicitly calibrate confidence.
• When uncertainty is high, prioritize recommending reversible experiments.
• For high-impact decisions, point out "which additional piece of information is cheapest and most likely to improve decision quality."

Common output shapes

Single recommendation

At minimum include:

• The decision itself
• The recommended option
• Why it is better under the current criteria
• Key trade-offs
• confidence and uncertainty
• next step

Option comparison

At minimum include:

• options
• criteria
• Pros and cons of each option
• reversibility and "the cost of judging wrong"
• The recommended option or a staged path

Prioritization

At minimum include:

• Candidate items
• The ranking logic
• trade-off
• Items that were downgraded or deferred, and why

How to handle missing information

• Do not hide missing information.
• If a decision can still be made when several assumptions hold, state which assumptions the recommendation depends on.
• If it is not yet appropriate to settle the matter, point out what is missing and which missing fact is most likely to change the answer.

Output requirements

• The decision structure must be explicit enough for the user to audit the recommendation.
• The answer must help the user choose, defer, or de-risk; it cannot stop at merely explaining the topic.
• When you are making a value judgment, keep it separate from the factual layer.

Completion criteria

• The decision, options, and criteria are all made explicit.
• trade-offs and reversibility are clearly visible.
• The strength of the recommendation matches the strength of the evidence.
• The user gets a clear next step, even if that next step is to continue gathering information.

Anti-pattern

• Giving advice without framing the decision
• Hiding the criteria driving the recommendation
• Compressing facts and judgment into an unsupported conclusion
• Disguising it as low uncertainty
• Only listing options without helping the user act