Personas

# Personas

These are the seven people we build Amble for. Every spec, every component, every empty state, every error message should pass through their eyes before it ships.

## Why personas live here

Personas are not test fixtures. They are **product truth** — the canonical answer to "who is this for?"

If you cannot name the persona who needs your feature, you are building for nobody. If your feature serves "everyone," it usually serves no one well. These pages exist next to the architecture and data model docs because they are equally foundational.

## How to use these

### Before you write a spec

Read the relevant persona's `Background` and `Mindset` sections. Imagine them reading your spec. Would they understand what you are building? Would they care?

Then run `/persona-review spec <path>` to get a structured critique with acceptance criteria.

### Before you ship UI

Run `/persona-review browser <persona-id>` to have the `persona-simulator` agent log in as the persona and attempt their JTBD against the live app. The agent will report friction with screenshots and a UX scorecard.

### When you're stuck

If you cannot decide between two design options, ask: "what would Casey think?" or "would Alex actually use this?" The persona's perspective often resolves the ambiguity.

## Persona schema

Every persona file uses the same YAML frontmatter:

```yaml
---
id: "kebab-case-id"
name: "FirstName the Role Title"
tenant_slug: "default"
role: "system_admin | tenant_admin | editor | member | viewer | guest"
email_env: "E2E_PERSONA_EMAIL"
credentials_env: "E2E_PERSONA_PASSWORD"
jtbd:
  - "Specific actionable job they're trying to accomplish"
success_criteria:
  - "Measurable pass/fail gate from their perspective"
heuristics:
  - "Relevant Nielsen heuristic to focus on"
---
```

Plus two narrative sections:

- **Background** — who they are, what they do daily, the context they bring
- **Mindset & Behavior** — first-person traits: what frustrates them, what they value, how they judge quality

## Adding a new persona

Run `/persona-review define`. The skill walks you through:

1. Who is this person?
2. What are their top jobs?
3. What would make them angry?
4. What would make them quit?

Then it generates the persona file and adds it to the sidebar.

Do not add a persona just because a stakeholder asks. Personas earn their place by representing a distinct user segment with distinct jobs and distinct failure modes.

## The seven personas

| Persona | Role | Why they matter |
|---------|------|-----------------|
| [Casey the Evaluator](/docs/personas/first-time-admin) | system_admin | First impression — the 5-minute embarrassment test |
| [Jordan the PE Analyst](/docs/personas/pe-analyst) | editor | Data density and speed — the Excel-replacement test |
| [Sam the Consulting Manager](/docs/personas/consulting-manager) | tenant_admin | Configuration — the admin-UX-must-be-as-good test |
| [Alex the Sales Ops Manager](/docs/personas/sales-ops) | tenant_admin | Power-user efficiency — the click-count test |
| [Riley the Content Manager](/docs/personas/marketing-content) | editor | Domain vocabulary — the no-jargon test |
| [Morgan the Executive](/docs/personas/stakeholder-viewer) | viewer | Read-only consumption — the polished-report test |
| [Taylor the Guest Viewer](/docs/personas/guest-viewer) | guest | External access — the no-onboarding test |

## Related

- [Quality System](https://github.com/tylerdr/amble/blob/main/documents/QUALITY-SYSTEM.md) — how personas fit into the broader quality loop
- `.claude/rules/ux-review.md` — the 6-test UX heuristic framework personas evaluate against
- `.claude/agents/persona-simulator.md` — the agent that brings personas to life in the browser
- `.claude/skills/persona-review/SKILL.md` — the skill for spec critique and browser testing