diff --git a/.opencode/skills/adventure-puzzle-analyzer/SKILL.md b/.opencode/skills/adventure-puzzle-analyzer/SKILL.md index 62b85c0..d9fef28 100644 --- a/.opencode/skills/adventure-puzzle-analyzer/SKILL.md +++ b/.opencode/skills/adventure-puzzle-analyzer/SKILL.md @@ -58,54 +58,89 @@ For each walkthrough section, note: ## Standard Template +Every puzzle type page should follow this structure (target: ≤400 lines): + ```markdown # [Puzzle Type Name] -**Information Architecture**: How info is conveyed to player +## Core Mechanic -**Player Action Pattern**: -1. Step one -2. Step two -3. Solution +(3 sentences max explaining what this pattern achieves) -**Core Mechanic**: One sentence on underlying logic. +## When to Use -**Variations**: Brief list or table of manifestations +(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 Examples +### [Game Code]: [Puzzle Name] -### [Game]: [Puzzle Name] +(Same format) -**Mechanic**: Brief setup. +--- -**Solution Chain**: -1. Action with discovery... -2. Action... -3. Result... +### [Game Code]: [Puzzle Name] -**Why It's This Type**: Explicit connection to core mechanic. +(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 -- Use /README.md as reference for related types when cross-linking -- Keep Core Mechanic to ONE sentence +- 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 @@ -114,6 +149,7 @@ For each walkthrough section, note: | 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 | ## Reference diff --git a/REFACTOR_PUZZLE_TYPES.md b/REFACTOR_PUZZLE_TYPES.md new file mode 100644 index 0000000..1043db0 --- /dev/null +++ b/REFACTOR_PUZZLE_TYPES.md @@ -0,0 +1,212 @@ +# 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: + +```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 | +``` + +--- + +## 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`): +```markdown +### 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": +```markdown +| 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`) diff --git a/todos/TODOS.md b/todos/TODOS.md index 3ee24f5..4956d0e 100644 --- a/todos/TODOS.md +++ b/todos/TODOS.md @@ -324,9 +324,37 @@ - [x] mdbook build passes with no broken links ✓ (only pre-existing HTML tag warnings remain) - [x] At least 25 commits created ✓ - Total hierarchy work commits: ~35+ -See commit history above for full breakdown by phase.ction-physics.md -- [ ] All Related Types sections updated across all puzzle type files -- [ ] All Inspiration pages checked and links fixed -- [ ] SUMMARY.md restructured hierarchically under parent categories -- [ ] mdbook build passes with no broken links -- [ ] At least 25 commits created (one per completed task) +See commit history above for full breakdown by phase. + +--- + +# Puzzle Type Page Refactoring + +See [REFACTOR_PUZZLE_TYPES.md](../REFACTOR_PUZZLE_TYPES.md) for detailed plan. + +## Phase 1: Pilot - Refactor Tier 1 Pages (Most Verbose) +- [ ] Refactor `pattern-learning.md` (target: ≤400 lines, 3 examples) + - Keep: Core Mechanic, Solution Chain, 3 best examples + - Move: Extended MI2/MI1/BAS/QFG4 analysis → respective game inspiration pages + - Commit after each change +- [ ] Refactor `sensory-exploitation.md` (target: ≤400 lines, 3 examples) + - Keep: Core Mechanic, 3 examples (parrot, poodle, Medusa mirror) + - Move: QFG3 honeybird/meerbat, Loom tower, etc. → inspiration pages +- [ ] Refactor `multi-faceted-plan.md` (target: ≤400 lines, 3 examples) + - Keep: Core Mechanic, parallel MFP examples only + - Move: QFG2/QFG3/QFG4 multi-examples → inspiration pages + +## Phase 2: Refactor Tier 2 Pages +- [ ] Refactor `sequential-construction.md` — needs Core Mechanic, trim examples +- [ ] Refactor `information-brokerage.md` — needs format cleanup +- [ ] Refactor `environmental-storytelling.md` — needs format cleanup +- [ ] Refactor `memo-chain.md` — needs format cleanup + +## Phase 3: Review and Cleanup Tier 3 Pages +- [ ] Review and cleanup remaining puzzle type pages (≤400 lines each) +- [ ] Verify Related Types tables are consistent across all pages + +## Phase 4: Validation +- [ ] Run `npx remark-cli` on all changed files +- [ ] Run `mdbook build` to verify no broken links +- [ ] Final review of SUMMARY.md navigation structure