notid/puzzle-design-kb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add puzzle type refactoring plan and update skill template

Browse Source 
- Create REFACTOR_PUZZLE_TYPES.md with detailed analysis and implementation plan
- Update adventure-puzzle-analyzer skill template to match target playbook format:
  - Core Mechanic section (≤3 sentences)
  - Exactly 3 examples with consistent format
  - Solution Chain as numbered specific actions
  - Add Key Rules section
- Add refactoring tasks to TODOS.md referencing the plan
This commit is contained in:
Bryce
2026-03-19 09:43:28 -07:00
parent e9a23c8eb7
commit 0648d82c60
3 changed files with 299 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
.opencode/skills/adventure-puzzle-analyzer/SKILL.md
View File

@@ -58,54 +58,89 @@ For each walkthrough section, note:
## Standard Template ## Standard Template
Every puzzle type page should follow this structure (target: ≤400 lines):
```markdown ```markdown
# [Puzzle Type Name] # [Puzzle Type Name]
**Information Architecture**: How info is conveyed to player ## Core Mechanic
**Player Action Pattern**: (3 sentences max explaining what this pattern achieves)
1. Step one
2. Step two
3. Solution
**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**: ### [Game Code]: [Puzzle Name]
1. Action with discovery...
2. Action...
3. Result...
**Why It's This Type**: Explicit connection to core mechanic. (Same format)
--- ---
## Related Types ## Related Types
| Type | Similarity | Distinction | | 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 ## Guidelines
### DO: ### DO:
- Focus on MECHANICS, not story details - Focus on MECHANICS, not story details
- Use /README.md as reference for related types when cross-linking - Keep Core Mechanic to ≤ 3 sentences
- Keep Core Mechanic to ONE sentence - 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 - Distinguish parallel (MFP) vs sequential (Meta-Construction) requirements
### DON'T: ### DON'T:
- Document game-specific mechanics that don't generalize - Document game-specific mechanics that don't generalize
- Create new types without 2+ examples OR one very complex example - Create new types without 2+ examples OR one very complex example
- Use vague terms ("clever," "creative") — be mechanical - Use vague terms ("clever," "creative") — be mechanical
- Exceed 400 lines per page — move details to inspiration pages
## Quick Pitfalls ## Quick Pitfalls
@@ -114,6 +149,7 @@ For each walkthrough section, note:
| Pattern Learning vs Observation Replay | Learn SYSTEM (PL) vs memorize SEQUENCE (OR) | | 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 | | 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) | | 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 ## Reference

212
REFACTOR_PUZZLE_TYPES.md Normal file
View File

@@ -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`)

40
todos/TODOS.md
View File

@@ -324,9 +324,37 @@
- [x] mdbook build passes with no broken links ✓ (only pre-existing HTML tag warnings remain) - [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+ - [x] At least 25 commits created ✓ - Total hierarchy work commits: ~35+
See commit history above for full breakdown by phase.ction-physics.md See commit history above for full breakdown by phase.
- [ ] 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 # Puzzle Type Page Refactoring
- [ ] At least 25 commits created (one per completed task)
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