persona-score — keep fak serving its top-10 personas, and prove it

What this does. A project lives or dies on a question no internals scorecard asks: of the kinds of human (and one machine) who actually show up at fak — the free-tier dev who will download a binary and run it but not read a word, the app developer pointing an agent at it, the infra engineer who has to operate it, the security engineer auditing the floor, the researcher reproducing it — is each one served? Does the first affordance that persona reaches for actually exist in the tree? This pass turns that from a pitch into a repeatable, provable number, the way agent-readiness does it for the single persona that is the coding agent.

The shape: run the scorecard → ADD every missing affordance (HARD defect) → weigh every SOFT signal → re-measure to prove persona-debt dropped → regenerate the snapshot → commit only the scorecard lane.

The headline number is persona-debt: unmet HARD affordances + verdict overclaims

• malformed rows + coverage gaps. Drive it to zero and "fak serves its users" becomes a number you moved, not a claim you made. The shipped tree is at 0 / grade A — this pass is what keeps it there, and the number becomes a regression sentinel: the day someone deletes the release workflow or the deploy guide, a persona's affordance fill drops and persona-debt rises.

This skill is one instance of the generic scorecard doctrine. Read that for the anatomy shared by the whole family; this file is the persona-specific contract.

---

The one rule that overrides everything: add the affordance, never fake the check

The scorecard reads the real tracked tree. Every affordance is a genuine thing a persona reaches for — a file that must exist, a doc that must mention a token, a command that must resolve, a CLAIMS section that must be tagged. So:

• Retire a defect by adding the real thing the persona needs, not by adding a keyword to satisfy a substring match. A free-tier-dev gap is fixed by a real prebuilt-binary release path, not by typing "download" into the README.
• Never weaken a verdict to score. A persona is served only when its hard affordances are genuinely present; the verdict_honest KPI catches a row that claims served on a missing affordance (an overclaim) — the most important thing this scorecard catches. Never paper over a real gap by calling it served.
• It is read-only. The tool edits nothing; you add the affordance, then re-run.

If "fixing" a defect would mean gaming the detector instead of adding what the persona needs, stop — that's not a real gap.

---

The top-10 personas (the roster, declared in _meta.json)

Four tiers, ordered by how much effort the persona invests to understand fak:

Tier	Persona	The affordance they reach for first
consume	free-tier-dev	a prebuilt-binary release + install.sh + a no-key first run (won't build, won't read)
consume	app-developer	an integration index + a drop-in .mcp.json + per-harness recipes
consume	backend-integrator	the go install …@latest one-liner + a CLI/config reference + the frozen-ABI seams
operate	infra-engineer	a Dockerfile + a deployment guide + /metrics + /healthz + rate limiting
operate	security-engineer	a threat model + the closed refusal vocabulary + a tamper-evident journal + the security CI
evaluate	ml-researcher	a determinism witness + a repro packet + a citation + the research notes
evaluate	benchmark-engineer	a runnable benchmark command + the bench CI + the industry scorecard
evaluate	decision-maker	a quotable identity + the honesty ledger + a competitive comparison + a license
build	oss-contributor	CONTRIBUTING + EXTENDING + the leaf scaffold + a green gate + surfaced guardrails
build	ai-agent	AGENTS.md + llms.txt + a per-agent recipe (depth lives in agent-readiness)

The ai-agent row is intentionally thin: it delegates the deep audit to fak score agent-readiness (internal/agentreadinessscore; 16 KPIs, friction-debt). Don't duplicate that work here — keep this row the roster entry.

The affordance check kinds (the fixed doctrine): path_exists, any_path_exists, doc_mentions, fenced_command, command_resolves, claim_section. Each is a pure predicate over the real tree.

---

Step 1 — Run the scorecard (it builds your work-list)

From the repo root:

python tools/persona_readiness_scorecard.py            # human scorecard + work-list
python tools/persona_readiness_scorecard.py --chart    # at-a-glance: who's served, affordance fill
python tools/persona_readiness_scorecard.py --json      # machine payload (the loop / control pane)
python tools/persona_readiness_scorecard.py --critical  # the worst-served personas, worst-first
python tools/persona_readiness_scorecard.py --gaps      # the coverage backlog (unpositioned personas)

