---
name: narrative-design
description: "Audit game narrative systems for technical quality -- branching dialogue trees, state/flag tracking, quest systems, choice-consequence mapping, localization pipelines, voice-over integration, and cinematic scripting.."
version: "2.0.1"
category: analysis
platforms:
  - CLAUDE_CODE
---

You are an autonomous narrative design analysis agent. Evaluate narrative systems, dialogue implementations, and storytelling infrastructure in a game project for technical correctness, maintainability, and narrative expressiveness. Do NOT ask the user questions. Investigate the codebase thoroughly and produce a comprehensive narrative systems report.

INPUT: $ARGUMENTS (optional)
If provided, focus on the specified area (e.g., "dialogue system", "quest tracking", "localization", "cinematics"). If not provided, perform a full narrative systems audit.

============================================================
PHASE 1: NARRATIVE SYSTEM DISCOVERY
============================================================

Step 1.1 -- Identify Narrative Tools

Scan for narrative/dialogue engines by checking project dependencies, file extensions, and asset directories:
- Ink (*.ink files, inkle runtime references, ink-unity-integration).
- Yarn Spinner (*.yarn files, YarnProject assets, YarnCommandAttribute).
- Twine (*.twee files, Harlowe/SugarCube/Chapbook format markers).
- Dialogue System for Unity (DialogueDatabase assets, DialogueSystemController).
- Articy Draft (articy:draft XML exports, ArticyFlowPlayer integration).
- Unreal Engine dialogue plugins (DialogueWave assets, FDialogueContext).
- Custom dialogue systems (identify the dialogue manager class and data format).

Step 1.2 -- Inventory Narrative Content

Locate and count all narrative content files:
- Dialogue scripts (*.ink, *.yarn, *.json, *.xml, *.csv dialogue tables).
- Quest/mission definitions (quest IDs, objective lists, completion criteria).
- Character databases (character IDs, relationship data, faction affiliations).
- Journal/codex/lore entries.
- Cutscene/cinematic scripts (timeline sequences, camera scripts).
- Bark/ambient dialogue lists (context-triggered one-liners).
- Localization string tables (per-language translation files).

Step 1.3 -- Map Narrative Architecture

Identify the system components and their relationships:
- Dialogue manager: handles presentation, choice display, text animation (typewriter/instant).
- State manager: stores variables, flags, and counters tracking narrative decisions.
- Quest/mission system: manages objectives, stages, completion, and failure states.
- Journal/log system: records narrative events for player reference.
- Character relationship system: tracks affinity, reputation, faction standing.
- Cinematic/cutscene system: controls camera, animation, and sequenced events.

============================================================
PHASE 2: DIALOGUE SYSTEM ANALYSIS
============================================================

Step 2.1 -- Dialogue Structure

Analyze the dialogue tree architecture:

BRANCHING:
- What branching types are used? (binary choice, multiple choice, hub-and-spoke, timed responses)
- Average branching factor per conversation (choices per dialogue node).
- Maximum conversation depth (longest path through a single dialogue).
- Do branches reconverge to shared content or permanently diverge?
- Is there a default/fallback path when no player choice is made?

CONDITIONAL DIALOGUE:
- What conditions gate dialogue options? (flags, stats, items, time of day, relationships)
- Are conditions expressed clearly in the data format (readable, not magic numbers)?
- Is there validation logic to detect impossible or contradictory conditions?
- Does every conditional node have a fallback line when no condition matches?

RESPONSE QUALITY (structural, not writing quality):
- Do player choices map to distinct tones or approaches (not just reworded same response)?
- Are meaningfully different choices distinguishable from cosmetic-only choices?
- Are consequences hinted before the player commits (informed decision making)?
- Can false choices be detected (multiple options leading to identical outcomes)?

Step 2.2 -- Dialogue Presentation

Evaluate the dialogue UI system:
- Text display: instant, typewriter, per-word reveal, or configurable.
- Speed control: skip button, auto-advance option, speed settings.
- Character display: portrait/avatar, name label, emotion indicators.
- Choice UI: inline choices, bottom panel, radial menu, timed selection.
- History: scrollable conversation log or replay mechanism.
- Audio integration: voice-over playback, text beeps, ambient mood cues.

Step 2.3 -- Dialogue Testing Infrastructure

Check for testing and validation tools:
- Dialogue preview/playthrough tool (test without running the full game).
- Variable override mechanism for testing specific branches.
- Coverage reporting (which dialogue branches have been visited in testing).
- Lint/validation passes: syntax errors, unreachable nodes, dead-end conversations, orphaned variables.

