Persona Auditor

---

TL;DR

The Problem

AI writes code that runs fine and is internally consistent — but the moment a real user walks the journey, it falls apart:

• Users get stuck in the first few steps, even though every function looks correct in isolation.
• You patch one point after another, for many rounds, and never find the root cause — because each fix only sees a local symptom.
• Worst of all: some bugs you'd never notice at all. Cross-project contamination, stale state, wrong sort order — they hide deep in the code and only surface when a real user walks the full path.

The Solution

Persona Auditor first reads the code to map the project's full structure (every page / command / scenario), then dispatches two layers of digital personas: mechanical walkers that exhaustively traverse every user path on paper and record only code-verifiable facts (where it broke, at which file:line, in how many steps), plus an intent observer that weighs which breaks a human would most likely care about. Finally it steps back to a god's-eye view and attributes dozens of symptoms to a few root causes, each with a falsifiable way to verify the fix.

audit → report (root cause + location) → you confirm → agent fixes → verify the symptom disappears

Why Persona Auditor?

Strength	What it means for you
🎭 Real-user perspective	Walks journeys as people would — facts recorded by mechanical walkers, human weight added by an intent observer
🗺️ Whole-project map first	Reads code to list every page / command / scenario before dispatching — no blind path-picking
👁️ Finds what you'd never notice	Hunts "self-consistent but experience-wrong" gaps, not just runtime bugs
🎯 God's-eye attribution	Counterfactual reasoning collapses dozens of symptoms into a few root causes — each falsifiable
🧮 Exhaustive, not sampled	Equivalence classes + boundary values + orthogonal arrays guarantee no missed combination, with a provable coverage count
⚖️ Facts vs opinions, separated	Walkers record only falsifiable facts; opinions are tagged as hypotheses, never findings
🎲 Deterministic & reproducible	A bounded set of personas — same input, same output, no chaotic surprises
🔄 Fix loop, not a report	Ends in precise fixing + verification, not "audit done, good luck"
🧹 Release hygiene + defensive pollution (exclusive)	Catches AI's signature diseases: secrets / PII / trial-and-error traces written into code, and guardrail notes (⚠️ warnings, "don't ship" self-reminders) leaked into public artifacts
🔍 Wheel-reinvention audit (exclusive)	Flags hand-rolled modules that a mature open-source library already beats
⚖️ Adapts to the project	Lite / Standard / Deep — a landing page doesn't get a heavyweight audit
🔌 Plugs into your loop	One-shot, incremental-after-each-change, or a gate before commit/release

---

Design Philosophy

1. Paper traversal is the means, not the end. "Not executing, not clicking" is how we exhaust every path — faster and more global than real clicking. The end goal is precise fixing — finding the few root causes so you fix once, not patch forever.
2. Exhaustiveness is the soul; sampling is negligence. One happy path proves nothing. The full persona × function × operation × state × timing matrix is traversed, with coverage quantified and provable.
3. Code is the single source of truth. Reason from the behavior recovered by reading the code, not from docs or memory.
4. Deterministic, not chaotic. Code and state machines are deterministic, so the simulation is deterministic too — a bounded set of personas, reproducible results.
5. Facts and opinions are separated. Walkers record only code-verifiable facts (broke at file:line, in N steps); the intent observer adds human-weighted hypotheses, explicitly tagged — never conflated with findings.
6. Falsifiable or it isn't a finding. Every root cause must carry a verification path ("if I fix X, symptom Y disappears"). No verification path = downgraded to "impression", never reported as a conclusion.

---

What it detects

Seven dimensions — plus tech-stack unification — dozens of checks, one table to show the coverage:

