Verdict format

A verdict is a small YAML document. It is deliberately small: an agent should be able to read the whole thing and act, and a reviewer should be able to check every claim in it in an afternoon.

slug: auth-nextjs-solo
kind: recommend
question: auth for a Next.js app, solo dev, free tier, email + Google login
context_tags: [nextjs, auth, solo, free-tier, typescript]
version_tested: "1.7.3"
answer_md: >-
  Better Auth. You own the users table in your own Postgres, the organization and
  api-key plugins cover teams and keys without a second vendor, and there is no
  per-monthly-active-user bill when you grow.
alt_md: Clerk gives you hosted sign-in UI, SSO, and an admin panel in an afternoon.
alt_wins_when: you need SSO or hosted UI this week and accept per-MAU pricing
avoid_md: >-
  NextAuth / Auth.js v4: the v5 migration has stalled since 2025 and the docs
  describe two incompatible APIs at once.
nodes:
  - role: pick
    slug: better-auth
    name: Better Auth
    type: library
    registry: npm
    package_name: better-auth
    latest_version: "1.7.3"
    license: MIT
traps:
  - node: better-auth
    version_range: ">=1.0.0"
    severity: major
    symptom: Role changes do not reach the session until the cookie cache expires.
    fix_md: >-
      Disable session.cookieCache for role-gated apps, or pass
      disableCookieCache on the routes that check roles.
sources:
  - url: https://www.better-auth.com/docs/plugins/api-key
    fetched_at: "2026-09-08"

The fields that make it a verdict rather than a summary

kind is one of recommend, compare, alternatives, design, or stack, and it decides which tool can serve the document.

question is written the way a developer would ask it, constraints included. "auth for a Next.js app" is not a question a verdict can answer; "solo dev, free tier, email and Google login" is what makes one pick correct and another wrong.

alt_wins_when is the field most comparisons skip. A recommendation with no stated condition for the alternative is an opinion. The condition is what lets an agent tell whether your situation is the exception.

version_tested and each trap's version_range are what make the answer checkable later. A nightly job reads the registries; when the pick's latest release passes the tested version by a major, the verdict is served with a RECHECK flag until a person looks again.

sources carry a fetched_at date each. A source without a read date is a citation you cannot audit.

severity is blocker, major, or minor. Blockers sort first in every response, because the trap budget in a compact block is spent from the top.

Field limits

The schema is strict about length, because a verdict that does not fit in a compact block is a verdict an agent will only half read.

slug, kind, question, answer_md, nodes and sources are required. Everything else is optional, and an omitted field means its line is absent from the served block rather than empty.

Statuses

A verdict moves through draft, review, published, recheck, retired. Only published and recheck are served, by the tools and by the website alike. retired is what happens to a verdict that loses its evidence: it stops being served rather than being quietly edited.

The spec

The schema, the validator, and the rules the schema cannot express are in the verdict spec directory. Five of those rules are enforced when a reviewer publishes: exactly one pick node, a reviewer and a date set at publish rather than by the author, an expiry at most 120 days out, every claim covered by a dated source, and a semver range on every trap. How verdicts are made describes what each one refuses.

The spec is CC0, so another corpus can adopt the format without inheriting a licence. The verdicts themselves, in WellWorn-dev/wellworn, are CC BY-SA 4.0.