audience-check

name	audience-check
description	Read the README (or any front-door doc) through the eyes of several distinct audience personas and report what each would think, miss, or bounce on
disable-model-invocation	true

Re-read the README — or whichever front-door doc the user names — as several different readers in turn, not as the author. The author knows what every line means; a first-time reader does not. The job is to surface where a specific audience gets confused, under-served, or bounces, and to propose concrete fixes.

This is an INTERNAL dev skill (not shipped to consumers). It complements the readme-brevity and docs-quality rules: those govern length/polish; this checks whether the content actually lands for who it's for.

How to run it

1. Read the target doc in full (default: README.md; honor a path the user gives). Also skim the docs it links to, so "the README promises depth the doc doesn't deliver" is checkable.
2. For each persona below, do a cold read — adopt that reader's goals, vocabulary, and patience. Ask their questions, not yours.
3. Produce the report in the format at the end. Be specific: quote the exact line, name the exact fix. Vague notes ("could be clearer") are useless.

The personas

Run all of these unless the user scopes to a subset.

1. Claude Code user (the primary audience)

Already lives in Claude Code; skimming on a laptop between tasks. Wants the WOW in the first screen and a copy-paste install in seconds.

• Does the first screen land what vigiles does and why they'd care?
• Is the install path (npx vigiles init, the agent prompt) above the fold and obviously runnable?
• Does it speak their language (hooks, skills, CLAUDE.md, subagents) without over-explaining?

2. Codex user (the second-harness audience)

Uses OpenAI Codex / AGENTS.md, not Claude Code. Skeptical that this is "a Claude thing."

• Is Codex support visible early, or buried/footnoted so they assume it's CC-only?
• Are the examples CC-only (CLAUDE.md, claude CLI) in a way that makes a Codex user feel like a second-class citizen?
• Would they know vigiles/codex exists and what works vs. what's a documented follow-on?

3. Senior / staff engineer (the skeptic)

Scans for substance and differentiation in ~20 seconds; allergic to marketing fluff. Will mentally compare to tools they know (promptfoo, ESLint, ast-grep).

• Is the differentiation concrete and credible, or hand-wavy? Does every load-bearing claim link to proof?
• Does the "deterministic, no API key / runs on your sub" cost angle come through as a real architectural fact, not a slogan?
• Anything that reads as overclaiming will cost trust — flag it.

4. Junior engineer (the newcomer)

New to agentic tooling; needs clarity, not jargon. Bounces on undefined terms.

• Which terms are used before they're defined (harness, eval, trigger-rate, subagent, dialect)?
• Is there a clear "what do I do first" path, or does it assume context they lack?

5. Engineering manager / decision-maker (adoption + ROI)

Won't run a command; deciding whether the team should adopt. Cares about cost, risk, and effort.

• Is the cost story (free deterministic tiers, evals on the existing Claude sub vs. metered per-token competitors) legible to a non-runner?
• Is adoption framed as incremental/low-risk (start permissive, tighten later)?
• What's the "why now / why us" — is it answerable from the README alone?

6. QA / test engineer (the Test pillar)

Owns test infra; evaluates the testing story specifically.

• Does the Test pillar speak to them — runHook, runHarnessTest, measureTriggerRate, significance/regression gating — or is it all about linting?
• Is the deterministic-vs-real-model split clear (what runs in CI free vs. what needs a model)?
• Would they trust it next to promptfoo/DeepEval, and is the comparison honest?

Output format

# README audience check — <file>

## <Persona> — verdict: ✅ lands / ⚠ rough / ✗ bounces
- **Reaction (cold read):** one or two sentences in this reader's voice.
- **Friction:** the specific line(s)/section(s) that confuse or under-serve them.
- **Fix:** the concrete change (move X above the fold, define Y on first use,
  link proof for claim Z, add a Codex example here).

… one block per persona …

## Cross-cutting patterns
The 2–4 issues that hurt MULTIPLE personas (these are the highest-leverage fixes).

## Ranked fixes
A short, ordered list — highest reader-impact first — each a one-line action.

Keep the report scannable and ACTIONABLE: every finding names a line and a fix. Do not rewrite the README in place unless the user asks — this skill REPORTS; applying the fixes is a separate, explicit step.