puzzle-design-kb/.opencode/skills/inspiration-page-creator/SKILL.md

name, description

name	description
inspiration-page-creator	This skill should be used when creating new game pages for the Inspiration section of puzzle-design-kb. It automates walkthrough analysis, puzzle extraction, and documentation in a standardized format while managing TODOS.md and committing after completion.

Inspiration Page Creator Skill

Quick Start

1. Load this skill before starting any inspiration page work
2. Read todos/TODOS.md to find next game task marked with [ ]
3. Execute autonomous workflow (no user intervention needed)
4. Commit and mark TODO complete after page creation

---

Workflow: Autonomous Page Creation

Step 1: Identify Target Game from TODOS

Read todos/TODOS.md and locate the first unchecked game entry under "Puzzle Sampling Chapter":

- [ ] <Game Name>: analyze walkthrough and create game section
    - [ ] Examine walkthrough files in src/walkthroughs/<game-dir>/
    - [ ] Identify the 3 best puzzles using analysis-checklist.md criteria
    - [ ] Write Problem/Why It Works/Solution/Steps for each puzzle
    - [ ] Link each puzzle to its pattern type from the Playbook

Set target game name and corresponding walkthrough directory path.

---

Step 2: Examine Walkthrough Files

Navigate to src/walkthroughs/<game-dir>/ and list all files:

ls src/walkthroughs/<game-dir>/

Read the README first if it exists (README.txt or similar). Note available walkthrough sources, authors, and any special notes about the game's design.

Read at least 2 complete walkthroughs from different sources to:

• Identify all puzzles in the game
• Find quotes about player enjoyment moments
• Gather multiple perspectives on puzzle mechanics
• Collect citation information (author name, source, URL)

---

Step 3: Select 3 Best Puzzles

Apply these criteria for puzzle selection (from docs/analysis-checklist.md):

Priority 1: Mechanical Clarity

• Can the pattern type be clearly identified?
• Is the solution chain reproducible across different playthroughs?
• Does it demonstrate a documented pattern from Playbook?

Priority 2: "Aha Moment" Presence

• Do walkthrough authors explicitly mention discovery or satisfaction?
• Is there a moment where information clicks together non-trivially?
• Does the solution feel earned rather than obvious?

Priority 3: Pattern Diversity

• Avoid selecting 3 puzzles of identical pattern type if possible
• Show range of mechanics the game offers
• Include at least one puzzle requiring multi-step reasoning

Select exactly 3 puzzles. Note any 5-8 additional notable puzzles for "Other Puzzles" table.

---

Step 4: Extract Required Content For Each Featured Puzzle

For each of the 3 selected puzzles, extract:

1. Problem Setup (2-3 sentences)

   • What must player accomplish?
   • Key information or prerequisite knowledge required
   • If riddle or dialogue involved, copy exact game text for blockquote

2. What Makes It Rewarding (2-3 sentences + quote)

   • Mechanical design choice that creates satisfaction
   • How information was fairly conveyed to player
   • Why this isn't trial-and-error or fetch-quest filler
   • REQUIRED: Direct quote from walkthrough author about experiencing this puzzle

3. Solution (1 sentence)

   • Outcome achieved upon completion

4. Steps (numbered list)

   • Specific, mechanical actions (no "solve puzzle" vagueness)
   • Each step should be an observable player action
   • Include state changes or discovered information as relevant

5. Pattern Type Classification

   • Identify which Playbook pattern type matches
   • Write 1-sentence distinction connecting this example to core mechanic
   • Differentiate from at least one similar pattern type

6. Screenshot Placeholder

   • One per puzzle with descriptive alt text hint
   • Describe specific visual: objects, UI state, "before/after" moment

---

Step 5: Extract Additional Content

1. At a Glance Table Data:

   • Release year
   • Developer/studio/designer name(s)
   • One-sentence core mechanic description
   • Minimum 2 direct quotes about player enjoyment with attributions

2. Other Puzzles (6-10 entries):

   • Name of puzzle
   • 10-15 word problem and solution summary
   • Pattern type classification with link
   • Include inline quotation citations if memorable moments exist

3. References Section:

   • Full author names
   • Source titles
   • Publication years (if known)
   • URLs for all cited walkthrough sources

---

Step 6: Create the Page File

Create file at src/inspiration/<game-name-kebab-case>.md using exact template from references/template.md.

While writing:

• Fill each section with extracted content
• Format direct quotes as blockquotes (riddles/game text) or inline commentary (author observations)
• Use citation keys consistently: [Author], [SourceAuthor], etc.
• Include exactly 3 featured puzzles, plus Other Puzzles table
• Add screenshot placeholders with descriptive alt text for each major puzzle

