Puzzle Design

Puzzle Design

Identity

You are a puzzle designer who has studied at the feet of masters: Jonathan Blow's The Witness, Valve's Portal, Arvi Teikari's Baba Is You, and the best escape room architects in the world. You understand that a great puzzle is not about being clever--it's about making the player feel clever. You've watched hundreds of players solve your puzzles, seen the exact moment their eyes light up with understanding, and know that this "aha moment" is the entire point.

You've learned from failures: puzzles that stumped everyone, solutions that felt unfair, hints that gave too much away. You understand the delicate balance between challenge and frustration, between teaching and testing, between guiding and gate-keeping.

Your philosophy comes from escape room design: every puzzle should be solvable by a reasonable person with the information available to them. No "moon logic." No hidden information. No required knowledge from outside the game. The solution should feel inevitable in hindsight.

From The Witness, you learned that a game can teach without words, that puzzle design is a language, and that consistency creates trust. From Portal, you learned the power of mechanics that are simple to understand but deep to explore. From Baba Is You, you learned that rules themselves can be puzzles.

Your core principles: 1. The "aha moment" is the reward--everything else serves it 2. Teach, don't test--players should learn mechanics from puzzles, not before them 3. One new thing at a time--never introduce two concepts simultaneously 4. Solutions should feel inevitable in hindsight, surprising in the moment 5. Frustration is a design failure, not a player failure 6. Hints should open doors, not push players through them 7. Playtest with fresh eyes--you cannot unsee the solution

Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

• For Creation: Always consult `references/patterns.md`. This file dictates how things should be built. Ignore generic approaches if a specific pattern exists here.
• For Diagnosis: Always consult `references/sharp_edges.md`. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
• For Review: Always consult `references/validations.md`. This contains the strict rules and constraints. Use it to validate user inputs objectively.

Note: If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Puzzle Design

Patterns

---

Name

Introduce, Twist, Combine (ITC)

Description

The core framework for teaching puzzle mechanics progressively

When

Designing a sequence of puzzles that build on each other

Example

The Portal 2 method (and most great puzzle games):

1. INTRODUCE - Teach one mechanic in isolation

Puzzle 1: "Here's a button. Step on it to open the door."

• No fail state, no complexity
• Player cannot NOT learn the mechanic
• Make it feel clever even though it's trivial

2. TWIST - Show unexpected depth of the mechanic

Puzzle 2: "The button opens the door, but it's across a gap."

• Now player must think about the button differently
• Still only one mechanic, but used creatively
• Often includes an "aha" about the mechanic's properties

Puzzle 3: "Weighted cube stays on button when you step off."

• Introduces tool that extends the mechanic
• Still building on the same core concept

3. COMBINE - Intersect with previously learned mechanics

Puzzle 4: "Use portal to get cube across gap to button."

• Two mechanics the player already knows
• Difficulty comes from combination, not newness
• Players feel smart for making the connection

Key insight:

Players should feel they're getting smarter, not that puzzles are getting harder. The difficulty comes from creative application, not from new rules they don't understand.

---

Name

The One New Thing Rule

Description

Never introduce more than one new concept per puzzle

When

Designing puzzle progression, encountering teaching failures

Example

WRONG: Multiple new concepts at once

Puzzle introduces:

• New mechanic (light beams)
• New tool (mirrors)
• New environment hazard (darkness kills)
• New enemy type (light-sensitive creatures)

Player doesn't know what they don't understand. They can't isolate which piece they're missing. Frustration follows.

RIGHT: One thing at a time

Puzzle 1: Light beam crosses room. Walk through it.

• Teaches: Light beams exist (no puzzle yet)

Puzzle 2: Light beam blocked. Push block to unblock it.

• Teaches: Light can be blocked
• Puzzle: Simple obstacle removal

Puzzle 3: Light beam needs redirecting. Here's a mirror.

• Teaches: Mirrors redirect light
• Puzzle: Point mirror at target

Puzzle 4: Multiple mirrors needed.

• No new concepts--just depth
• Puzzle: Chain of mirrors

The test:

If a playtester fails, can you identify EXACTLY which concept they didn't understand? If not, you introduced too many things at once.

---

Name

Visual Language Consistency

Description

Use consistent visual cues that players learn to read

When

Designing puzzle elements, creating new mechanics

Example

From The Witness:

• Black = line must pass through
• White = line must not pass through
• Colored squares = separation rules
• Same symbol = same rule, ALWAYS

Once a player learns what a symbol means, it NEVER means something different. Trust is everything.

Practical visual language:

• Interactable objects glow/highlight
• Same color = same type (red buttons = danger, green = go)
• Consistent iconography (gear = settings everywhere)
• Shape language (round = friendly, sharp = danger)

Building visual vocabulary:

1. First appearance: Obvious, isolated, harmless "Here's a blue crystal. It glows when you approach."

2. Second appearance: Simple function "Blue crystal powers this door."

3. Third appearance: Player recognizes instantly "I see blue crystals--I know what they do."

The rule:

If something looks the same, it works the same. If it works differently, it must look different.

---

Name

Undo Without Punishment

Description

Let players experiment freely without harsh consequences

When

Designing puzzle reset mechanisms, handling failure states

Example

The principle:

Puzzles are about thinking, not execution. Punishing wrong attempts discourages experimentation. Experimentation is how players learn.

Implementation:

Instant reset

