Add: inspiration-page-creator skill for autonomous game documentation
This commit is contained in:
332
.opencode/skills/inspiration-page-creator/SKILL.md
Normal file
332
.opencode/skills/inspiration-page-creator/SKILL.md
Normal file
@@ -0,0 +1,332 @@
|
||||
---
|
||||
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
|
||||
- [ ] <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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
**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 "<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`:
|
||||
|
||||
```markdown
|
||||
## Games Analyzed
|
||||
|
||||
- [<Game Name> (<Year>)](inspiration/<game-name-kebab-case>.md)
|
||||
```
|
||||
|
||||
If "Inspiration" section doesn't exist yet, add it after "Core Principles":
|
||||
|
||||
```markdown
|
||||
# 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:**
|
||||
```markdown
|
||||
- [ ] <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:**
|
||||
```markdown
|
||||
- [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:**
|
||||
|
||||
```bash
|
||||
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: <Game>...")
|
||||
|
||||
**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/<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
|
||||
|
||||
```bash
|
||||
# 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"
|
||||
```
|
||||
@@ -0,0 +1,183 @@
|
||||
# Formatting Guide for Inspiration Pages
|
||||
|
||||
## Direct Quotes
|
||||
|
||||
### Blockquotes (for riddles, lengthy dialogue, or key game text)
|
||||
|
||||
Use when quoting verbatim game content that's central to the puzzle mechanics:
|
||||
|
||||
```markdown
|
||||
### Problem
|
||||
|
||||
A riddle on his mother's gravestone hints at the solution:
|
||||
|
||||
> "Destiny shall draw the lightning
|
||||
> Down from heaven; roll its thunder
|
||||
> Far across the sea to where I
|
||||
> Wait upon the Shore of Wonder"
|
||||
|
||||
[source citation if needed]
|
||||
```
|
||||
|
||||
**Guidelines:**
|
||||
- Preserve original line breaks with `<space><backslash>` at end of line
|
||||
- Use only when text is 2+ lines or critically important verbatim
|
||||
- Place after problem setup, before analysis
|
||||
|
||||
---
|
||||
|
||||
### Inline Quotes (for walkthrough author commentary)
|
||||
|
||||
Use when incorporating another author's observation about player experience:
|
||||
|
||||
```markdown
|
||||
As one walkthrough notes: "Look at the sheep and cast the Dye draft to dye them green, which will hide them from the dragon" [THayes].
|
||||
```
|
||||
|
||||
Or integrated into sentence:
|
||||
|
||||
```markdown
|
||||
One walkthrough captures the moment of revelation: "Remember the poem on your mother's grave? 'On the day the sky is opened...' You got it!" [GameCat].
|
||||
```
|
||||
|
||||
**Guidelines:**
|
||||
- Always attribute with citation key in brackets immediately after closing quote
|
||||
- Use double quotes for external sources, single quotes for nested quotes
|
||||
- Keep under 2 lines; if longer, use blockquote
|
||||
- Prefer quotes that capture player's "aha moment" rather than mechanical steps
|
||||
|
||||
---
|
||||
|
||||
## Citations
|
||||
|
||||
### Citation Key Format
|
||||
|
||||
Create short keys from author/source names:
|
||||
|
||||
| Author/Source | Citation Key | Example |
|
||||
|--------------|-------------|----------|
|
||||
| Tom Hayes (GameFAQs) | THayes | [THayes] |
|
||||
| Game Cat (The Spoiler) | GameCat | [GameCat] |
|
||||
| Bobbin Threadbare (LP Archive) | BobbinThreadbare | [BobbinThreadbare] |
|
||||
| StrategyWiki Community | StrategyWiki | [StrategyWiki] |
|
||||
|
||||
**Rules:**
|
||||
- Use PascalCase for multi-word keys
|
||||
- No spaces or underscores in key itself
|
||||
- Keep to max 3 words
|
||||
- Be consistent across single page (don't switch from THayes to Hayes)
|
||||
|
||||
---
|
||||
|
||||
### References Section Format
|
||||
|
||||
At end of page, before any closing content:
|
||||
|
||||
```markdown
|
||||
### References
|
||||
|
||||
[THayes] Tom Hayes, GameFAQs Walkthrough (2008). https://gamefaqs.gamespot.com/pc/564920-loom/faqs/26748
|
||||
|
||||
[GameCat] Game Cat, The Spoiler Centre Solution. https://the-spoiler.com/ADVENTURE/Lucas.Arts/loom.5.html
|
||||
|
||||
[BobbinThreadbare] Bobbin Threadbare, Let's Play Archive LP (2011). http://lparchive.org/Loom/
|
||||
```
|
||||
|
||||
**Format:**
|
||||
- `['CitationKey']` followed by one space
|
||||
- `Full Author Name,` (comma after name)
|
||||
- `Source Title (Year).` (year in parentheses if known, period after)
|
||||
- `URL` (full URL, no line break before it)
|
||||
- Blank line between entries
|
||||
|
||||
---
|
||||
|
||||
## Pattern Type Links
|
||||
|
||||
### Verify Links Work
|
||||
|
||||
Before committing, run:
|
||||
|
||||
```bash
|
||||
ls src/puzzles/ | grep -i <pattern-keyword>
|
||||
```
|
||||
|
||||
Or manually verify the file exists at `src/puzzles/<exact-filename>.md`.
|
||||
|
||||
**Common Patterns & Correct Paths:**
|
||||
|
||||
| Pattern Type Display Name | File Path (correct link) |
|
||||
|--------------------------|-------------------------|
|
||||
| Pattern Learning | `../puzzles/pattern-learning.md` |
|
||||
| Multi-Faceted Plan | `../puzzles/multi-faceted-plan.md` |
|
||||
| Meta-Puzzle Construction | `../puzzles/meta-puzzle-construction.md` |
|
||||
| Sensory Exploitation | `../puzzles/sensory-exploitation.md` |
|
||||
| Metaphor-to-Literal | `../puzzles/metaphor-literal.md` (NOT metaphor-to-literal) |
|
||||
| Distraction Physics | `../puzzles/distraction-physics.md` |
|
||||
| Observation Replay | `../puzzles/observation-replay.md` |
|
||||
|
||||
### Always Test Markdown Links
|
||||
|
||||
After writing page, build to verify:
|
||||
|
||||
```bash
|
||||
mdbook build 2>&1 | grep -i "<game-name>.md"
|
||||
```
|
||||
|
||||
If no warnings or errors about missing links, all links are valid.
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
### ❌ Wrong: Vague pattern type descriptions
|
||||
```markdown
|
||||
[Pattern Learning](../puzzles/pattern-learning.md) — This is a pattern learning puzzle because you learn something.
|
||||
```
|
||||
|
||||
### ✅ Correct: Mechanical distinction
|
||||
```markdown
|
||||
[Pattern Learning](../puzzles/pattern-learning.md) — Player learns a system (DYE changes object color) in Domain A (Hetchel's tent), then applies the same rule in Domain B (field). Unlike Multi-Faceted Plan, this is a single mechanic applied consistently—not multiple requirements gathered from different sources.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Wrong: Quote without attribution
|
||||
```markdown
|
||||
"One playthrough notes: 'the magical land was unique.'"
|
||||
```
|
||||
|
||||
### ✅ Correct: Proper citation placement
|
||||
```markdown
|
||||
One playthrough notes: "the magical land was unique and just as memorable twenty years later" [BobbinThreadbare].
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Wrong: Broken link
|
||||
```markdown
|
||||
[Metaphor-to-Literal](../puzzles/metaphor-to-literal.md) — ...
|
||||
```
|
||||
|
||||
### ✅ Correct: Verified existing file path
|
||||
```markdown
|
||||
[Metaphor-to-Literal](../puzzles/metaphor-literal.md) — ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Screenshot Alt Text Hints
|
||||
|
||||
Each placeholder should describe **what to capture**, not just generic "gameplay":
|
||||
|
||||
```markdown
|
||||
❌ 
|
||||
✅ 
|
||||
✅ 
|
||||
```
|
||||
|
||||
**Good alt text includes:**
|
||||
- Specific objects in frame
|
||||
- Key UI state or character action
|
||||
- "Before" or "after" state if showing transformation
|
||||
- Visual connection between elements (e.g., "matches", "contrasts")
|
||||
@@ -0,0 +1,115 @@
|
||||
# Inspiration Page Creation — Quick Reference Card
|
||||
|
||||
## 5-Step Autonomous Workflow
|
||||
|
||||
```
|
||||
1. Read todos/TODOS.md → Find first unchecked game task
|
||||
2. Read walkthroughs in src/walkthroughs/<game>/ → Extract puzzle data + quotes
|
||||
3. Create src/inspiration/<game>.md → Use template.md structure
|
||||
4. Verify pattern links work → ls src/puzzles/*.md
|
||||
5. Update SUMMARY.md + TODOS.md → git commit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Puzzle Selection Criteria (Top 3 Only)
|
||||
|
||||
**Priority Order:**
|
||||
1. **Mechanical clarity** — Pattern type identifiable, solution reproducible
|
||||
2. **"Aha moment" presence** — Walkthrough mentions discovery/satisfaction
|
||||
3. **Pattern diversity** — Don't pick 3 identical pattern types
|
||||
|
||||
*Additional puzzles go in "Other Puzzles" table (6-10 entries)*
|
||||
|
||||
---
|
||||
|
||||
## Required Quotes (Minimum)
|
||||
|
||||
| Section | Quote Requirement | Format |
|
||||
|---------|------------------|--------|
|
||||
| At a Glance | 2+ player enjoyment quotes | Inline: `"quote" [Key]` |
|
||||
| Each of 3 puzzles | 1+ walkthrough author quote | Blockquote or inline with attribution |
|
||||
| Other Puzzles (optional) | Memorable moments only | Inline where relevant |
|
||||
|
||||
---
|
||||
|
||||
## Screenshot Alt Text Format
|
||||
|
||||
**Must describe what to capture, not generic "gameplay":**
|
||||
|
||||
```markdown
|
||||
✅ 
|
||||
❌ 
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern Type Link Verification
|
||||
|
||||
**Common corrections:**
|
||||
- `metaphor-to-literal.md` → `metaphor-literal.md` ❌→✅
|
||||
- Always use `../puzzles/` relative path from inspiration folder
|
||||
- Verify file exists: `ls src/puzzles/ | grep <keyword>`
|
||||
|
||||
---
|
||||
|
||||
## Citation Format Rules
|
||||
|
||||
**Keys:** PascalCase, no spaces, 3 words max
|
||||
|
||||
```markdown
|
||||
[THayes] → Tom Hayes, GameFAQs Walkthrough (2008). URL
|
||||
[GameCat] → Game Cat, The Spoiler Centre Solution. URL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Word Count Target
|
||||
|
||||
- **Total:** ~1,000 words
|
||||
- Acceptable range: 800-1,200 words
|
||||
- If over 1,300 words → trim "What Makes It Rewarding" sections first
|
||||
|
||||
---
|
||||
|
||||
## Pre-Commit Checklist (Copy-Paste)
|
||||
|
||||
```
|
||||
[ ] File path: src/inspiration/<kebab-name>.md ✓
|
||||
[ ] Exactly 3 featured puzzles with Problem/Rewarding/Solution/Steps ✓
|
||||
[ ] One screenshot placeholder per puzzle with descriptive alt text ✓
|
||||
[ ] Direct quote in each "What Makes It Rewarding" section ✓
|
||||
[ ] Two+ quotes in At a Glance table ✓
|
||||
[ ] Other Puzzles table has 6-10 entries ✓
|
||||
[ ] References section has full URLs ✓
|
||||
[ ] All pattern links verified against src/puzzles/*.md ✓
|
||||
[ ] Citation keys consistent throughout ✓
|
||||
[ ] Word count near 1,000 ✓
|
||||
[ ] SUMMARY.md updated ✓
|
||||
[ ] TODOS.md marked complete ✓
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Commit Message Template
|
||||
|
||||
```
|
||||
Complete: <Game Name> inspiration page with 3 featured puzzles and pattern type links
|
||||
```
|
||||
|
||||
**Files to stage:**
|
||||
- `src/inspiration/<game>.md`
|
||||
- `todos/TODOS.md`
|
||||
- `src/SUMMARY.md`
|
||||
|
||||
---
|
||||
|
||||
## mdbook Build Check
|
||||
|
||||
After creating page, verify no link errors:
|
||||
|
||||
```bash
|
||||
mdbook build 2>&1 | grep -i "<game-name>"
|
||||
```
|
||||
|
||||
No output = all links valid ✓
|
||||
158
.opencode/skills/inspiration-page-creator/references/template.md
Normal file
158
.opencode/skills/inspiration-page-creator/references/template.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Inspiration Page Template
|
||||
|
||||
Use this exact structure for every game page in `/src/inspiration/`.
|
||||
|
||||
## File Naming
|
||||
|
||||
`src/inspiration/<game-name-kebab-case>.md`
|
||||
|
||||
Example: `loom.md`, `beneath-a-steel-sky.md`, `day-of-the-tentacle.md`
|
||||
|
||||
---
|
||||
|
||||
## Template Structure
|
||||
|
||||
```markdown
|
||||
# <Game Name> (<Year>)
|
||||
|
||||
[2-3 sentence intro summarizing game, unique mechanics, and why its puzzles matter. Include first citation if applicable.]
|
||||
|
||||
## At a Glance
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Release Year** | <Year> |
|
||||
| **Developer** | <Studio/Designer> |
|
||||
| **Core Mechanic** | <One-sentence description of what distinguishes this game> |
|
||||
| **What players found enjoyable** | "<Direct quote from walkthrough>" — [brief context] [<Citation>]. Additional playthrough notes: "<second quote>" [<Citation>] |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Puzzle 1: <Descriptive Name>
|
||||
|
||||
### Problem
|
||||
|
||||
[2-3 sentences explaining what must be accomplished. If puzzle involves a riddle or lengthy dialogue, format as blockquote:]
|
||||
|
||||
> "Exact text from game"
|
||||
|
||||
[Optional citation for setup details]
|
||||
|
||||
|
||||
|
||||
### What Makes It Rewarding
|
||||
|
||||
[2-3 sentences on mechanical design choice that creates satisfaction. Include direct quote from walkthrough author about the puzzle experience when available:]
|
||||
|
||||
"<Quote about player's moment of discovery or appreciation>" [<Citation>]
|
||||
|
||||
[Continue with mechanical analysis — why this isn't trial-and-error, how information was fairly conveyed, etc.]
|
||||
|
||||
### Solution
|
||||
|
||||
[1 sentence on outcome achieved]
|
||||
|
||||
### Steps
|
||||
1. [Specific, mechanical action]
|
||||
2. [Specific, mechanical action]
|
||||
3. [Specific, mechanical action]
|
||||
4. [Continued as needed...]
|
||||
5. [Final action that completes puzzle]
|
||||
|
||||
[<Pattern Type>](../puzzles/<pattern-slug>.md) — [1 sentence explicitly connecting this example to the core mechanic of the pattern type, distinguishing from similar types].
|
||||
|
||||
---
|
||||
|
||||
## Puzzle 2: <Descriptive Name>
|
||||
|
||||
### Problem
|
||||
|
||||
[same structure as Puzzle 1]
|
||||
|
||||
|
||||
|
||||
### What Makes It Rewarding
|
||||
|
||||
[same structure as Puzzle 1, with direct quote]
|
||||
|
||||
### Solution
|
||||
|
||||
[same structure as Puzzle 1]
|
||||
|
||||
### Steps
|
||||
[n numbered specific actions]
|
||||
|
||||
[<Pattern Type>](../path/to/pattern.md) — [connection to pattern mechanic].
|
||||
|
||||
---
|
||||
|
||||
## Puzzle 3: <Descriptive Name>
|
||||
|
||||
### Problem
|
||||
|
||||
[same structure as Puzzle 1]
|
||||
|
||||
|
||||
|
||||
### What Makes It Rewarding
|
||||
|
||||
[same structure as Puzzle 1, with direct quote]
|
||||
|
||||
### Solution
|
||||
|
||||
[same structure as Puzzle 1]
|
||||
|
||||
### Steps
|
||||
[n numbered specific actions]
|
||||
|
||||
[<Pattern Type>](../path/to/pattern.md) — [connection to pattern mechanic].
|
||||
|
||||
---
|
||||
|
||||
## Other Puzzles
|
||||
|
||||
| Name | Problem & Solution | Pattern Type |
|
||||
|------|-------------------|--------------|
|
||||
| <Name 1> | [<15-word description>; include inline quote citation like `<"text" <Citation>>` if memorable] | [<Pattern>](../path/pattern.md) |
|
||||
| <Name 2> | [Description with citation if needed] | [<Pattern>](../path/pattern.md) |
|
||||
| <Name 3> | [Description with citation] | [<Pattern>](../path/pattern.md) |
|
||||
| <Name 4> | [Description] | [<Pattern>](../path/pattern.md) |
|
||||
| <Name 5> | [Description with citation] | [<Pattern>](../path/pattern.md) |
|
||||
| <Name 6+> | [Continue to ~8 entries total, or as many notable puzzles as exist] | [<Pattern>](../path/pattern.md) |
|
||||
|
||||
---
|
||||
|
||||
### References
|
||||
|
||||
[<CitationKey1>] Full Author Name, Source Title (Year). URL
|
||||
|
||||
[<CitationKey2>] Full Author Name, Source Title (Year). URL
|
||||
|
||||
[<CitationKey3>] Full Author Name, Source Title (Year). URL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Word Count Target
|
||||
|
||||
**~1,000 words total**, broken down as:
|
||||
- Introduction + At a Glance: ~150 words
|
||||
- Each featured puzzle: ~250 words × 3 = ~750 words
|
||||
- Other Puzzles table + References: ~150 words
|
||||
|
||||
---
|
||||
|
||||
## Critical Requirements Checklist
|
||||
|
||||
Before committing:
|
||||
|
||||
- [ ] Exactly 3 featured puzzles with full Problem/Rewarding/Solution/Steps sections
|
||||
- [ ] One screenshot placeholder per puzzle with specific alt text hint describing what to capture
|
||||
- [ ] At least one direct quote formatted as blockquote or inline in each "What Makes It Rewarding" section
|
||||
- [ ] At minimum one direct quote in "What players found enjoyable" field of At a Glance table
|
||||
- [ ] All Pattern Type links point to existing files (verify with `ls src/puzzles/`)
|
||||
- [ ] Filename matches kebab-case of game name
|
||||
- [ ] References section includes full URLs for all cited walkthroughs
|
||||
- [ ] Citation keys match between in-text citations and References section
|
||||
Reference in New Issue
Block a user