/verdict

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.

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 `out/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 the brief **in chat** per `references/adr