--- name: inspiration-page-creator description: 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": ```markdown - [ ] : analyze walkthrough and create game section - [ ] Examine walkthrough files in src/walkthroughs// - [ ] 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//` and list all files: ```bash ls src/walkthroughs// ``` 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/.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: ```bash 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: ```bash mdbook build 2>&1 | grep -i "" ``` If warnings or errors appear about missing links, fix them. --- ### Step 8: Update SUMMARY.md Add entry under `# Inspiration` section in `src/SUMMARY.md`: ```markdown ## Games Analyzed - [ ()](inspiration/.md) ``` If "Inspiration" section doesn't exist yet, add it after "Core Principles": ```markdown # Core Principles - [Core Principles](core-principles.md) # Inspiration ## Games Analyzed - [ ()](inspiration/.md) ``` --- ### Step 9: Update TODOS and Commit Mark the game task as complete in `todos/TODOS.md`: **Before:** ```markdown - [ ] : analyze walkthrough and create game section - [ ] Examine walkthrough files in src/walkthroughs// - [ ] 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:** ```markdown - [x] : analyze walkthrough and create game section - [x] Examine walkthrough files in src/walkthroughs// - [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:** ```bash git add src/inspiration/.md todos/TODOS.md src/SUMMARY.md git commit -m "Complete: inspiration page with 3 featured puzzles and pattern type links" ``` --- ## Critical Validation Checklist Before committing, verify: - [ ] File created at correct path: `src/inspiration/.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 ```markdown "The tragic story of Bobbin Threadbare and his quest to save the world..." ``` ### ✅ Correct: Mechanical description ```markdown "Player learns magical drafts by observing enchanted objects; each draft can then be reused elsewhere." ``` --- ### ❌ Wrong: Vague reward analysis ```markdown "This puzzle is clever and creative." ``` ### ✅ Correct: Mechanical satisfaction ```markdown "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 ```markdown "One walkthrough notes this was memorable." ``` ### ✅ Correct: Proper citation placement ```markdown "One walkthrough notes: 'the magical land was unlike any I'd ever seen' [AuthorKey]." ``` --- ## File Path References - **Output location:** `src/inspiration/.md` - **Walkthrough sources:** `src/walkthroughs//` - **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 ```bash # Step 1: Identify target game cat todos/TODOS.md | grep -A 5 "^\- \[ \]" | head -20 # Step 2: List walkthrough files ls src/walkthroughs// # Step 7: Verify pattern links exist ls src/puzzles/*.md # Step 8: Build check after page creation mdbook build 2>&1 | grep -i "" # Step 9: Commit changes git add src/inspiration/.md todos/TODOS.md src/SUMMARY.md git commit -m "Complete: inspiration page with 3 featured puzzles and pattern type links" ```