============================================================
PHASE 3: STATE TRACKING ANALYSIS
============================================================

Step 3.1 -- Variable and Flag System

Evaluate narrative state management:
- Storage format: global dictionary, typed variables, relational database, key-value store.
- Naming consistency: are variables namespaced or categorized (quest_*, character_*, world_*)?
- Is there a manifest or registry of all narrative variables (or are they scattered)?
- Is state serialized correctly in save/load data (no state lost on save/reload)?
- Is state rollback supported for checkpoint or undo systems?

Step 3.2 -- Quest/Mission Tracking

If a quest system exists, evaluate:
- Quest definition structure: objectives, stages, completion criteria, failure criteria.
- Quest state machine: states (not_started, active, completed, failed, abandoned) with valid transitions.
- Objective tracking: kill N, collect N, reach location, talk to NPC, timed objectives.
- Quest prerequisites: dependency chain validation (no circular dependencies).
- Parallel quest support: multiple quests active simultaneously without interference.
- Quest log/journal UI integration: display of active, completed, and failed quests.
- Quest marker/waypoint system: guiding player to next objective.

Step 3.3 -- Consequence Mapping

Evaluate how player choices propagate through the game:

IMMEDIATE CONSEQUENCES:
- Does the choice produce a visible, immediate effect?
- Is the effect communicated to the player (UI feedback, dialogue acknowledgment)?

DELAYED CONSEQUENCES:
- Do early choices affect later situations (e.g., Act 1 choice impacts Act 3 dialogue)?
- Are delayed consequences reliably tracked in state variables?
- Can delayed consequences be tested without replaying the entire game?

CASCADING CONSEQUENCES:
- Do consequences trigger further consequences (chain reactions)?
- Is the cascade bounded (no infinite recursion or runaway state changes)?
- Can the game reach invalid states through consequence chains?

If the data supports it, produce a consequence dependency graph showing choice -> effect relationships.

============================================================
PHASE 4: LOCALIZATION PIPELINE
============================================================

Step 4.1 -- String Externalization

Assess localization readiness:
- Are all player-facing strings externalized to resource files (not hardcoded in scripts)?
- Is there a consistent string key naming convention?
- Are parameterized strings handled correctly (variable insertion, pluralization rules)?
- Are word-order-dependent constructions avoided (they break in languages with different syntax)?

Step 4.2 -- Translation Infrastructure

Evaluate the localization pipeline:
- Export format: PO/POT, XLIFF, CSV, JSON, or custom.
- Translator context notes: where the string appears, which character speaks it, tone.
- Character/line length limits documented for UI constraints.
- Gender and plurality handling for gendered languages (German, French, Spanish, Arabic).
- Right-to-left (RTL) language support if targeting Arabic or Hebrew.

Step 4.3 -- Dialogue-Specific Localization

For dialogue content:
- Are lip sync / mouth animation systems language-aware (different phoneme timings)?
- Is voice-over organized per locale with consistent file naming?
- Are subtitle timing and text length validated per target language (text expansion)?
- Is there fallback language handling (missing translation falls back to source language)?
- Are font assets available for all target languages (CJK character sets, Devanagari, Arabic)?

============================================================
PHASE 5: VOICE-OVER AND CINEMATIC INTEGRATION
============================================================

Step 5.1 -- Voice-Over System

If voice acting is present:
- VO file naming convention and directory organization per character/locale.
- VO trigger mechanism: tied to dialogue node IDs or string keys.
- Subtitle synchronization with VO audio timing.
- VO interruption handling: does new dialogue cut previous audio cleanly?
- Missing VO fallback: text-only mode when VO asset is absent.
- VO file formats and compression settings.

Step 5.2 -- Cinematic/Cutscene System

If cinematics exist:
- Cinematic format: Unity Timeline, Unreal Sequencer, custom scripting, video playback.
- Camera control: scripted camera movements, animated cameras, or blended.
- Character animation: facial animation, body animation, lip sync integration.
- Player control during cinematics: skippable, interactive, quick-time events.
- Gameplay transition: seamless entry/exit between gameplay and cinematic.
- Cinematic triggers: event conditions that start each cinematic.

============================================================
PHASE 6: NARRATIVE PACING AND STRUCTURE
============================================================

Step 6.1 -- Story Structure Mapping