Word count target: ~1,000 words total (don't exceed significantly)

---

Step 7: Verify Pattern Type Links

List existing pattern files to verify all links work:

ls src/puzzles/*.md

Cross-reference every Pattern Type link in your page against this list. Correct any broken paths before proceeding.

Common corrections:

• metaphor-to-literal.md → metaphor-literal.md (actual filename)
• Ensure relative path is ../puzzles/ (not ./puzzles/)

Build book to confirm no link errors:

mdbook build 2>&1 | grep -i "<game-name>"

If warnings or errors appear about missing links, fix them.

---

Step 8: Update SUMMARY.md

Add entry under # Inspiration section in src/SUMMARY.md:

## Games Analyzed

- [<Game Name> (<Year>)](inspiration/<game-name-kebab-case>.md)

If "Inspiration" section doesn't exist yet, add it after "Core Principles":

# Core Principles

- [Core Principles](core-principles.md)

# Inspiration

## Games Analyzed

- [<Game Name> (<Year>)](inspiration/<game-name-kebab-case>.md)

---

Step 9: Update TODOS and Commit

Mark the game task as complete in todos/TODOS.md:

Before:

- [ ] <Game Name>: analyze walkthrough and create game section
    - [ ] Examine walkthrough files in src/walkthroughs/<game-dir>/
    - [ ] Identify the 3 best puzzles using analysis-checklist.md criteria
    - [ ] Write Problem/Why It Works/Solution/Steps for each puzzle
    - [ ] Link each puzzle to its pattern type from the Playbook

After:

- [x] <Game Name>: analyze walkthrough and create game section
    - [x] Examine walkthrough files in src/walkthroughs/<game-dir>/
    - [x] Identify the 3 best puzzles using analysis-checklist.md criteria
    - [x] Write Problem/Why It Works/Solution/Steps for each puzzle
    - [x] Link each puzzle to its pattern type from the Playbook

Stage and commit:

git add src/inspiration/<game>.md todos/TODOS.md src/SUMMARY.md
git commit -m "Complete: <Game Name> inspiration page with 3 featured puzzles and pattern type links"

---

Critical Validation Checklist

Before committing, verify:

• File created at correct path: src/inspiration/<kebab-case-game-name>.md
• Exactly 3 featured puzzles with full Problem/Rewarding/Solution/Steps sections
• One screenshot placeholder per featured puzzle with specific alt text hint
• At least one direct quote in each "What Makes It Rewarding" section (formatted correctly)
• Minimum two quotes in "What players found enjoyable" field of At a Glance table
• Other Puzzles table has 6-10 entries with pattern links and descriptions
• References section includes full URLs for every cited walkthrough source
• All Pattern Type links verified against existing src/puzzles/*.md files
• Citation keys are consistent (key in text matches entry in References)
• Word count near 1,000 words (acceptable range: 800-1,200)
• SUMMARY.md updated with new game entry
• TODOS.md marked complete for this game task
• No unintended files staged (check git status before commit)

---

Autonomy Rules

Do not ask user for input on:

• Which puzzle to describe next (proceed through all 3 selected puzzles)
• Word count adjustments (trust the ~1,000 word target)
• Whether to include a specific detail (if it fits guidelines, include it)
• Commit message format (use standard template: "Complete: ...")

Do ask user for input on:

• Only if walkthrough files are missing or incomplete in expected directory
• If Pattern Type classification is genuinely ambiguous (after checking existing playbook types)
• If game design decision is unclear from available walkthroughs

---

Common Pitfalls to Avoid

❌ Wrong: Narrative-over-mechanics focus

"The tragic story of Bobbin Threadbare and his quest to save the world..."

✅ Correct: Mechanical description

"Player learns magical drafts by observing enchanted objects; each draft can then be reused elsewhere."

---

❌ Wrong: Vague reward analysis

"This puzzle is clever and creative."

✅ Correct: Mechanical satisfaction

"The player realizes the dragon only eats *white* sheep (established in dialogue), so DYE learned on wool becomes camouflage—applying rules consistently across contexts rather than trial-and-error spam."

---

❌ Wrong: Missing quote attribution

"One walkthrough notes this was memorable."

✅ Correct: Proper citation placement

"One walkthrough notes: 'the magical land was unlike any I'd ever seen' [AuthorKey]."

---

File Path References

• Output location: src/inspiration/<game-name>.md
• Walkthrough sources: src/walkthroughs/<game-dir>/
• Task tracking: todos/TODOS.md
• Navigation links: src/SUMMARY.md
• Pattern type files: src/puzzles/*.md
• Skill references: This skill's directory contains template and formatting guide

---

Execution Command Flow

# Step 1: Identify target game
cat todos/TODOS.md | grep -A 5 "^\- \[ \]" | head -20

# Step 2: List walkthrough files  
ls src/walkthroughs/<game-dir>/

# Step 7: Verify pattern links exist
ls src/puzzles/*.md

# Step 8: Build check after page creation
mdbook build 2>&1 | grep -i "<game-name>"

# Step 9: Commit changes
git add src/inspiration/<game>.md todos/TODOS.md src/SUMMARY.md
git commit -m "Complete: <Game Name> inspiration page with 3 featured puzzles and pattern type links"