skills/research-writing/references/comparison_report_framework.md

# Comparison and Decision Report Framework

## Start with the decision

Bad:
"Compare A and B."

Better:
"Which fits a 10-person team that needs X, Y, Z under budget Q?"

## Normalize the comparison

Use the same:
- date;
- version;
- plan/tier;
- geography/currency;
- workload;
- benchmark methodology;
- feature definition.

## Evidence classes

Separate:
- documented capability;
- measured independent result;
- vendor claim;
- analyst inference;
- community experience;
- unavailable/unknown.

## Criteria

Possible criteria:
- functional fit;
- quality;
- reliability;
- performance;
- security;
- integration;
- developer experience;
- operational burden;
- cost;
- lock-in;
- governance;
- support.

Use only criteria relevant to the decision.

## Tables

A comparison table should summarize evidence, not replace analysis.

Avoid:
- arbitrary numeric scores;
- pseudo-precision;
- "winner" labels with no requirement context.

## Recommendation

For non-political technical/product decisions, a recommendation may be appropriate when:
- requirements are explicit;
- evidence is current;
- trade-offs are visible.

State:
- recommendation;
- why;
- what the alternative does better;
- what would change the recommendation.

## Missing evidence

Say:
- not publicly documented;
- not independently tested;
- pricing requires quote;
- current behavior not verified.

Do not fill gaps with guesses.