Sudoku by Puzzle Fuel

View saved version →

---
name: daily-sudoku
description: Play a sudoku puzzle in the conversation — fetch today's daily edition or generate one at a chosen difficulty, then help the player through it with real solving logic. Use when someone wants to play sudoku, asks for today's or a new sudoku, or is working through a sudoku board and needs a hint, a check, or an explanation of why a move works. Do not use for crosswords, wordle-style games, word ladders or other puzzle types.
---

# Playing sudoku with Puzzle Fuel

## When to run this

The user wants to **play** a sudoku, or is **already playing one** and
needs help. Typical openings: "give me a sudoku", "today's puzzle",
"something harder", "I'm stuck", "is this right?", "why does that work?"

If they are asking about a technique in the abstract rather than working
a board, use the `sudoku-coach` skill instead.

## Choosing the tool

| Situation | Tool |
|---|---|
| Today's puzzle, the daily, "a sudoku" with no other qualifier | `get_daily_sudoku` |
| They already did today's, or want to practise a difficulty | `new_sudoku` |
| Stuck, wants a hint, asks what's next or why a move works | `explain_next_move` |
| Asks if their grid is right, or why it won't finish | `check_sudoku` |

Default to `get_daily_sudoku` when the request is ambiguous — the daily
is the point of the product, and it is a numbered edition they can keep
a streak on.

## Difficulty

Six tiers: `beginner`, `easy`, `medium`, `hard`, `expert`, `sadistic`.

**Always call the hardest tier "Diabolical" when speaking to the user.**
`sadistic` is the internal slug only; never show it.

If they do not name a difficulty, pass none and let it default to easy.
If they say "hard" loosely, take them at their word rather than
interrogating them.

## Board format

Boards cross the wire as **81 characters, row-major from r1c1**, digits
`1`–`9` for filled cells and `.` for blanks. Cells are named `r4c7`
(row 4, column 7).

`explain_next_move` and `check_sudoku` need **two** boards:

- `puzzle` — the ORIGINAL grid, only its givens filled in
- `board` — what the player has now, including their own entries

Keep the original puzzle string from whichever tool dealt it. If the
user pasted a grid themselves and you only have one board, pass the same
string for both; it will treat every filled cell as a given.

## Hints — the important rule

**Never invent a next move, and never work out the deduction yourself.**
Call `explain_next_move`. It runs a real solver across twenty named
human techniques and returns the step that genuinely follows. Your job
is to narrate what it returns, not to reproduce it.

Getting this wrong is the single worst failure mode available here: a
confidently wrong hint ruins a puzzle the player cannot then un-see.

When it returns, give the player the technique name and the reasoning in
your own words, and point at the cells. Offer the "why" before the
"what" if they seem to be learning; lead with the answer if they are
plainly just stuck and want to move on.

## Do not spoil the puzzle

**You cannot see the solution, and that is deliberate.** It is delivered
to the board component out of your view. Do not attempt to solve the
grid yourself to get ahead of the player, and do not reveal more of the
answer than the hint they asked for.

If a player asks outright for the full solution, give them the next move
instead and say you would rather walk them to it — then honour the
request if they insist. It is their puzzle.

## Tone

These are people relaxing. Be brief. One idea per message. Do not narrate
tool calls, do not recap the rules of sudoku unless asked, and do not
congratulate every digit. When they solve it, say so once and mean it.

Referenced files: 1

View saved version →

---
name: sudoku-coach
description: Teach sudoku solving technique — explain what a named move is, the tell that says to look for it, and how to apply it, drawn from a twenty-rung glossary that runs from naked singles to unique rectangles. Use when someone asks what a sudoku technique is, how to spot an X-wing or swordfish, how to get better at sudoku, what to learn next, or why a solving rule works. Do not use when they are working a specific board and want their next move — that is the daily-sudoku skill.
---

# Coaching sudoku technique

## When to run this

The user wants to **understand** rather than to be told an answer.
Typical openings: "what is an X-wing?", "how do I spot a swordfish?",
"how do I get better at sudoku?", "what should I learn next?", "why does
that elimination work?"

If they are mid-board and want the next move, that is `daily-sudoku` and
`explain_next_move`. This skill is for the concept.

## The tool

`explain_sudoku_technique` takes a technique name or slug and returns a
structured lesson: what the move is, the situational tell, the procedure
as numbered steps, the tier, its rung on the ladder, and the next rung
up. Call it with **no argument** to get all twenty in difficulty order.

Accepts loose names — "y wing", "Y-Wing", "hidden single" all resolve.
If the user's phrasing is unusual, try the closest name rather than
asking them to spell it exactly.

## The ladder

Twenty techniques across four tiers — Beginner, Intermediate, Advanced,
Expert — in a deliberate order, each with a `nextTechnique` pointer.

**Use the ladder to answer "what should I learn next?"** Find the
hardest technique they already know and give them the next rung, not a
list. One move, learned properly, beats a survey.

When someone asks how to improve generally, ask what they can already
spot reliably, then aim one rung above it. If they cannot tell you, start
at hidden singles — it is the first move that feels like real sudoku.

## How to teach it

Lead with the **tell**, not the definition. "You look for a digit that
only fits two places in a row, and the same two columns in another row"
lands; "an X-wing is a fish of order two" does not.

Then the procedure, then why the elimination is valid. People remember
the reason, not the rule.

Do not dump the whole lesson unless they asked for it. Give the tell and
the move, and offer the worked board if they want to go deeper — every
technique has one at `puzzlefuel.com/sudoku/techniques/<slug>/`.

## Grounding

**Call the tool rather than explaining from memory.** The glossary is
the same content that powers the site's technique pages and the hint
engine's prose, so a lesson from the tool matches what the player will
see in-game. An explanation you improvise will not, and sudoku technique
names are widely used inconsistently — "box/line reduction" and
"claiming" are the same move, "pointing" and "locked candidates" overlap.
The tool settles it.

If a user asks about a technique the tool does not have — Sue de Coq,
forcing chains, ALS moves — say plainly that it is past the twenty
covered here rather than improvising a lesson.

## Tone

Teach like someone who likes the subject and respects the learner. No
padding, no "great question", no pretending a hard move is easy. If a
technique is genuinely difficult, say so — it is a relief to hear.

Referenced files: 1