user-feedback

What this skill does

# User Feedback Agent

## Design Principle: Persona Context Isolation

This skill keeps persona-specific reasoning **out of the main context window** and **away from other personas**. Each persona is a separate sub-agent invocation that receives only its own profile and the artifact under review. Personas never see each other's feedback. The skill orchestrates the full cycle: select personas, spawn each independently, then aggregate results after all have responded.

Key principles:

1. **Personas are sub-agents, not roles.** Each persona gets its own Agent invocation with ONLY its profile and the artifact. No shared state between persona agents.
2. **Independence produces diversity.** If personas saw each other's feedback, they would converge toward consensus prematurely. Independent feedback catches more issues across different user perspectives.
3. **Aggregation happens after all personas respond.** The skill synthesizes consensus, conflicts, and recommendations only after collecting all independent feedback.
4. **Always include accessibility.** At least one accessibility persona must be included in every review, regardless of persona selection method.
5. **Personas stay in character.** They are users, not designers or developers. They give emotional, honest, personal feedback grounded in their profile's goals, frustrations, and tech literacy.

Unlike the architect skill (which loads multiple references into a single sub-agent for cross-cutting concerns), user-feedback spawns **multiple isolated sub-agents** that each see only their own persona definition and the artifact. The main context receives only the aggregated report.

---

## Phase 1: Persona Selection

Auto-detect relevant persona categories from project type:

| Project Type | Primary Category | Default Personas |
|---|---|---|
| GAME_DEV | Gamer | Casual Casey, Hardcore Hank, Speedrunner Sam, Completionist Cora, Social Skyler, Accessible Alex, Mobile Morgan |
| GREENFIELD, FEATURE, WEB_APP | Web/App User | Power User Pat, Average User Avery, First-Time Fiona, Non-Technical Nate, Accessible Ash |
| ENTERPRISE, B2B | Enterprise/B2B | Admin Alice, End User Eddie, Manager Maya, IT/Security Ivan |
| Any | Demographic Overlays | Gen Z Zara, Millennial Mia, Gen X Xavier, Boomer Barbara |

Read `.delivery/config.yml` for:
- `personas.selected` — list of built-in persona names to use
- `personas.custom` — custom persona definitions (see `references/custom-personas.md`)
- `personas.count` — preferred number of personas (overrides default)
- `personas.overlays` — demographic overlays to apply

### Selection Rules

- **Minimum**: 3 personas. **Recommended**: 5 personas. **Maximum**: 7 personas.
- Always include at least 1 accessibility persona: Accessible Alex (games) or Accessible Ash (web/enterprise).
- If the user specifies personas by name, use exactly those (still enforce the accessibility minimum).
- If the user describes a persona in natural language ("a casual mobile gamer who plays on the bus"), construct a custom persona from that description following the profile template in `references/custom-personas.md`.
- Demographic overlays can be combined with any category persona (e.g., "Casual Casey as Gen Z"). The overlay modifies communication style, expectations, and reference points without replacing the base persona.
- If project type is ambiguous, ask the user before proceeding.

**Declare before proceeding:**

> `Personas: [list] | Stage: [N] | Artifact: [type] | Protocol: [stage-specific from feedback-protocols.md]`

---

## Phase 2: Artifact Preparation

Determine what each persona receives based on the pipeline stage. Personas receive **only** the artifact sections relevant to their review scope, not the entire pipeline state.

| Stage | Artifact Type | What Personas Receive |
|---|---|---|
| Stage 2 (Refine) | PRD | Problem statement, user stories, acceptance criteria, personas section |
| Stage 3 (Design) | Design | User flows, wireframes, UI patterns, navigation structure |
| Stage 6 (Dev) | Feature | Feature descriptions, interaction patterns, UI descriptions, trade-offs |
| Stage 7 (UAT) | Product | Full product description, test results, known issues, release notes |

### Context Isolation Rules

- Strip internal implementation details, architecture decisions, and developer-facing content.
- Remove references to other pipeline stages or internal process artifacts.
- Present content as a user would encounter it: product-facing language, not engineering language.
- If the artifact contains visual descriptions (wireframes, mockups), include those verbatim — personas need to react to what users would see.
- For game artifacts: include genre, platform, control scheme, and any monetization model — these heavily influence persona reactions.
- For enterprise artifacts: include role-based access descriptions and workflow context — enterprise personas evaluate based on their organizational role.

### Artifact Size Guidelines

- If the artifact exceeds 2000 words, extract only the sections most relevant to user-facing experience.
- For large PRDs, prioritize: problem statement, user stories, and acceptance criteria. Omit technical implementation details.
- For design artifacts, include all user-visible flows but omit backend architecture diagrams.
- Always preserve the artifact's original language and terminology — do not paraphrase, as personas need to react to actual product copy.

---

## Phase 3: Persona Agent Invocation

Load `references/persona-invocation.md` for the full Phase 3 procedure: invocation steps, the persona-agent prompt template, and demographic overlay handling. Embed the prompt template literally in each persona sub-agent invocation.

Persona families are dispatched as paradigm sub-skills under `skills/personas/<family>/SKILL.md` (router-only, not directly model-invoked):

| Project Type Trigger | Family Sub-Skill | Personas |
|---|---|---|
| GAME_DEV | `skills/personas/gamers/SKILL.md` | Casual Casey, Hardcore Hank, Speedrunner Sam, Completionist Cora, Social Sophie, Accessible Alex, Mobile Morgan |
| GREENFIELD / FEATURE / WEB_APP | `skills/personas/web-app/SKILL.md` | Power User Pat, Average User Avery, First-Timer Fran, Non-Technical Nancy, Accessible User Ash |
| ENTERPRISE / B2B | `skills/personas/enterprise/SKILL.md` | Admin Alice, End User Eddie, Manager Maya, IT/Security Ivan |
| Any (overlay) | `skills/personas/demographic/SKILL.md` | Gen Z Zara, Millennial Mike, Gen X Grace, Boomer Bob |

**Do not run personas in sequence that can see each other's output.** Each persona sub-agent must be an independent invocation per the procedure in `references/persona-invocation.md`.

---

## Phase 4: Feedback Aggregation

After all persona sub-agents return their feedback, aggregate following the patterns in `references/aggregation-patterns.md`.

### Step 1: Theme Extraction

Categorize all feedback items into themes:
- **Usability** — navigation, clarity, learnability, workflow efficiency
- **Accessibility** — assistive technology support, color contrast, text size, motor requirements
- **Missing Features** — functionality personas expected but did not find
- **Confusion** — elements that caused misunderstanding or uncertainty
- **Performance** — speed, responsiveness, loading expectations
- **Delight** — elements that generated positive emotional response

### Step 2: Consensus Detection

Count how many personas raised the same issue:
- **4+ personas**: CRITICAL priority
- **3 personas**: HIGH priority
- **2 personas**: MEDIUM priority
- **1 persona**: LOW priority
- **Exception**: Any issue raised by an accessibility persona is MEDIUM minimum, regardless of count

### Step 3: Conflict Detection

Identify cases where personas disagree on the same element. Document both perspectives as a "design tension" rather than resolving the conflict — these represent genuine trade-offs the team must decide.

### Step 4: Weighting

Apply multipliers when calculating priority scor