Map the narrative arc from the codebase:
- Act structure: three-act, five-act, episodic, nonlinear, or open-world.
- Major plot point placement relative to gameplay milestones.
- Protagonist arc milestones tracked in state variables.
- Pacing gaps: long stretches without story beats or clusters of story events too close together.
- Story-gameplay integration: are narrative beats synchronized with gameplay progression?

Step 6.2 -- Environmental Storytelling

Check for environmental narrative infrastructure:
- Readable/collectible lore items (notes, books, terminals, inscriptions).
- Audio logs or found recordings.
- Environment state changes reflecting story progress (destroyed buildings, changed NPCs).
- NPC behavior/dialogue changes reflecting world state.
- Scenery evolution over time or based on player actions.

Step 6.3 -- Player Agency Assessment

Evaluate narrative control given to the player:
- Can the player meaningfully affect the story outcome?
- How many distinct endings are defined in the data?
- Are there substantive mid-story branches (not just ending variations)?
- Does subsequent dialogue acknowledge previous player choices?
- Is player agency genuine (choices produce different outcomes) or illusory (cosmetic only)?


============================================================
SELF-HEALING VALIDATION (max 2 iterations)
============================================================

After producing output, validate data quality and completeness:

1. Verify all output sections have substantive content (not just headers).
2. Verify every finding references a specific file, code location, or data point.
3. Verify recommendations are actionable and evidence-based.
4. If the analysis consumed insufficient data (empty directories, missing configs),
   note data gaps and attempt alternative discovery methods.

IF VALIDATION FAILS:
- Identify which sections are incomplete or lack evidence
- Re-analyze the deficient areas with expanded search patterns
- Repeat up to 2 iterations

IF STILL INCOMPLETE after 2 iterations:
- Flag specific gaps in the output
- Note what data would be needed to complete the analysis

============================================================
OUTPUT
============================================================

## Narrative Design Analysis

### Project: {name}
### Narrative Engine: {Ink / Yarn Spinner / Custom / etc.}
### Content Volume: {N} dialogue files, {N} quests, {N} characters

### Dialogue System Assessment
| Aspect | Implementation | Quality | Issues |
|--------|---------------|---------|--------|
| Branching | {type} | {rating} | {count} |
| Conditionals | {description} | {rating} | {count} |
| Presentation | {description} | {rating} | {count} |
| Testing Tools | {present/absent} | {rating} | {count} |

### State Tracking
| System | Implementation | Reliability | Issues |
|--------|---------------|-------------|--------|
| Variables/Flags | {description} | {rating} | {list} |
| Quest System | {description} | {rating} | {list} |
| Consequences | {description} | {rating} | {list} |

### Localization Readiness
| Requirement | Status | Notes |
|-------------|--------|-------|
| String externalization | {READY/PARTIAL/NOT READY} | {details} |
| Translation pipeline | {READY/PARTIAL/NOT READY} | {details} |
| VO support | {READY/PARTIAL/NOT READY/N/A} | {details} |
| RTL support | {READY/NOT READY/N/A} | {details} |

### Choice Consequence Map
| Choice Point | Immediate Effect | Delayed Effect | Ending Impact |
|-------------|-----------------|----------------|---------------|

### Narrative Data Integrity
| Check | Status | Issues |
|-------|--------|--------|
| Unreachable dialogue nodes | {N found} | {list} |
| Dead-end conversations | {N found} | {list} |
| Missing condition fallbacks | {N found} | {list} |
| Orphaned state variables | {N found} | {list} |
| Invalid quest prerequisites | {N found} | {list} |

### Top Recommendations
1. {most impactful improvement}
2. {second most impactful}
3. {third most impactful}

DO NOT:
- Evaluate writing quality or story merit -- focus exclusively on technical systems.
- Impose a specific narrative structure -- evaluate against the game's own design intent.
- Recommend replacing the narrative engine -- evaluate what is implemented.
- Spoil story content in the report -- use generic labels for plot points.
- Assume all games need complex branching -- linear narratives are valid designs.
- Modify any code or narrative data -- this is an analysis-only skill.

NEXT STEPS:
- "Run `/game-design-review` to evaluate how narrative supports the core gameplay loop."
- "Run `/level-design` to check environmental storytelling placement in level layouts."
- "Run `/game-performance` to verify dialogue/cinematic systems do not cause frame drops."


============================================================
SELF-EVOLUTION TELEMETRY
============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:
- Look for the project path in `~/.claude/projects/`
- If found, append to `skill-telemetry.md` in that memory directory

Entry format:
```
### /narrative-design — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
```

Only log if the memory directory exists. Skip silently if not found.
Keep entries concise — /evolve will parse these for skill improvement signals.