Verdict

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):

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-template.md (read it when you reach this step), then save as .md + a self-contained .html (see Output files). Cite inline with linked URLs; label vendor claims.

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 out/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 out/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 ./out/verdicts/ in the current working directory:

• out/verdicts/<slug>-<YYYY-MM-DD>.md — the brief verbatim.
• out/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 out/verdicts/ if needed. Briefs make good shared history, but they may contain internal project context — committing them is the user's call, not the skill's.

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 five 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.