puzzle-design-kb/REFACTOR_PUZZLE_TYPES.md

Refactoring Puzzle Type Pages

Analysis

Current State

The puzzle type pages in /src/puzzles/ suffer from severe inconsistency and bloat:

File	Lines	Issues
pattern-learning.md	825	Massive dump of all analysis, no clear sections
sensory-exploitation.md	860+	Same problem
multi-faceted-plan.md	1000+	Same problem
sequential-construction.md	~300	Slightly better but still inconsistent

What works:

• Game inspiration pages (e.g., beneath-a-steel-sky.md) use a clean, consistent format:
  • Problem
  • Why It Works
  • Solution
  • Steps (numbered)
  • Pattern Type links

Target Format (per README)

The README specifies playbook pages should have:

1. Understandable title describing the core mechanic
2. What this puzzle type achieves and when to use it
3. Mechanic-oriented analysis (setting-independent patterns)
4. Three illustrative examples from reference games
5. Cross-links to cited puzzles in Inspiration section
6. Index table of other game implementations

Problems to Fix

1. No Core Mechanic section — Most pages bury the core mechanic in prose
2. No Solution Chain format — Should be numbered steps, not prose
3. Too many examples — Pages try to include ALL examples; should be exactly 3
4. Inconsistent "Why It's This Type" — Some have it, some don't
5. Missing Related Types tables — Some have it, format varies
6. Verbose analysis should move to inspiration pages — The deep walkthrough analysis belongs in game inspiration docs, not in the type definitions

---

Refactoring Template

Every puzzle type page should follow this structure:

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

---

Files to Refactor

Tier 1 (High Priority — Most Verbose)

1. pattern-learning.md (825 lines)

   • Keep: Core Mechanic, Solution Chain, 3 best examples
   • Move: Extended MI2/MI1/BAS/QFG4 analysis → respective game inspiration pages
   • Remove: Redundant examples beyond 3

2. sensory-exploitation.md (860+ lines)

   • Keep: Core Mechanic, 3 examples (parrot, poodle, Medusa mirror)
   • Move: QFG3 honeybird/meerbat, Loom tower, etc. → inspiration pages

3. multi-faceted-plan.md (1000+ lines)

   • Keep: Core Mechanic, 3 examples
   • Move: QFG2/QFG3/QFG4 multi-examples → inspiration pages
   • Keep meta-puzzle distinction in Related Types

Tier 2 (Medium Priority)

4. sequential-construction.md — Needs Core Mechanic section, trim examples
5. information-brokerage.md — Needs format cleanup
6. environmental-storytelling.md — Needs format cleanup
7. memo-chain.md — Needs format cleanup

Tier 3 (Lower Priority — Already Compact)

8. truth-revelation.md — Already reasonable length
9. cross-temporal-causality.md — Needs minor cleanup
10. cross-realm-logistics.md — Needs minor cleanup
11. multi-character-coordination.md — Needs minor cleanup
12. timed-consequence.md — Needs minor cleanup
13. comedy-based-persuasion.md — Needs minor cleanup
14. distraction-environmental-manipulation.md — Needs minor cleanup
15. class-specific-ritual.md — Needs minor cleanup
16. multi-faction-diplomacy.md — Needs minor cleanup
17. robot-programming.md — Needs minor cleanup
18. escalating-combat-progression.md — Needs minor cleanup
19. surreal-logic-bridge.md — Needs minor cleanup
20. metaphor-literal.md — Needs minor cleanup
21. observation-replay.md — Needs minor cleanup
22. symbol-code-translation.md — Needs minor cleanup

---

Migration Strategy

Moving Analysis to Inspiration Pages

For each example removed from puzzle type pages:

1. Add to appropriate game inspiration page under "Other Notable Puzzles" table
2. Link back to the puzzle type page
3. Include brief description (1-2 sentences)

Example:

Before (in pattern-learning.md):

### Grim Fandango: Coat Check System + Photo Finish Ticket (GF - Year Two)

[800 lines of detailed analysis...]

After (in inspiration/grim-fandango.md):

Add to "Other Notable Puzzles":

| Grim Fandango: Coat Check + Photo Finish | [[Pattern Learning](../puzzles/pattern-learning.md)] | Color-coded ticket systems encode information requiring symbol translation |

Updating Cross-References

After refactoring:

1. Verify all links in SUMMARY.md still work
2. Update any Also Uses: references in inspiration pages
3. Ensure Related Types tables point to correct files

---

Quality Checklist

After refactoring each page, verify:

• Core Mechanic is ≤ 3 sentences
• Solution Chain uses numbered list with specific actions
• Exactly 3 examples with "Why It's This Type" analysis
• Related Types differentiates from ≥ 2 similar types
• Filename matches kebab-case title
• Page targets ≤ 400 lines
• All game references use source code (MI1, KQVI) not full names
• Links to inspiration pages for extended examples

---

Implementation Order

1. Update skill template (adventure-puzzle-analyzer/SKILL.md) to reflect target format
2. Refactor Tier 1 pages as pilot (pattern-learning, sensory-exploitation, multi-faceted-plan)
3. Update inspiration pages with migrated examples
4. Refactor Tier 2 pages
5. Review and cleanup Tier 3 pages
6. Run validation (npx remark-cli) on all changed files
7. Build and verify (mdbook build)