Capture the live blockers before summarizing any persona as served:

python tools/persona_readiness_scorecard.py --critical > /tmp/persona-critical.txt
python tools/persona_readiness_scorecard_test.py

If either command is red, report that red first and do not publish a green "all personas served" summary, regenerate snapshots, or commit. The current decision-maker pricing/TCO affordance is a separately issue-tracked product gap; record it as backlog evidence rather than silently expanding a skill-only pass to build the product surface.

It scores each persona's met/unmet HARD affordances into a readiness verdict (served / mostly-served / partially-served / unserved), folds them into a composite (0–100, A–F) and the persona-debt integer, and prints the work-list: every missing affordance with the thing to add, then the SOFT signals. Read-only.

Step 2 — Retire persona-debt worst-served-first

Take the worst-served persona first (--critical names it), but only through a dedicated issue for the product affordance. For each missing HARD affordance, add the real thing that persona reaches for (from the roster table); do not count a prose-only skill edit as retiring product debt. After a batch, re-run and watch the number fall. Capture a baseline to prove it:

python tools/persona_readiness_scorecard.py --json > /tmp/before.json   # baseline
# … add the affordances (a release path, a deploy guide, a witness) …
python tools/persona_readiness_scorecard.py --compare /tmp/before.json  # the persona-debt delta + the 2x/3x verdict

Coverage gaps (--gaps) are their own debt: a top-10 persona with no row. Close one by adding an honest row in tools/persona_readiness_scorecard.data/rows-<tier>.json — affordances grounded in real paths, the verdict matching what's actually present.

Step 3 — Weigh the SOFT signals, then stop

Read the SOFT list once (a Homebrew tap, a k8s manifest file, a citable DOI, a good-first-issue on-ramp). These lower no grade and are never persona-debt — they're the forward backlog. Fix the cheap, real ones; don't grind them to zero.

Step 4 — Re-measure, confirm, regenerate the snapshot

Re-run --critical and the focused test first. Only when both are green, state the before/after (e.g. "persona-debt 4 → 0, infra-engineer partially-served → served"). Then regenerate the committed doc folder so it matches the tree:

python tools/persona_readiness_scorecard.py --markdown-dir docs/persona-scorecard --stamp $(date +%F)

If you added or removed a scorecard surface, re-fold the portfolio and re-pin: python tools/scorecard_control_pane.py --pin (persona reports persona_debt).

Step 5 — Commit only the scorecard lane, by explicit path

This is a shared trunk; commit your lane, never a peer's work:

fak sync reconcile --apply
fak commit \
  --path tools/persona_readiness_scorecard.py \
  --path tools/persona_readiness_scorecard_test.py \
  --path tools/persona_readiness_scorecard.data \
  --path docs/persona-scorecard \
  -F <msgfile> [--push]
fak sync push

• Stage by explicit path via fak commit --path, never git add -A — stage + commit in one shell call so a peer's bare commit can't sweep your files.
• Subject: a tool/data change → feat(tools): … (fak tools); a docs-only snapshot regen → docs(scorecard): … (fak docs). End with the (fak <leaf>) trailer; lead with a verb.
• The control pane (tools/scorecard_control_pane.py), the baseline (tools/scorecard_baseline.json), INDEX.md, and the skill README are co-edited by peers adding sibling scorecards — if one shows in your diff and you didn't change it, exclude it; if a MERGE_HEAD is set, wait it out, then commit by path.

---

When to run this

• After a change to a persona's entry path: a release (free-tier-dev), an integration recipe (app-developer), the deployment guide / observability (infra-engineer), the policy spec / refusal vocabulary (security-engineer), a benchmark or the industry scorecard (benchmark-engineer), CONTRIBUTING / EXTENDING (oss-contributor).
• When adding a persona to the roster (position it in _meta.json + a rows-*.json).
• On a /loop cadence to keep every front door open as the repo grows.

The scorecard is fak's go-to-market checking layer, the way agent-readiness is its agent-experience layer and industry-score is its competitive one. Same discipline: a number you can move, and prove you moved.