---
name: adventure-puzzle-analyzer
description: Analyzes point-and-click adventure game walkthroughs to identify, categorize, and document puzzle mechanics. Use when analyzing new game walkthroughs or updating the puzzle design handbook.
---

# Adventure Puzzle Analyzer Skill

## Quick Start

```
1. Read walkthrough, list all puzzle solutions
2. For each: what info + how conveyed + what action solved it?
3. Match to existing types in /puzzles/ OR create new type
4. Document and update README.md table of contents
```

## Instructions

### Step 1: Extract Puzzle Solutions

For each walkthrough section, note:
- What player needed to discover
- How information was conveyed (dialogue, environment, text, trial-and-error)
- Action(s) that solved it
- Whether info came from one or multiple sources

### Step 2: Classify Against Existing Types

**Read /README.md** for full list of existing types. Quick reference:

| Type | Key Indicator |
|------|---------------|
| Pattern Learning / Knowledge Transfer | Learn system in Domain A, apply same rules in Domain B |
| Multi-Faceted Plan | Multiple INDEPENDENT requirements gathered from different sources |
| Meta-Puzzle Construction | Sequential chain where STEP N'S OUTPUT = Step N+1's INPUT |
| Memo Chain | Scattered written fragments that synthesize into solution |
| Metaphor-to-Literal | Idiomatic/poetic language decoded into literal game objects |
| Information Brokerage | NPC exchange network: who wants what from whom |
| Sensory Exploitation | NPC has perceptual weakness/sense; exploit directly |
| Distraction Physics | Manipulate ENVIRONMENT to break NPC blocking pattern |
| Observation Replay | Watch sequence once under blocked conditions, reproduce exactly later |
| Timed Consequence | Story urgency without mechanical timer/deadline |

**If none fit**: Read existing type definitions in `/puzzles/` to confirm no match. Consider new type if at least 2 distinct puzzles share same information architecture.

### Step 3: Document

**Adding example to existing type:**
1. Open relevant file in `puzzles/`
2. Add under "## Game Examples" section using standard format (see Template below)
3. Optionally add to "## Related Types" or "## Common Misidentifications" if it clarifies boundaries

**Creating new type:**
1. Create new markdown file in `puzzles/` with kebab-case name
2. Use template below for structure
3. Update `/README.md` table of contents (add row, increment number)
4. Cross-reference from most similar existing types

## Standard Template

Every puzzle type page should follow this structure (target: ≤400 lines):

```markdown
# [Puzzle Type Name]

## Core Mechanic

(3 sentences max explaining what this pattern achieves)

## When to Use

(When designer should consider this puzzle type)

## Solution Chain

1. (Specific player action)
2. (Specific player action)
3. (Specific player action)

## Examples

### [Game Code]: [Puzzle Name]

**Problem**: One sentence on the obstacle.

**Why It's This Type**: Explicit connection to Core Mechanic.

**Solution**:
1. Step...
2. Step...

---

### [Game Code]: [Puzzle Name]

(Same format)

---

### [Game Code]: [Puzzle Name]

(Same format)

---

## Related Types

| Type | Similarity | Distinction |
|------|------------|-------------|
| [Type A](path.md) | Shared characteristic | Key difference |
| [Type B](path.md) | Shared characteristic | Key difference |

## Index

| Game | Puzzle | Section |
|------|--------|---------|
| MI1 | Swordfight Insults | Examples |
| KQVI | [Puzzle Name] | Inspiration |
```

**Key Rules:**
- Core Mechanic: ≤ 3 sentences
- Exactly 3 examples (not 5, not 10)
- Solution Chain: numbered, specific actions (not "solve puzzle")
- "Why It's This Type": explicit connection to Core Mechanic
- Move extended analysis to game inspiration pages, not type definitions
- Use source codes (MI1, KQVI, QFG3) not full game names

## Guidelines

### DO:
- Focus on MECHANICS, not story details
- Keep Core Mechanic to ≤ 3 sentences
- Use exactly 3 examples with consistent format
- Link extended analysis to game inspiration pages
- Use source codes (MI1, KQVI, QFG3) not full game names
- Distinguish parallel (MFP) vs sequential (Meta-Construction) requirements

### DON'T:
- Document game-specific mechanics that don't generalize
- Create new types without 2+ examples OR one very complex example
- Use vague terms ("clever," "creative") — be mechanical
- Exceed 400 lines per page — move details to inspiration pages

## Quick Pitfalls

| Confusion | Test |
|-----------|------|
| Pattern Learning vs Observation Replay | Learn SYSTEM (PL) vs memorize SEQUENCE (OR) |
| MFP vs Meta-Construction | Gather in any order? Yes = MFP, No = Meta-Construction |
| Brokerage vs Sensory Exploitation | Trade ITEM for ITEM (IB) vs exploit PERCEPTION weakness (SE) |
| Page length | If >400 lines, move examples to inspiration pages |

## How to Design Great Puzzles of This Type

| Type | Best Practices |
|------|---------------|
| **Pattern Learning** | Teach the complete system in the tutorial domain before testing it; ensure identical mechanics between learning and application phases |
| **Multi-Faceted Plan** | Let players discover requirements through exploration, not explicit checklists; ensure the "aha" moment comes from synthesis |
| **Meta-Construction** | Make each step's output clearly feed into the next; avoid invisible dependencies |
| **Memo Chain** | Place fragments in logical locations that reward exploration; ensure assembly is obvious once all pieces found |
| **Metaphor-to-Literal** | Make the idiomatic expression memorable and culturally clear; ensure the literal mapping is logical within game world |
| **Information Brokerage** | Give each NPC a distinct personality that explains why they want what they want |
| **Sensory Exploitation** | State the perceived sense explicitly (character says "I trust only what I hear"); ensure the item genuinely matches that sense |
| **Distraction Physics** | Make the environmental chain logical and observable before player tries it; ensure cause-effect is visible |
| **Observation Replay** | Make the observed sequence memorable but not trivially reproducible; add stakes so failure has consequence |
| **Timed Consequence** | Create urgency through narrative stakes, not arbitrary deadlines; ensure player can always see the countdown |
| **Symbol Code Translation** | Provide clear visual feedback on EXAMINATION—symbols must be readable; ensure shapes/colors on artifacts match button interfaces exactly; first instance should be a sandbox with no penalty until pattern discovered |
| **Truth Revelation** | Make the hidden information logically deducible from the reveal action; ensure the item or action used has a natural connection to what's being revealed |
| **Cross-Temporal Causality** | Make cause-effect between time periods obvious once observed; ensure player can always trace back what they changed and why it worked |
| **Multi-Character Coordination** | Give each character a distinct role that's immediately clear; ensure simultaneous actions are achievable without tight real-time requirements |

**Universal Principles:**
- **Information conveyance should match the puzzle's difficulty** — complex puzzles need multiple hints, simple ones need fewer
- **Failure should teach, not punish** — when player fails, they should learn something useful
- **The solution should feel inevitable once discovered** — avoid "moon logic" where solution requires arbitrary knowledge
- **Reward the player's investment** — if puzzle requires effort, the payoff should feel earned

## Reference

- `/puzzles/` directory: All existing puzzle type definitions
- `/README.md`: Master table of contents — use to find related types for cross-reference ideas