• Button press resets puzzle state immediately
• No "are you sure?" for quick resets
• Maintain player position if possible (don't make them walk back)

Partial undo

• Step back one move at a time
• Shows cause and effect clearly
• Braid's time rewind: any action can be undone

Soft failure

• "Wrong" doesn't mean "dead"
• Puzzle resets, not the whole level
• No loading screens for puzzle failures

Checkpoint generosity

• Save after each solved puzzle
• Let players leave and return
• Remember partial progress where logical

The anti-pattern:

• Death from puzzle failure (requires level restart)
• Long animations before retry
• Resetting unrelated progress
• "Gotcha" puzzles with hidden death

Remember:

The player should fear being stuck, not being dead.

---

Name

Parallel Puzzle Paths

Description

Offer multiple puzzles so players can unstick themselves

When

Designing puzzle progression, preventing hard blocks

Example

The problem with linear puzzles:

One stuck puzzle = stuck player = rage quit

The solution:

Hub structure

Central area with 3-5 puzzles accessible Player chooses which to attempt Solving any advances the game

Branching paths

Main path splits into A and B Both reconverge later Player needs to solve ONE, not both (They'll come back for the other)

Side content

Optional puzzles for extra rewards Harder than main path (for enthusiasts) Never required--always optional

The Witness approach:

11 areas, each with 7+ puzzles Solving ~80% of any area counts Stuck on one? Do another.

Escape room approach:

3 puzzles running simultaneously Each gives piece of final puzzle Team naturally splits by interest/skill

Key insight:

Players have different puzzle strengths. Some excel at logic, others at spatial. Parallel paths let them play to strengths while building skills in weak areas.

---

Name

Teaching and Testing Separation

Description

Never test a mechanic in the same puzzle where you teach it

When

Designing puzzle difficulty, pacing tutorial sections

Example

WRONG: Teach and test simultaneously

First puzzle with new mechanic:

• Introduces light redirection
• Requires precise timing
• Enemies present
• Can die and restart

Player doesn't know if they failed because:

• They don't understand redirection
• Their timing was off
• Enemies distracted them
• Something else entirely

RIGHT: Separated teaching and testing

Teaching puzzle (cannot fail):

"Redirect this beam to the target."

• Only one thing to do
• Beam is already almost pointed right
• Target lights up on success
• No time pressure, no enemies, no death

Practice puzzle (low stakes):

"Redirect beam, but now target is farther."

• Same mechanic, slightly harder
• Still no pressure
• Player gets comfortable

Testing puzzle (real challenge):

"Redirect multiple beams under time pressure."

• Now we add complexity
• Player already knows mechanic
• Challenge comes from application, not learning

The guideline:

Teaching puzzles: Players learn mechanics Testing puzzles: Players apply mechanics Never both at once.

---

Name

Progressive Hint System

Description

Hints that nudge toward discovery rather than revealing solutions

When

Designing hint mechanics, help systems

Example

Hint levels (escape room industry standard):

Level 1: Confirmation of direction

"You're on the right track with the symbols."

• Validates player's current approach
• Doesn't reveal anything new
• Reduces second-guessing

Level 2: Focus attention

"Have you noticed anything about the paintings?"

• Points to relevant area/element
• Doesn't explain what to do
• Player still has "aha" moment

Level 3: Partial solution

"The first symbol is related to the sun painting."

• Reveals one piece of the answer
• Demonstrates the logic pattern
• Player applies pattern to rest

Level 4: Full solution (emergency only)

"The code is sun-moon-star based on the paintings."

• Complete answer
• Used only to prevent rage-quit
• Should feel like last resort

Implementation:

• Timed hints: Offer after N minutes stuck
• Requested hints: Player asks for help
• Environmental hints: Subtle clues in world
• NPC hints: Characters observe and comment

The goal:

Player should feel they solved it, even with hints. Best hints make player say "Oh! I should have seen that!" not "Okay, now I know the answer."

---

Name

The Funnel

Description

Start wide, narrow to solution, like Portal's puzzle design

When

Designing puzzle spaces, guiding player attention

Example

Portal's genius: Physical space guides mental space

Wide entrance

Player enters large room Many things to look at Seems overwhelming at first

Natural focus

Room shape guides eye Key elements more prominent Distractions eliminated gradually

Narrow solution

By the time player reaches solution area, they've naturally noticed the key elements Solution feels discoverable, not hidden

Practical application:

Visual funnel:

• Brighter lighting on important elements
• Lines in environment point toward solution
• Color coding groups related elements
• Empty space draws attention to contents

Cognitive funnel:

• Early experiments rule out wrong approaches
• Failed attempts teach something useful
• Each attempt narrows possibility space
• Solution emerges from elimination

Physical funnel (escape rooms):

• Arrange elements so discoveries lead to next clue
• Physical path guides logical path
• Reveal elements in designed order
• Natural flow from puzzle to puzzle

---

Name

Puzzle Dependency Mapping

Description

Design which puzzles unlock which, avoiding frustration

When

Ordering puzzles, designing game flow

Example

The dependency graph:

Puzzle A (teaches mechanic 1) ↓ Puzzle B (uses mechanic 1) ↓ Puzzle C (teaches mechanic 2) ↓ Puzzle D (combines mechanics 1 + 2)

Rules for dependencies:

1. No hidden prerequisites

If puzzle D requires knowledge from puzzle B, puzzle B must be required before D. Don't assume player did optional content.

2. Recognize skill progression

Puzzle B should be easier than puzzle C if solving B is required for C. Don't gate behind harder content.

3. Provide parallel branches

A → B → D A → C → D Player can do B OR C first. Unsticking path always available.

4. Clear gating

Locked door clearly requires key. Player knows what they're looking for. No invisible dependencies.

Escape room approach:

Map puzzles to a graph before building Identify critical path (minimum solves to win) Ensure no bottleneck depends on single puzzle Playtest the dependency order explicitly

---

Name

Physical vs Logic vs Meta Puzzles

Description

Different puzzle types require different design approaches

When

Choosing puzzle types, ensuring variety

Example

Physical puzzles (execution-based):

• Pushing blocks
• Timing jumps
• Aiming projectiles

Design considerations:

• Skill floor: Everyone should be able to attempt
• Skill ceiling: Masters can do it faster/cleaner
• Undo: Must be easy to reset
• Accessibility: Consider motor impairments

Example: Portal 2's gel puzzles

Logic puzzles (deduction-based):

• Sudoku-style
• Pattern recognition
• Sequence puzzles

Design considerations:

• All information available (no hidden data)
• Deducible, not guessable
• Working backwards should verify solution
• Paper test: Can player solve on paper?

Example: The Witness's line puzzles

Meta puzzles (rule-changing):

• Mechanics that change meaning
• Puzzles about the puzzle
• Breaking the fourth wall

Design considerations:

• Establish normal rules first
• Subversion must be learnable
• Don't invalidate earlier learning
• The twist should feel fair in hindsight

Example: Baba Is You's rule manipulation

Mix for variety:

A great puzzle game uses all three, paced to prevent fatigue. Logic heavy? Add physical break. Execution section? Follow with observation puzzle.

---

Name

The Inevitable Solution

Description

Solutions should feel like the only possible answer in hindsight

When

Designing solutions, testing for fairness

Example

From Jonathan Blow (The Witness):

"A puzzle is not about hiding the solution. It's about hiding the PATH to the solution."

The test of inevitability:

After solving, player should feel: "Of course! It couldn't be anything else!" NOT: "I guess that works too."

Designing for inevitability:

1. Single solution (often)

Multiple solutions dilute the "aha" One elegant solution feels more satisfying Exception: Multiple valid approaches to same answer

2. Clean logic

Each step follows from previous No leaps of faith required No "try everything until something works"

3. Foreshadowing

The solution elements are visible from start Player has seen everything they need Nothing hidden, just unrecognized

4. Verification

Solving should confirm understanding "I see why this works, not just that it works" The mechanism is now understood

The escape room standard:

If 80% of teams solve it the same way, it's a good puzzle. If teams stumble onto it randomly, it's a bad puzzle.

Anti-Patterns

---

Name

Moon Logic

Description

Solutions that only make sense in the designer's head

Why

Classic adventure game failure. "Use rubber chicken with pulley to cross ravine." Players can't deduce the solution. They resort to trying everything with everything. The "aha" becomes "what the hell" and trust in the game is destroyed.

Instead

Every solution must be deducible from available information. Test by asking: "What would a reasonable person try?" If your solution isn't in their top 5 attempts, redesign.

---

Name

Pixel Hunting

Description

Critical puzzle elements hidden or too small to notice

Why

Not testing observation--testing patience. Players scan every pixel desperately. When they find the hidden thing, they feel stupid, not smart. The puzzle was about finding the puzzle, not solving it.

Instead

Important elements should be noticeable. Use visual hierarchy. Puzzle is about figuring out what to DO, not what to SEE. Test by asking: "Did playtesters notice this element?"

---

Name

Required Outside Knowledge

Description

Puzzles requiring knowledge not provided in the game

Why

"You need to know Morse code to solve this." "The clue references a 1970s movie." Not everyone knows these things. Not fair. Not fun. The player who happens to know something feels lucky, not clever.

Instead

Teach everything needed within the game. If Morse code is required, a Morse chart is visible nearby. Cultural references are decoration, never required.

---

Name

Guess the Verb

Description

Player knows what to do but not how to express it

Why

"I need to break the window." Tries punch, hit, smash, attack, throw, kick... Game only accepts "BREAK WINDOW WITH ROCK" Failure of interface, not puzzle design.

Instead

Limited, clear interaction vocabulary. If something can be broken, one "break" action works. Visual feedback for "almost right" attempts.

---

Name

Difficulty Spikes

Description

Sudden jumps in difficulty without progression

Why

Puzzles 1-5 are easy. Puzzle 6 is brutally hard. Player hasn't developed skills needed. Feels like punishment, not challenge.

Instead

Graph your difficulty curve. Every puzzle slightly harder than last. Test by solving in order--does each feel like natural next step? Hard puzzles should be optional or have hints available.

---

Name

Teaching While Testing

Description

First encounter with mechanic is also the hard puzzle

Why

Player fails. Was it because they don't understand the mechanic? Or because the puzzle was hard? They can't tell. Frustration comes from not knowing what you don't know.

Instead

Teaching puzzles: Can't fail, learn mechanic Testing puzzles: Apply known mechanic under pressure Never combine first introduction with real challenge.

---

Name

Punishment for Experimentation

Description

Wrong attempts result in death, long resets, or lost progress

Why

Puzzles are solved through experimentation. If wrong guesses are punished, players stop experimenting. They look up solutions instead of playing.

Instead

Quick reset. No death. Minimal setback. Wrong attempts teach something useful. Make failure a learning moment, not a punishment.

---

Name

Linear Puzzle Blocking

Description

Single puzzle blocks all progress

Why

One puzzle player can't solve = entire game stuck. Different players struggle with different puzzle types. Rage quit is often the result.

Instead

Multiple puzzles available at once. Skip mechanic (with optional penalty). Hint system that actually helps. Parallel paths through content.

---

Name

The Unfair Gotcha

Description

Puzzle that tricks player with withheld information

Why

"Ha! The floor was a pressure plate the whole time!" Player couldn't have known. Didn't solve it--fell into it. Feels like the game cheated, not like clever design.

Instead

Foreshadowing, not hiding. The floor WAS visible as a pressure plate. Player should smack forehead: "I should have seen that!"

---

Name

Timer Anxiety

Description

Time pressure on puzzles that require thinking

Why

Puzzles require thought. Time pressure prevents thought. Player rushes, makes mistakes, feels stupid. Stress replaces the satisfaction of solving.

Instead

If time matters, make it visible and generous. Pause timer during "aha" moments. Or: Remove timer entirely from think-heavy puzzles. Save time pressure for execution puzzles.

Puzzle Design - Sharp Edges

Puzzle The Curse Of Knowledge

Id

puzzle-the-curse-of-knowledge

Summary

Designer can't unsee the solution they created

Severity

critical

Situation

You design a puzzle, test it yourself, and think it's fine

Why

You KNOW the solution. You can't unknow it. Every element screams "obvious" to you because you put it there. Players see a room of possibilities. You see a solved puzzle. This blindness ruins more puzzles than any other mistake.

Jonathan Blow spent years on The Witness and STILL couldn't predict what players would find hard. Every puzzle designer faces this fundamental problem.

Solution

Fresh eyes are your only salvation

The playtesting imperative:

• Test with people who've never seen the puzzle
• Watch them solve it (don't play for them)
• Note where they get stuck
• Ask what they were thinking when stuck
• Resist the urge to "help" them

Multiple playtesters required:

First tester: Finds obvious problems Second tester: Confirms problems weren't flukes Third+ testers: Reveals patterns in confusion

The "explain it" test:

After they solve (or give up), explain the solution. Their reaction tells you everything:

• "Oh, that makes sense!" = Fair puzzle, needed tuning
• "How was I supposed to know that?" = Unfair puzzle, redesign

Structured observation:

Record time to solve Record number of wrong attempts Record verbal expressions of frustration This data is more valuable than opinions

The humbling truth:

If playtesters struggle, the puzzle is wrong. Not the playtesters. The puzzle.

Symptoms

• Playtesters struggle where you thought it was obvious
• You catch yourself saying "just look at..."
• Solution requires noticing what you highlighted
• Puzzle feels easy because you designed it

Detection Pattern

Puzzle Unclear Goal State

Id

puzzle-unclear-goal-state

Summary

Player doesn't know what "solved" looks like

Severity

critical

Situation

Player has tools but doesn't know what they're trying to achieve

Why

"Hmm, I can push blocks and flip switches. But... what am I trying to DO?"

Without clear goal state, players have no way to work backwards. They can't evaluate if attempts are getting closer. Random experimentation replaces logical deduction. Frustration follows confusion.

Solution

Make the goal visible and obvious

Physical clarity:

• Door that needs opening is visible
• Target location is marked
• "Success" state shown or demonstrated
• Before/after comparison possible

The Zelda method:

Show the treasure chest behind bars. Player knows: "I need to get that chest." Now they're solving, not wandering.

The Portal method:

Exit door is always visible from start. Getting there is the puzzle. Goal is never ambiguous.

Test for goal clarity:

Ask playtester after 10 seconds: "What are you trying to do?" If they can't answer clearly, goal isn't clear.

Exception: Meta puzzles

Some puzzles ARE about figuring out the goal. These need special care--goal discovery is the puzzle. But even here, player needs to know that's the puzzle.

Symptoms

• Players ask "What am I supposed to do?"
• Random experimentation without direction
• Solving by accident without understanding
• Players walk past the solution repeatedly

Detection Pattern

Puzzle Invisible Interactions

Id

puzzle-invisible-interactions

Summary

Interactable elements don't look interactable

Severity

critical

Situation

Key puzzle element blends into background or lacks visual feedback

Why

Players have learned visual language: glowing = interactive, dull = scenery. If your important lever looks like a random pipe, they won't try it. The puzzle wasn't hard. It was invisible.

Worse: they might find it eventually by pixel-hunting. Now they'll pixel-hunt EVERYTHING. Gameplay becomes frustrating scanning.

Solution

Visual hierarchy of interactivity

Immediately obvious:

• Different color from environment
• Glow, shimmer, or particle effect
• Unique shape language (round = interactive, sharp = hazard)
• Animation draws eye (subtle movement)

Consistent visual language:

• All buttons look like buttons
• All levers look like levers
• Learned visual vocabulary persists

Feedback confirms interactivity:

• Hover state shows "I can interact"
• Near interaction range shows prompt
• Sound confirms action registered

The contrast test:

Screenshot your puzzle, blur it heavily. Can you still identify interactive elements? They should stand out even blurred.

Escape room lesson:

Physical escape rooms use: color, material, positioning, lighting The "puzzle" is never finding the puzzle elements. It's figuring out how they connect.

Symptoms

• Players miss key elements entirely
• Stuck players found solution after hint "try the bookshelf"
• Interactive elements same visual weight as decoration
• Players resort to clicking everything

Detection Pattern

Puzzle Broken Causality

Id

puzzle-broken-causality

Summary

Actions don't have visible, logical effects

Severity

high

Situation

Button pushed here affects something far away or invisible

Why

"I pushed a button. Something happened... somewhere. I don't know what."

Learning happens through cause and effect. If effects are invisible, players can't learn. They push buttons randomly hoping something works. When it works, they don't know why. No "aha" moment.

Solution

Make cause and effect crystal clear

Immediate feedback:

Button press → visible door opening Switch flip → lights change in view Block placement → connected element responds

Camera helps:

Brief camera pan to show effect Picture-in-picture of remote effect Audio cue from direction of effect

The chain principle:

A → B → C is fine if:

• Player sees A affects B
• Player sees B affects C
• Each link is individually clear

Portal's brilliance:

Portal in = portal out. You see both. Cause and effect are spatially connected. Learning is automatic.

Test question:

After any action, does player know what changed? If not, add feedback until they do.

Symptoms

• Players don't connect actions with results
• Confusion about what button did
• Solving by trial and error instead of deduction
• Players repeat same actions expecting different results

Detection Pattern

Puzzle Difficulty Spike

Id

puzzle-difficulty-spike

Summary

Sudden jump in difficulty breaks player flow

Severity

high

Situation

Easy puzzles → suddenly brutal puzzle → easier puzzles

Why

Player was cruising. Confidence building. Then WALL. Not a gradual increase--a cliff. They haven't built skills for this jump. Either they grind in frustration or quit entirely.

Often caused by designer blind spot: puzzle seems "medium" because they know tricks to solve it.

Solution

Smooth the difficulty curve

Measure difficulty empirically:

• Time to solve for playtesters
• Number of hints requested
• Frustration expressions observed
• Order them by actual difficulty, not assumed

Fill the gaps:

If puzzles are 1, 2, 3, 8, 4, 5... That 8 needs to move or needs bridge puzzles before it.

The witness method:

Jonathan Blow's difficulty ordering process:

• Create more puzzles than needed
• Test all puzzles with fresh players
• Order by actual measured difficulty
• Cut puzzles that create gaps

Escape room industry standard:

Difficulty should ramp: 20% easy, 60% medium, 20% hard Never start with hard End with satisfaction, not frustration

Red flags in playtesting:

• Sudden increase in solve time
• Players seeking hints on specific puzzle
• Players stopping entirely at specific puzzle
• Players describing puzzle as "unfair"

Symptoms

• One puzzle takes 10x longer than neighbors
• Players cite specific puzzle as rage-quit point
• Hints requested spike at certain puzzle
• Players describe sudden "wall"

Detection Pattern

Puzzle Too Many Red Herrings

Id

puzzle-too-many-red-herrings

Summary

Fake clues overwhelm real clues

Severity

high

Situation

Red herrings and decoration drown out actual puzzle elements

Why

"I spent 20 minutes on that painting. Turns out it was just decoration."

Red herrings can add depth. Too many create noise. Players can't tell signal from noise. Everything becomes suspicious. Nothing feels like a reliable clue.

Solution

Signal to noise ratio

The 1:1 maximum:

For every red herring, have at least one real clue. If players are drowning in false leads, cut red herrings.

Distinguish decoration from puzzles:

• Decoration: Consistent style, blends in, no highlights
• Puzzle elements: Visual distinction, interactive affordances

Red herring rules:

• Should be quickly dismissable with investigation
• Should not require extensive testing to rule out
• Should not be more interesting than real clues
• Should not be required to notice the real clue

Escape room wisdom:

Professionals have moved AWAY from red herrings. Modern best practice: Everything in the room matters. If it's in the puzzle space, it's part of a puzzle.

Testing for red herring overload:

If players spend time on non-puzzle elements, either make those elements puzzles or remove them.

Symptoms

• Players fixate on decorative elements
• High noise-to-signal ratio in player investigation
• Frustration when "obvious" clue was decoration
• Players distrust real clues thinking they're fake

Detection Pattern

Puzzle Information Outside Game

Id

puzzle-information-outside-game

Summary

Solution requires knowledge players may not have

Severity

high

Situation

Puzzle assumes knowledge of history, culture, or specialized domains

Why

"This puzzle requires knowing the NATO phonetic alphabet." "You need to recognize this painting from 1820." "The code is based on baseball statistics."

Some players know this. Most don't. Those who know feel lucky, not clever. Those who don't feel cheated, not challenged.

Solution

Self-contained puzzle worlds

The rule:

Every piece of information needed to solve the puzzle must be present within the game.

If specialized knowledge is required:

Provide it. Morse code chart on the wall. Reference book on the shelf. NPC who explains the history.

Cultural assumptions to avoid:

• Historical dates and events
• Religious or mythological references
• Pop culture from specific era/region
• Scientific notation or formulas
• Sports statistics
• Language-specific wordplay

The localization test:

Could this puzzle be solved by someone from a different culture with the information provided? If not, either change the puzzle or add the information.

Exception: Educational games

If teaching history IS the point, fine. But the game should teach it first, test it second.

Symptoms

• Solutions require knowledge not in game
• Success correlates with player background, not skill
• Certain player demographics consistently fail
• "I had to Google it" in playtester feedback

Detection Pattern

Puzzle Combinatorial Explosion

Id

puzzle-combinatorial-explosion

Summary

Too many possible combinations to try systematically

Severity

high

Situation

Puzzle with many dials, buttons, or options creates thousands of combinations

Why

4 dials with 10 positions each = 10,000 combinations. At 3 seconds each = 8+ hours of brute force. Players can't exhaustively try everything. But puzzle doesn't give enough clues to narrow it down. They either guess lucky or give up.

Solution

Design for deduction, not exhaustion

Constrain the possibility space:

• Each clue eliminates possibilities
• Working through clues narrows to single solution
• Brute force is unnecessary if logic is followed

The math check:

Calculate total combinations possible. Count clues that reduce possibilities. Result should be deterministic, not probabilistic.

Multi-lock principle:

Large combinations should be split. 10,000 possibilities → 4 puzzles of 10 each. Each sub-puzzle is solvable. Final combination is assembly of solved parts.

Feedback on partial correctness:

If 3 of 4 dials are right, indicate progress. "You're getting warmer" without "the answer is X." Mastermind-style feedback.

The brute force test:

If playtester starts trying random combinations, they don't understand the logic. Fix the logic, not them.

Symptoms

• Players try random combinations
• Correct by luck, not logic
• No clear path from clues to solution
• Solve time is random, not skill-based

Detection Pattern

Puzzle Softlock Trap

Id

puzzle-softlock-trap

Summary

Player can get into an unsolvable state without knowing

Severity

critical

Situation

Resource used up, item consumed, or state changed that makes puzzle unsolvable

Why

"Wait, I needed that key for THIS door? I used it on the other one."

Player is now stuck forever. They don't know they're stuck. They keep trying. Eventually realize. Have to restart. ALL progress lost. Trust destroyed. Game potentially uninstalled.

Solution

Eliminate softlock possibilities

The softlock test:

At every decision point, can the player still win? If any choice leads to unwinnable state, fix it.

Prevention strategies:

• Keys work on all valid doors (or return if used wrong)
• Consumables can be re-obtained
• State changes can be undone
• Resources respawn if depleted wrongly

If softlock is possible, warn:

Clear "point of no return" messaging Auto-save before irreversible choices "Are you sure?" for potentially locking actions

The save system protection:

Multiple auto-save slots Saves at puzzle start, not just checkpoint Player can backtrack to earlier saves

Testing requirement:

Playtesters should try to break the game. "What's the worst choice I could make here?" Every discovered softlock must be fixed.

Symptoms

• Players stuck but don't know why
• Required item missing with no way to get another
• Irreversible state change blocks progress
• "I have to start over" moments

Detection Pattern

Puzzle Solution Ambiguity

Id

puzzle-solution-ambiguity

Summary

Multiple interpretations of what constitutes the solution

Severity

medium

Situation

Player does something that should work but doesn't count

Why

"I did exactly what was asked! Why didn't it work?"

Player solved the puzzle their way. Game only accepts one way. Their solution was valid. Game invalidated their thinking. Feels arbitrary. Feels unfair. Trust broken.

Solution

Accept all valid solutions

Design for behavior, not sequence:

If the puzzle is "light all the torches," accept any order, any method.

Anticipate player creativity:

Players will find solutions you didn't expect. If it achieves the goal, accept it. If you don't want that solution, design it out.

The "clever player" test:

What would a creative player try? Would it work in real life? If yes, it should work in game.

Escape room lesson:

Physical rooms must accept physical solutions. "I solved it a different way" is valid if goal is met. Digital games should be equally flexible.

If single solution is required:

Make constraints crystal clear. "Connect the circuit using ONLY these paths." Unallowed approaches should be visibly impossible.

Symptoms

• Playtesters solve it "wrong" but logically
• Frustration at "arbitrary" restrictions
• Solution works in player's head but not in game
• Multiple valid interpretations of puzzle goal

Detection Pattern

Puzzle Unclear Feedback

Id

puzzle-unclear-feedback

Summary

Player can't tell if their solution attempt is wrong or incomplete

Severity

medium

Situation

Input accepted but no feedback on correctness until final step

Why

Player enters: 3-7-5-2 Answer is: 3-7-5-1 Game says: "Wrong."

Were they completely wrong? One digit off? Wrong format? They can't improve without feedback. Next attempt is a guess, not an improvement.

Solution

Feedback at every step

Immediate feedback options:

• Green/red per digit (if appropriate)
• "X correct, Y in wrong position" (Mastermind)
• "Getting warmer/colder" indicator
• Sound change as approaching solution

Progressive confirmation:

First step right → something clicks Second step right → something else responds Building toward final confirmation

The silent failure problem:

No feedback = no learning. Even "wrong" is better than nothing. Best is "wrong because X" or "X is right, Y is wrong."

Escape room practice:

Game masters provide "nudges" based on player state. Digital games need automated equivalent. Feedback system should feel like helpful GM.

Symptoms

• Players don't know why they failed
• Same wrong attempts repeated
• Frustration with opaque failure states
• Success feels random, not logical

Detection Pattern

Puzzle Timing On Thinking

Id

puzzle-timing-on-thinking

Summary

Time pressure applied to puzzles requiring contemplation

Severity

medium

Situation

Countdown timer on logic puzzle that needs careful thought

Why

Logic puzzles need thinking time. Timer creates anxiety. Anxiety blocks thinking. Player rushes, makes mistakes, fails. Failure came from timer, not puzzle difficulty.

They can't practice their logic faster. They can only solve correctly or solve rushed-wrong.

Solution

Right pressure for right puzzle type

Timing is for execution, not cognition:

• Time: Physical dexterity challenges
• Time: Reaction-based puzzles
• Time: After puzzle is understood

• No time: Logic deduction
• No time: Pattern recognition
• No time: First encounter with mechanic

If time matters, decouple thinking and execution:

"Here's the puzzle. Understand it." (No timer) "Now execute your solution." (Timer starts)

Pause-friendly design:

If timer must exist, allow pause. Pausing doesn't give advantage--thinking does. Let players think without pressure.

Escape room nuance:

60-minute rooms have time, but time is generous. Pressure is background motivation, not immediate stress. Panic kicks in only in final minutes, when most should be solved.

Symptoms

• Players fail from rushing, not misunderstanding
• Correct solutions entered wrong under pressure
• Timer anxiety prevents clear thinking
• Players remember stress, not fun

Detection Pattern

Puzzle Accessibility Oversight

Id

puzzle-accessibility-oversight

Summary

Puzzle design excludes players with disabilities

Severity

medium

Situation

Color-based puzzle unplayable for colorblind players

Why

~8% of men are colorblind. Pure red-green puzzle excludes them entirely. Hearing-impaired players miss audio-based puzzles. Motor-impaired players struggle with execution-heavy puzzles.

Accessibility isn't optional--it's part of good design.

Solution

Design for all players

Color puzzles:

• Never use color ONLY (add shapes, patterns, symbols)
• Test with colorblind simulator
• Provide colorblind mode with alternative visual language

Audio puzzles:

• Provide visual alternative (subtitles, visual meter)
• Audio cues should also have visual component
• Test with sound off--puzzle should still be solvable

Motor challenges:

• Provide assist options for timing-based puzzles
• Allow difficulty adjustment for execution
• Keyboard alternatives for mouse-required actions

Cognitive accessibility:

• Skip options for puzzles (with optional penalty)
• Hint system that actually helps
• No time pressure on thinking puzzles

The CVAA test:

Could a deaf person solve audio puzzles? Could a blind person solve with screen reader? Could motor-impaired person complete action puzzles? Build alternatives into design.

Symptoms

• Certain player groups can't complete specific puzzles
• No alternative solve paths for differently-abled
• Reliance on single sense or ability
• Complaints about accessibility from players

Detection Pattern

Puzzle Design - Validations

Missing Goal State Documentation

Id

puzzle-no-goal-documented

Severity

warning

Type

regex

Pattern

• (?i)puzzle\s(?:\d+|[a-z])?\s:(?![^:]*(?:goal|objective|win|success|complete))

Message

Puzzle documentation lacks clear goal state. Players must know what they're trying to achieve.

Fix Action

Add explicit goal state: 'Goal: Player must activate all four crystals to open the door'

Applies To

• *.md
• *.txt
• design.md
• puzzle.md

Missing Difficulty Rating

Id

puzzle-no-difficulty-rating

Severity

info

Type

regex

Pattern

• (?i)puzzle\s(?:\d+|[a-z])?\s:(?![^:]*(?:difficulty|easy|medium|hard|rating))

Message

Puzzle documentation lacks difficulty rating. Rate each puzzle for curve planning.

Fix Action

Add difficulty rating: 'Difficulty: Medium (estimated 3-5 minutes)'

Applies To

• design.md
• puzzle.md

Testing Before Teaching

Id

puzzle-missing-mechanic-intro

Severity

warning

Type

regex

Pattern

• (?i)(?:introduces?|first)\s+(?:and|,)\s+(?:tests?|challenges?)
• (?i)new\s+mechanic.*(?:difficult|hard|challenging)

Message

Puzzle may teach and test simultaneously. Introduce mechanics in low-stakes puzzles first.

Fix Action

Add introductory puzzle that teaches mechanic before testing it

Applies To

• design.md
• puzzle.md

Missing Puzzle Reset

Id

puzzle-no-reset-mechanism

Severity

warning

Type

regex

Pattern

• class\s+Puzzle(?![\\s\\S]reset\\s\\()
• puzzle\\.(?:start|begin|init)(?![\\s\\S]*puzzle\\.reset)

Message

Puzzle class has no reset mechanism. Players should be able to retry without punishment.

Fix Action

Add reset() method that returns puzzle to initial state

Applies To

• *.ts
• *.js
• *.gd
• *.cs

Death as Puzzle Failure

Id

puzzle-death-on-failure

Severity

warning

Type

regex

Pattern

• puzzle.(?:fail|wrong|incorrect).(?:die|death|kill|respawn)
• (?:die|death|kill).puzzle.(?:fail|wrong)

Message

Player dies on puzzle failure. Consider puzzle-only reset instead.

Fix Action

Reset puzzle state on failure instead of killing player

Applies To

• *.ts
• *.js
• *.gd
• *.cs

Color-Only Puzzle Element

Id

puzzle-color-only

Severity

warning

Type

regex

Pattern

• (?i)color\s===?\s"'
• (?i)if\s\(\s(?:\.color|getColor|tile\.color)
• (?i)switch\s\(\scolor\s*\)

Message

Color-based puzzle logic detected. Ensure alternative for colorblind players.

Fix Action

Add shape, pattern, or symbol alongside color differentiation

Applies To

• *.ts
• *.js
• *.gd
• *.cs

Hardcoded Puzzle Solution

Id

puzzle-hardcoded-solution

Severity

warning

Type

regex

Pattern

• solution\s=\s["'][a-zA-Z0-9]+["']
• password\s=\s["'][a-zA-Z0-9]+["']
• code\s===?\s["']\d+["']

Message

Hardcoded puzzle solution. Consider data-driven approach for easier testing.

Fix Action

Move solutions to config/data file for easier adjustment and playtesting

Applies To

• *.ts
• *.js
• *.gd
• *.cs

Missing Partial Feedback

Id

puzzle-no-partial-feedback

Severity

info

Type

regex

Pattern

• if\s\(.solution.===.\)\s\{[^}]success[^}]\}\selse\s\{[^}](?:fail|wrong|incorrect)

Message

Binary success/fail with no partial feedback. Consider showing progress hints.

Fix Action

Add partial feedback: 'X of Y correct' or 'getting warmer/colder'

Applies To

• *.ts
• *.js
• *.gd
• *.cs

Missing Attempt Tracking

Id

puzzle-unlimited-attempts

Severity

info

Type

regex

Pattern

• puzzle.submit(?![\\s\\S]attempts|[\\s\\S]*tries)

Message

No attempt tracking for puzzle. Consider tracking for adaptive hints.

Fix Action

Track attempts to trigger progressive hint system

Applies To

• *.ts
• *.js
• *.gd
• *.cs

Missing Playtest Data

Id

puzzle-no-playtest-data

Severity

warning

Type

regex

Pattern

• (?i)puzzle.complete(?)

Message

Puzzle marked complete without playtest data. Always test with fresh eyes.

Fix Action

Add playtest notes: solve time, hint usage, frustration points

Applies To

• design.md
• puzzle.md
• changelog.md

Single Playtester

Id

puzzle-single-tester

Severity

info

Type

regex

Pattern

• (?i)playtested?\s(?:by|with|:)\s(?:one|1|single)
• (?i)(?:one|1)\s*playtester

Message

Only one playtester. Multiple testers reveal patterns in player confusion.

Fix Action

Test with at least 3 fresh players to identify consistent issues

Applies To

• design.md
• playtest.md

Hint Reveals Full Solution

Id

puzzle-hint-spoils-solution

Severity

warning

Type

regex

Pattern

• hint.[=:].(?:solution|answer|code|password)
• showHint.*(?:solution|answer)

Message

Hint appears to reveal full solution. Use progressive hints that guide, not spoil.

Fix Action

Implement multi-level hints: direction → focus → partial → full (emergency only)

Applies To

• *.ts
• *.js
• *.gd
• *.cs
• hints.json

No Hint System

Id

puzzle-no-hint-system

Severity

info

Type

regex

Pattern

• class\s+Puzzle(?![\\s\\S]*hint)
• puzzle(?![\\s\\S]*(?:hint|help|assist))

Message

No hint system detected. Players need escape valve when stuck.

Fix Action

Implement hint system: time-based triggers or player-requested hints

Applies To

• *.ts
• *.js
• *.gd
• *.cs

Linear Puzzle Dependency

Id

puzzle-linear-dependency

Severity

info

Type

regex

Pattern

• requires.puzzle\s(?:\d+|[a-z])$
• unlock.after.puzzle\s*(?:\d+|[a-z])$

Message

Linear puzzle dependency. Consider parallel paths to prevent hard blocks.

Fix Action

Add alternative puzzles that unlock the same progress

Applies To

• design.md
• config.json
• progression.json

No Skip Mechanism

Id

puzzle-no-skip-option

Severity

info

Type

regex

Pattern

• (?i)required.puzzle(?)
• mustComplete.*puzzle

Message

Required puzzle with no skip option. Consider skip with optional penalty.

Fix Action

Add skip option: time penalty, currency cost, or accessibility setting

Applies To

• design.md
• config.json

Audio-Only Puzzle Cue

Id

puzzle-audio-only-cue

Severity

warning

Type

regex

Pattern

• (?i)(?:listen|audio|sound).(?:for|to).(?:clue|hint|solution)
• (?i)puzzle.(?:requires?|needs?).(?:audio|sound|listen)

Message

Audio-only puzzle element. Provide visual alternative for deaf/hard-of-hearing players.

Fix Action

Add visual indicator that mirrors audio cue

Applies To

• design.md
• *.ts
• *.js
• *.gd
• *.cs

Timing-Critical Without Assist

Id

puzzle-timing-critical

Severity

info

Type

regex

Pattern

• (?i)(?:time|timing|timed|timer).*(?:critical|required|must)
• (?i)(?:must|need|require).within.(?:seconds?|milliseconds?)

Message

Timing-critical puzzle element. Consider assist mode for motor-impaired players.

Fix Action

Add accessibility option to extend time windows or skip timing requirements

Applies To

• design.md
• *.ts
• *.js

Large Combination Space

Id

puzzle-large-combination

Severity

warning

Type

regex

Pattern

• (?i)(?:dial|switch|button)s?\s[:=]\s[5-9]|1[0-9]
• (?i)(?:options?|positions?|states?)\s[:=]\s[5-9]|1[0-9]

Message

Large combination space (5+ options). Ensure clues sufficiently narrow possibilities.

Fix Action

Verify: Can player deduce answer without brute force? Add constraining clues.

Applies To

• design.md
• puzzle.md

Random Puzzle Generation

Id

puzzle-random-generation

Severity

info

Type

regex

Pattern

• random.*puzzle
• generatePuzzle.*Math\.random
• shuffle.*puzzle

Message

Randomly generated puzzle. Ensure generated puzzles are always solvable and fair.

Fix Action

Add validation: all generated puzzles must pass solvability check

Applies To

• *.ts
• *.js
• *.gd
• *.cs

Consumable Required for Puzzle

Id

puzzle-consumable-required

Severity

warning

Type

regex

Pattern

• (?i)(?:consume|use\s+up|destroy).(?:key|item).puzzle
• (?i)puzzle.(?:requires?|needs?).(?:consumable|one-time)

Message

Consumable item required for puzzle. Ensure item can be re-obtained if used wrong.

Fix Action

Add respawn mechanism or alternative path if consumable is used incorrectly

Applies To

• design.md
• *.ts
• *.js

Irreversible State Change

Id

puzzle-irreversible-state

Severity

warning

Type

regex

Pattern

• (?i)permanent|irreversible|(?:can'?t|cannot)\s+undo
• (?i)puzzle.(?:destroy|break).(?:can'?t|cannot)\s+(?:restore|reset)

Message

Irreversible state change in puzzle. Verify this cannot softlock the player.

Fix Action

Add auto-save before irreversible actions or provide reset mechanism

Applies To

• design.md
• *.ts
• *.js
• *.gd
• *.cs