From 9180ccfaab58ab6d0e9a11899ffba1b5254e4f88 Mon Sep 17 00:00:00 2001 From: Bryce Date: Tue, 17 Mar 2026 20:10:59 -0700 Subject: [PATCH] Add adventure-puzzle-analyzer skill for walkthrough analysis and playbook updates --- skills/adventure-puzzle-analyzer/SKILL.md | 121 +++++++++++++++++++ skills/adventure-puzzle-analyzer/examples.md | 67 ++++++++++ 2 files changed, 188 insertions(+) create mode 100644 skills/adventure-puzzle-analyzer/SKILL.md create mode 100644 skills/adventure-puzzle-analyzer/examples.md diff --git a/skills/adventure-puzzle-analyzer/SKILL.md b/skills/adventure-puzzle-analyzer/SKILL.md new file mode 100644 index 0000000..62b85c0 --- /dev/null +++ b/skills/adventure-puzzle-analyzer/SKILL.md @@ -0,0 +1,121 @@ +--- +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 + +```markdown +# [Puzzle Type Name] + +**Information Architecture**: How info is conveyed to player + +**Player Action Pattern**: +1. Step one +2. Step two +3. Solution + +**Core Mechanic**: One sentence on underlying logic. + +**Variations**: Brief list or table of manifestations + +--- + +## Game Examples + +### [Game]: [Puzzle Name] + +**Mechanic**: Brief setup. + +**Solution Chain**: +1. Action with discovery... +2. Action... +3. Result... + +**Why It's This Type**: Explicit connection to core mechanic. + +--- + +## Related Types + +| Type | Similarity | Distinction | +``` + +## Guidelines + +### DO: +- Focus on MECHANICS, not story details +- Use /README.md as reference for related types when cross-linking +- Keep Core Mechanic to ONE sentence +- 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 + +## 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) | + +## Reference + +- `/puzzles/` directory: All existing puzzle type definitions +- `/README.md`: Master table of contents — use to find related types for cross-reference ideas diff --git a/skills/adventure-puzzle-analyzer/examples.md b/skills/adventure-puzzle-analyzer/examples.md new file mode 100644 index 0000000..1328ee1 --- /dev/null +++ b/skills/adventure-puzzle-analyzer/examples.md @@ -0,0 +1,67 @@ +# Examples + +## Adding Example to Existing Type + +In `puzzles/metaphor-literal.md`, under "## Game Examples": + +```markdown +### Monkey Island II: Bone Maze Navigation Song + +**Metaphor from dream**: "The HEAD bone is connected to the RIB bone, the RIB bone to the LEG bone..." + +**Translation Chain**: +1. Player hears song during dream state +2. Later encounters maze with Ugly Bone Thing wall panels +3. Recognizes song describes physical connections; first 3 bones per verse = passages +4. Push HEAD→RIB→LEG for each room, ignoring 4th bone (noise) + +**Why It's This Type**: Poetic encoding must be decoded into literal mechanical solution. +``` + +## Creating New Type Document + +File: `puzzles/kebab-case-name.md` + +```markdown +# [Type Name] + +**Information Architecture**: How player discovers puzzle structure. + +**Player Action Pattern**: +1. Step one +2. Step two +3. Solution + +**Core Mechanic**: One sentence only. + +--- + +## Game Examples + +### [Game]: [Puzzle] + +**Setup**: Brief context. + +**Solution Chain**: +1-5. Actions and discoveries... + +**Why It's This Type**: Explicit link to core mechanic. + +--- + +## Related Types + +| Type | Similarity | Distinction | +``` + +Then update `/README.md` table of contents with new row. + +## README Update Format + +```markdown +| 14 | [New Type](./puzzles/new-type.md) | One-line core mechanic | MI2 | +``` + +- Increment number sequentially +- Link uses kebab-case matching filename +- Game Source = KQVI, MI1, MI2, or "TBD" \ No newline at end of file