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