verdict git:20260705.4b7735cA

Immutable. This exact content is served forever at /api/v1/blob/7bbc716c7abc944d.

---
name: verdict
description: >-
  Architect-grade technology decision briefs — "which option should we pick, and
  why?" Takes a decision question (X vs Y vs Z for a stated context: library,
  database, framework, platform, buy-vs-build) plus your constraints, fans out
  parallel sub-agents to research each option's project health, community
  sentiment, technical claims, and operational story, then scores options across
  weighted criteria and emits an ADR-style recommendation with a full scorecard
  and cited evidence. Keyless; the recommendation is advisory — you decide. Use
  when the user must choose between technologies or approaches — e.g.
  "/verdict postgres vs mongodb for <use case>", "should we use Kafka or NATS",
  "compare X and Y", "buy vs build", "which framework for this". Also supports
  "/verdict revisit <brief>" to cheaply re-check a past verdict's revisit-when
  triggers. For community buzz on a single topic use pulse; for exhaustive
  fact-checked research use deep-research.
---

# verdict — technology decision briefs

`/verdict <option A> vs <option B> [vs <option C>] for <context> [constraints]`
`/verdict revisit <path-to-previous-brief>` — re-check an old verdict (see Revisit mode)

Answer one question: **given this context, which option should we pick, and what
evidence supports that?** You research every option the same way, score against
explicit weighted criteria, and write the decision up so it can be defended in a
design review — or revisited later when the facts change.

This skill is deliberately **keyless** (native `WebSearch`/`WebFetch` plus free
public endpoints) and **advisory**: it recommends with evidence, the human decides.

## Step 0 — Frame the decision

Extract from the request (ask **1–2 questions only if** genuinely blocking):

- **Options** (2–4). If the user names only one ("should we use X?"), add the
  status-quo/do-nothing option and the 1–2 strongest alternatives — say you did.
- **Decision context:** what is being built, scale (users/QPS/data volume), team
  size and existing skills, current stack, timeline.
- **Constraints & dealbreakers:** licensing limits, budget, compliance,
  must-run-on-prem, language lock-in, etc.
- **Criteria weights** — defaults below; honor plain-language overrides
  ("ops burden matters most", "we optimize for hiring").

State every assumption you make in the brief header. A verdict against the wrong
context is worse than no verdict.

## Step 1 — Fan out: parallel research sub-agents (per option)

Spawn one research sub-agent **per option**, concurrently (one message, multiple
`Agent` calls, `subagent_type: "Explore"`). Each covers five angles and returns
structured findings — every claim with a `url` + 1-line evidence, anything
unverified marked as such:

1. **Project health** (for OSS/tools; skip for pure approaches): GitHub keyless
   REST — stars trend, commit/release cadence, open-vs-closed issue velocity, bus
   factor, age, backing org/funding. A beautiful README with a dead repo behind
   it is a trap; this angle catches it. **Note:** keyless GitHub REST allows
   60 req/hr shared across all sub-agents — budget calls, and on a 403
   rate-limit mark the angle **unknown** rather than retrying in a loop.
2. **Community sentiment:** HN Algolia (`hn.algolia.com/api/v1/search?query=...`)
   + web search + Reddit fallback — what practitioners report *after adopting*:
   praise, recurring pain points, migration-away stories. Weight experience
   reports over launch-day hype — and over SEO comparison content ("X vs Y in
   2026" listicle farms are marketing surface, not adoption evidence; a real
   practitioner thread outweighs ten of them).
3. **Technical claims:** official docs + independent benchmarks/comparisons for
   the capabilities the context actually needs. **Label every claim vendor-made
   vs independently verified.** Note version/date — a 2022 benchmark may be void.
4. **Operational story:** licensing (and any recent license *changes*), managed
   vs self-hosted options, pricing shape, upgrade pain, hiring pool / learning
   curve for the stated team.
5. **Security posture:** CVE history and severity pattern, GitHub security
   advisories, how fast past vulnerabilities were patched, safety of the default
   configuration, and any compliance certifications the context requires. This
   evidence feeds the *Maturity & health* and *Operational burden* scores (no
   separate criterion) — but an unpatched-critical-CVE pattern can be a
   dealbreaker in its own right.

If an angle returns nothing usable, record it as **unknown** — never fabricate.

**Lossless hand-off:** each sub-agent writes its full findings to
`verdicts/.work/<option>.md` and returns a compact summary; score in Step 2
from the files, not the summaries — the evidence that decides a verdict must
not be flattened by the relay.

## Step 2 — Score

Score each option **0–10 per criterion**, weighted. Defaults (overridable in
Step 0):

| Criterion               | Weight | What it measures                                       |
| ----------------------- | ------ | ------------------------------------------------------ |
| Fit for requirements    | 30%    | Does it actually do what this context needs, natively? |
| Maturity & health       | 20%    | Project vitality, stability, ecosystem, longevity risk |
| Team & stack fit        | 20%    | Learning curve vs existing skills; integration cost    |
| Operational burden      | 15%    | Run/upgrade/monitor cost at the stated scale           |
| Cost & licensing        | 15%    | License risk, pricing shape, lock-in                   |

