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

Add: inspiration-page-creator skill for autonomous game documentation

Browse Source
This commit is contained in:
Bryce
2026-03-18 17:04:50 -07:00
parent ab22ec6f69
commit 54aa233142
4 changed files with 788 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
.opencode/skills/inspiration-page-creator/references/formatting-guide.md Normal file
View File

@@ -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
❌ ![Game screenshot](./loom-puzzle1.png)
✅ ![Gravestone showing riddle and tree symbol that matches mountaintop tree](./loom-puzzle1.png)
✅ ![Workers visible at top of green tower before APPEAR draft is cast](./loom-puzzle3.png)
```
**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")

115
.opencode/skills/inspiration-page-creator/references/quick-reference.md Normal file
View File

@@ -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
✅ ![Gravestone showing riddle and tree symbol that matches mountaintop tree](./loom-puzzle1.png)
❌ ![Game screenshot](./loom-puzzle1.png)
```
---
## 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
View 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>] |
![Game overview screenshot — <descriptive alt text hint for capturing the shot>](./<game>-overview.png)
---
## 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]
![<Specific visual to capture — key objects, UI state, character positions>](./<game>-puzzle1.png)
### 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]
![<descriptive alt text hint>](./<game>-puzzle2.png)
### 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]
![<descriptive alt text hint>](./<game>-puzzle3.png)
### 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