Dimension	What it detects
🧠 Logic & state	logic contradictions, dead branches, deadlock, infinite loops, state pollution, stale state, missing preconditions, variables accidentally overwritten, checks skipped, race conditions
👤 User experience	the "self-consistent but experience-wrong" gap, cognitive overload, feature fragmentation, missing feedback, "says vs does" mismatch, discoverability, recoverability, trust building, mental-model mismatch, abandonment points
🔒 Security	SQL injection, XSS, SSRF, IDOR, privilege escalation, command injection, path traversal, arbitrary file read, races, prompt injection, jailbreak (34 classes)
🤖 AI-smell & maintainability	naming emptiness, comment clichés, over-abstraction, swallowed exceptions, TODO graveyard, over-engineering, reinvented wheels, outdated tech, worse-than-mature-OSS
📋 Compliance & release	software-copyright compliance, store-review gating, missing EULA/copyright notices, secret leakage, real PII leakage, internal info / trial-and-error traces leaked, defensive-content pollution (corrections / warnings / self-reminders in public artifacts)
⚡ Concurrency & stress	multi-task concurrency, races, timeouts, interruption, duplicate submission, rapid switching, multi-subagent conflicts
🔗 Cross-scenario	cross-scenario contamination, precise switching, memory/state recall correctness, cross-module routing
🧩 Tech-stack unification	adapter-convergence failure: one concern solved by N parallel adapters / 1 live + 1 dead / write-only capability registry / ghost enum value / two names or two units for one fact / partial-use heavy borrow

Checks are triggered on demand, not dumped on you. The audit first asks "who is it for, where does it ship" and skips what doesn't apply — no store review for something not shipping, no mobile App Store review for a desktop app.

---

How it works

1. Intake — the agent infers the project type, users, and release scenario from code, then asks you only what code can't tell it (design intent, real user pain points, release decision).
2. Project map — reads the code to list every page / command / scenario and its core journeys, so nothing is left to guesswork.
3. Exhaustive traversal — equivalence classes + boundary values + orthogonal arrays cover the full path matrix without combinatorial explosion.
4. Two-layer personas — mechanical walkers record only facts (broke at file:line, in N steps, and whether it's an intended gate or an accidental break); an intent observer adds human-weighted hypotheses.
5. Six-layer checks — security, AI-smell, release hygiene, defensive-content pollution, wheel reinvention, adapter convergence (tech-stack unification), plus three-way alignment.
6. God's-eye attribution — counterfactual reasoning separates root causes from symptoms and ranks them by impact.

---

Quick Start

# skills ecosystem (Claude Code / Codex / Cursor / other agents)
npx skills add kevinshi3200/persona-auditor

# or manual: copy SKILL.md into your agent's skills directory
# e.g. ~/.agents/skills/persona-auditor/SKILL.md

Then trigger it in natural language:

"Audit this project with Persona Auditor." "审计这个项目" / "找 bug" / "推演" / "验收" / "出包前检查"

What you get: a report whose conclusion is a few root causes + impact-ranked fix directions — each with file:line and a falsifiable verification method — not dozens of symptoms laid flat.

---

How it compares

	Code review	E2E / click testing	Chaotic multi-agent	Persona Auditor
Perspective	code logic	machine operations	emergent agents	real users
Finds	code quality	runtime bugs	unpredictable	"self-consistent but experience-wrong" gaps + bugs you'd never notice
Root cause	single point	single point	unclear	god's-eye counterfactual attribution (a few root causes)
Coverage	sampled	one path at a time	chaotic	exhaustive, provable coverage
Cost	cheap, shallow	expensive	unpredictable	cheap + global + reproducible

---

Limitations

• Read-only during the audit — it never modifies code (to avoid contaminating the scene). Fixing happens in the loop, after you confirm.
• Cannot read binaries / reverse-engineer, replace real UI visual inspection, or replace real execution regression.
• Paper traversal surfaces specification-layer contradictions; if actual runtime behavior differs from what the code implies, that gap is flagged and fed back into the model.

---

FAQ

Will it drown me in findings? No. Checks are triggered on demand based on your release scenario, and the final report converges to a few root causes ranked by impact, not a wall of symptoms.

Is it deterministic, or another chaotic multi-agent simulation? Deterministic. Code and state machines are deterministic, so it uses a bounded set of personas (≤10, one per persona combo) — reproducible and predictable.

Does it change my code? Not during the audit. After you confirm the report, the same agent fixes precisely per the report and verifies the symptom disappears.

Does it do a heavy audit on a tiny project? No. It picks a depth tier — 🟢 Lite for a landing page / personal tool, 🟡 Standard for most projects, 🔴 Deep for store shipping / sensitive data / agent systems — and only runs what the project needs.

---

Author & Feedback

• Author: kevinshi3200
• Email: 915538592@qq.com
• Issues / feedback / feature requests: open an issue

License

MIT