If a criterion doesn't apply, mark it N/A and renormalize the rest — say so.
**Dealbreakers** (license incompatible, can't meet a hard constraint, project
effectively abandoned) disqualify the option outright regardless of score —
called out explicitly, not averaged away.

Compute a weighted total /10 per option. **Close calls (≤0.5 apart) are ties** —
say so honestly and let the tiebreaker be a context factor, not false precision.

## Step 3 — Emit the brief (ADR-style)

Render **in chat**, then save as `.md` + a self-contained `.html` (see Output
files). Cite inline with linked URLs; label vendor claims.

```markdown
# Verdict: <Option A> vs <Option B>[ vs <Option C>] — <context, one line>

**Run:** <YYYY-MM-DD> · **Status:** Proposed (advisory)
**Context & assumptions:** <what's being built, scale, team, constraints — including assumptions you made>
**Weights:** <the weights used and any overrides>

## Recommendation
**<Option>** — <2–3 sentences: the decisive factors>. <If a tie: say it's a tie and name the human tiebreaker.>

## Scorecard
| Criterion (weight) | A | B | C |
|---|---|---|---|
| Fit for requirements (30%) | x | x | x |
| ... rows per criterion, weighted total last, dealbreakers row if any |

## <Option A> — <score>/10
Strengths / weaknesses for THIS context, each with citation. Health snapshot
(commits/releases/issues). Notable practitioner reports. Vendor claims labeled.

(repeat per option)

## Consequences & risks of the recommendation
- What we accept by choosing it; migration/exit cost if we're wrong.

## Suggested spike
- The cheapest experiment (ideally ≤ 1 day) that would de-risk this decision
  before committing — what to build, what to measure, and what result would
  overturn the recommendation.

## Revisit when
- Concrete triggers that would change this verdict (e.g. "X ships native Y",
  "license changes", "we exceed N QPS").

## Sources
Every cited URL, grouped by option; vendor sources marked.
```

## Revisit mode

`/verdict revisit <path>` (or "revisit the postgres verdict") turns the
**Revisit when** section from a wish into a mechanism. Much cheaper than a full
re-run:

1. Read the previous brief (find it in `verdicts/` by slug if only a topic is
   given). Extract the recommendation, scores, dealbreakers, and the **Revisit
   when** triggers.
2. Research **only the triggers** plus two standing checks: any license change
   and any major-release/abandonment signal since the brief's run date. One
   Explore sub-agent per option, narrow scope — not the full five angles.
3. Emit a short **addendum**, not a new brief: per trigger — fired / not fired /
   unknown, with citation — and an overall call: **verdict stands / weakened
   (why) / overturned → recommend a full re-run**. Never silently flip a
   recommendation from a partial check; an overturn verdict recommends the
   re-run, the human decides.
4. Save as `verdicts/<slug>-revisit-<YYYY-MM-DD>.md` (markdown only — no HTML
   for addenda) and link the original brief in its header.

## Output files

Save to `./verdicts/` in the current working directory:

- `verdicts/<slug>-<YYYY-MM-DD>.md` — the brief verbatim.
- `verdicts/<slug>-<YYYY-MM-DD>.html` — a **bespoke, distinctively designed**
  version. Self-contained: inline `<style>`, **no JavaScript, no external
  requests** (system fonts), links preserved, the scorecard and recommendation
  as first-class visual elements, responsive, print-friendly.

`<slug>` = options joined by `-vs-`, lowercased. Compute the date with a shell
command (`date +%F`) — do not guess. Create `verdicts/` if needed and ensure
`.gitignore` covers it (briefs may contain internal project context).

Design the HTML via the **`frontend-design`** skill: subject is *an engineering
decision record*; the page's one job is to make the recommendation, scorecard,
and dealbreakers scannable in ten seconds, with the full evidence beneath.
Design changes presentation only — never scores, evidence, or citations. Fall
back to a clean self-contained no-JS layout if the skill is unavailable.

Tell the user the two saved paths at the end.

## Guardrails

- **Advisory, not authoritative.** Recommend with evidence; the human decides.
  Never present a close call as decisive.
- **Symmetric research.** Every option gets the same four angles — no
  strawmanning the option you suspect will lose.
- **Vendor claims labeled.** Marketing pages are evidence of intent, not of
  performance. Independent verification or it's marked "vendor claim."
- **No fabrication.** Every score traces to cited findings; unknowns stay
  unknown and are listed in the brief.
- **Keyless.** Never ask for API keys; degrade gracefully.
- **Context is king.** The same two options can produce opposite verdicts for
  different contexts — restate the context prominently so the brief can't be
  misapplied later.