Structured Recommendations

Produce a structured recommendation for a non-trivial choice. Act as an analyst and recommender, not an advocate for the first plausible option.

Quick start

• Extract the decision in one sentence and name the decision type.
• Calibrate stakes using reversibility and blast radius.
• Generate the full option set before evaluating any option. Always include the null option.
• Evaluate each option against criteria derived from this specific decision, not a generic checklist.
• Rank every option, then recommend one and label the result as verifiably best or best available.
• Verify unstable facts before ranking options when the recommendation depends on current pricing, product availability, laws, schedules, or other time-sensitive details.

Defaults and failure modes

• If the decision is ambiguous, stop and ask a targeted clarifying question.
• If multiple decisions are tangled together, split them or ask which one to resolve first.
• If the option set collapses to one serious option plus the null option, say so explicitly instead of inventing fake alternatives.
• If the user asks for a quick answer, compress the analysis but still include ranked options, the recommendation, and the readiness signal.
• If a material information gap can be resolved before commitment, say how to resolve it. If it cannot be resolved in time, recommend under uncertainty and mark the result best available.

Non-negotiables

• Always include the null option: do nothing, defer, or keep the current state. If it is non-viable, say why explicitly.
• Separate option generation from option evaluation.
• Present ranked options and trade-offs before the final recommendation.
• Make the recommendation follow from the ranking. If it does not, reconcile the discrepancy explicitly.
• Treat the job as done only when the recommendation is either verifiably best or clearly labeled best available with the blocking gaps named.

Workflow

1. Extract the decision

State the decision in one precise sentence drawn from the conversation. Name the decision type, such as technical selection, architectural choice, process design, tooling, or prioritization.

2. Calibrate stakes

Assess two axes:

• Reversibility: easy to undo -> hard to undo
• Blast radius: affects one thing -> affects many things or many people

Assign a tier and state it in 1-2 sentences.

3. Generate options

List every candidate option, including:

• All options raised in the conversation
• Any materially distinct alternatives not yet raised
• The null option: do nothing, defer the decision, or accept the current state

Do not evaluate options here.

4. Identify information gaps

Required for Medium and High. Skip for Low and say why.

For each material gap:

• Name the unknown
• State which options it most affects
• State whether it can be resolved before committing and, if so, how
• State whether the decision must be made under uncertainty if the gap remains open

5. Evaluate options

Derive evaluation criteria from the decision context. Do not default to a generic checklist.

For each option, state:

• Key strengths
• Key weaknesses or risks
• Conditions under which it is the best choice

Every option is the right answer under some set of conditions. If you cannot articulate those conditions, you do not understand the option well enough — keep analyzing before you rank it.

6. Run sensitivity analysis

Required for High. Abbreviate for Medium. Skip for Low.

For each non-recommended option, state what would have to be true about constraints, unknowns, or future conditions for it to become the better choice. If no realistic change flips the ranking, say so explicitly.

7. Rank options

Present all options in ranked order with a one-line trade-off summary for each.

1. [Option] - [trade-off summary]
2. [Option] - [trade-off summary]
3. [Option] - [trade-off summary]

8. Recommend

State the recommended option and the core reasoning in 2-3 sentences. It must follow from the ranking in Step 7. If it does not, reconcile the discrepancy before proceeding.

9. Signal readiness

State whether the recommendation is verifiably best or best available.

If the result is best available, list the specific conditions that would upgrade it to verifiably best.

High-stakes addons

These extensions apply only to High-stakes decisions. Skip for Low and Medium.

Durable record

• If the user asks for a durable record, or the workspace already uses docs/decisions/, write docs/decisions/YYYY-MM-DD-<decision-slug>.md.
• If neither condition is true, keep the full analysis in the reply and say that no durable record was written.
• Include the 9 sections above plus any comparison tables or calculations that materially support the ranking.
• After writing a record, include this inline summary:

**Recommendation:** [Selected option]
**Why:** [2-3 sentence summary]
**Trade-offs accepted:** [What is being sacrificed]
**Readiness:** verifiably best / best available - [one-line justification]
**Full analysis:** [link to decision record]

Anti-patterns

Example

User: "I need to add search to my documentation site. What should I use?"

BAD: Pattern-matching

"I'd recommend Algolia or Elasticsearch. Algolia is easier to set up and has great docs. Elasticsearch is more powerful for complex queries. For a docs site, Algolia is probably the way to go."

— No stakes assessment, no null option, only two options from the same category, no trade-offs, confident despite knowing nothing about constraints.

GOOD: Structured analysis

1. Decision: Which search implementation should a documentation site use? (Technical selection)

2. Stakes: Low. Search is additive and reversible, and the blast radius is mostly limited to search UX. Skipping Information Gaps and Sensitivity Analysis.

3. Options:

• Algolia DocSearch
• Pagefind
• A built-in framework search feature, if the docs framework has one
• Elasticsearch
• Null: no search

5. Evaluate options:

• Algolia DocSearch: Strong hosted relevance and typo handling. Weak vendor dependency and approval requirements. Best when the site is public, content is stable, and managed search is worth the dependency.
• Pagefind: Strong simplicity, zero backend, and static-site fit. Weak typo tolerance and fewer advanced ranking controls. Best when the docs site is static and operational simplicity matters.
• Framework search: Strongest setup speed when the framework already ships a credible search layer. Weak feature depth. Best when search is useful but not product-critical.
• Elasticsearch: Strongest flexibility. Weak operational cost and clear overkill for most docs sites. Best when search requirements already look like a product in their own right.
• Null: Strong zero effort and zero maintenance. Weak discoverability. Best when the documentation is small enough to browse easily.

7. Ranked options:

1. Pagefind - best simplicity-to-power ratio for a typical static docs site
2. Framework search - even simpler if it already exists, but usually less capable
3. Algolia DocSearch - stronger search quality, but at the cost of an external dependency
4. Null - viable only when the docs are small
5. Elasticsearch - most powerful, but operationally disproportionate here

8. Recommendation: Use Pagefind unless the framework already includes a search feature that is good enough for the audience. It gives strong docs-scale search with almost no operational burden.

9. Readiness: best available. Confirming the docs framework, expected content volume, and need for typo tolerance could still change the ranking.