skills/questforge-puzzles/SKILL.md

---
name: questforge-puzzles
description: Design and run Questforge puzzle beats, clue connections, symbolic minigames, route logic, social contradictions, and non-blocking deductions.
---

# Questforge Puzzles

Use this skill when a Questforge scene would benefit from a small deduction
beat, symbolic interaction, minigame, clue connection, or player-facing
reasoning challenge.

## Purpose

Add moments where the player connects facts, reads symbols, chooses a route,
spots a contradiction, or applies earlier lore. The goal is delight and agency,
not a hard lock.

Use `../../templates/puzzle-beat-prompt.md` and record prepared or used beats in
`dm/puzzle-ledger.md`. Use `../../scripts/puzzle_beats.py` when a compact,
repeatable draft or validation pass is useful.

## Good Puzzle Beats

Prefer:

- connecting two or three clues the player actually encountered;
- deciding between meaningful options with visible consequences;
- using inventory, NPC wording, faction symbols, maps, bells, oaths, or repeated
  motifs;
- revealing character, theme, or faction logic through the interaction;
- rewarding partial insight with progress plus complication.

Avoid:

- exact-word riddles;
- math busywork;
- one-answer locks with no alternate route;
- puzzles that require remembering a detail never emphasized;
- repeated puzzle formats in the same session.

## Table Flow

1. State the immediate situation and why it matters.
2. Remind the player of relevant clues naturally, not as an answer key.
3. Ask one concrete question.
4. Accept plausible reasoning; do not require exact phrasing.
5. If the player struggles, offer a hint that points to one prior clue.
6. After two wrong attempts, a hint request, or visible fatigue, use the
   fallback and keep play moving.
7. Record the result, reward, cost, and any new clue in campaign memory.

## Frequency

Use puzzle beats sparingly: roughly one meaningful deduction beat every few
scenes, or one larger puzzle per short adventure chapter. Skip them during high
urgency unless the puzzle is the urgent action.

## Rewards

Reward solved or partially solved beats with one or more of:

- safer route;
- better position;
- reduced DC;
- useful clue;
- NPC trust or leverage;
- avoided alarm;
- XP for meaningful progress;
- thematic revelation.

On bypass or failure, still move forward with a cost: time, noise, reduced
reward, resource loss, clue degradation, faction clock advance, or a harder
choice.