puzzle-design-kb/.opencode/skills/adventure-puzzle-analyzer/SKILL.md

name, description

name	description
adventure-puzzle-analyzer	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):

# [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