---
name: gamification-design
effort: medium
version: 1.0.0
description: Use when designing or analyzing points systems, reward loops, progression mechanics, engagement features, or loyalty programs. Triggers include "points system," "rewards design," "progression," "engagement loop," "battle pass," "loyalty mechanics," "gamification," or "retention hooks." For B2C customer-facing features in this codebase, this skill invokes the hyper-gamification-designer agent.
---

# Gamification Design

Analyze and optimize gamification elements for maximum engagement and retention.

## Project Context

**Reads from `baldart.config.yml`:** `paths.design_system`, `paths.ui_guidelines`, `identity.audience_segments`, `identity.design_philosophy`, `stack.animation.canonical`.
**Gated by features:** `features.has_design_system` (when `true`, design-system reads below are BLOCKING; when `false`, fall back to `paths.ui_guidelines` alone), `identity.audience_segments` non-empty (gamification surfaces target a specific segment — usually `customer` — which the user must confirm before any recommendation).
**Overlay:** loads `.baldart/overlays/gamification-design.md` if present — project-specific reward economy facts (point name, tier ladder, lottery format), motion vocabulary, brand voice register for customer surfaces.
**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.


## When to Use

Invoke this skill when working on:
- Points systems (earning, spending, expiring)
- Reward mechanics (coupons, discounts, prizes)
- Progression systems (tiers, levels, badges)
- Engagement loops (streaks, daily rewards, challenges)
- Loyalty mechanics (membership, VIP status)
- Social features (referrals, leaderboards, sharing)
- Retention mechanics (notifications, reminders)

## MANDATORY Design System Reads (BLOCKING before any visual recommendation)

Gamification features are typically customer-facing — their visual expression MUST conform to the project design-system SSOT (when one exists). The reads below are BLOCKING when `features.has_design_system: true`. Skipping any of them in that case is a protocol violation.

1. **MANDATORY / BLOCKING** — `${paths.design_system}/INDEX.md`. Component index and Canonical Authority Matrix. Entry point.
2. **MANDATORY / BLOCKING** — `${paths.design_system}/areas/<customer-segment>.md` (segment name comes from `identity.audience_segments` — typically `customer`). Surface guidance for badges, progress bars, reward cards, lottery tickets, etc.
3. **MANDATORY / BLOCKING** — the project's motion patterns doc (typically `${paths.design_system}/patterns/animations.md`; exact path listed in `.baldart/overlays/gamification-design.md`). Approved motion patterns (confetti, level-ups, wheel spin, progress pulses) must be specified against this registry.
4. **MANDATORY** — `${paths.design_system}/tokens-reference.md`. Colors, spacing, radii, shadows. Never invent new palettes that bypass this token contract.
5. **MANDATORY** — `${paths.ui_guidelines}` (brand voice + interaction-state sections). The project's brand voice pillars are listed in `.baldart/overlays/gamification-design.md` if it overrides the defaults.

If `stack.animation.canonical` is set, motion recommendations target those libraries.

Do NOT invent new color palettes, shadow recipes, or token names for gamification elements. Re-use the existing semantic tokens and component primitives defined in the design-system SSOT.

## Agent Delegation

This skill delegates to the `hyper-gamification-designer` agent for comprehensive analysis.

**To invoke the agent**, use the Task tool:
```
Task tool:
- subagent_type: hyper-gamification-designer
- prompt: [Feature description with details below]
```

## Required Context for Analysis

Provide the agent with:

1. **Feature Name**: What you're building/analyzing
2. **Target Behavior**: What users should do repeatedly
3. **Core Action**: The repeatable action (e.g., "scan receipt", "visit store")
4. **Reward Structure**: How users are rewarded
5. **Progression**: How users advance/progress
6. **Economy**: Points, tokens, currencies involved
7. **Social Elements**: Referrals, leaderboards, sharing (if any)
8. **Current KPI Concerns**: Drop-off points, churn, conversion issues

## Agent Output

The `hyper-gamification-designer` agent provides:

### A) TL;DR Verdict
- What works
- What is broken/weak
- Single highest-leverage change

### B) Gamification Scorecard (0-10)
| Dimension | Score | Notes |
|-----------|-------|-------|
| Core loop clarity | | |
| Reward design | | |
| Progression pacing | | |
| Meaningful goals | | |
| Social stickiness | | |
| Economy balance | | |
| Retention hooks | | |
| Agency & choice | | |
| Fairness | | |
| Ethical safety | | |

### C) MDA Map
- Mechanics: Concrete rules/systems
- Dynamics: Emerging behaviors
- Aesthetics: Player feelings

### D) Failure Modes
- Exploit vectors
- Churn triggers
- Pay-to-win risks

### E) Prioritized Improvements
| # | Change | Rationale | Complexity | KPI Impact |
|---|--------|-----------|------------|------------|

### F) Validation Plan
- Events to track
- Funnels/cohorts
- A/B test design

### G) Ethical Check
- Dark patterns detected
- Risk level
- Safer alternatives

## Quick Self-Check

Before invoking the agent, verify you have:
- [ ] Clear description of the feature
- [ ] Target user behavior defined
- [ ] Reward/progression structure outlined
- [ ] Any current metrics or concerns noted

## Related Skills

- `prd-planning`: For full PRD with gamification section
- `copywriting`: For reward/achievement messaging
- `ui-ux-pro-max`: For gamification UI patterns

## Project Integration

In this codebase, the `prd` agent automatically invokes `hyper-gamification-designer` for B2C features touching gamification areas. This skill provides direct access for standalone analysis.
