# Bfs State Space

> Model minimum-move problems as BFS over a state space. Use when solving bucket pouring puzzles, sliding tiles, or any problem asking for the shortest sequence of moves to reach a goal.

- Skill: `knoopx/bfs-state-space` (Agent Skill)
- Install (CLI): `npx skillmds@latest add knoopx/bfs-state-space`
- Raw SKILL.md: https://api.skillmd.com/api/skills/knoopx/bfs-state-space/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: knoopx (https://skillmd.com/u/knoopx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/knoopx/bfs-state-space

---


## When to use

When a problem asks for the MINIMUM number of moves/steps to reach a goal state (bucket pouring, puzzle solving, sliding tiles), model it as BFS over a state space.

## Rules

- State = a tuple of all values that fully describe the situation (e.g. (bucket_a, bucket_b))
- From each state, enumerate every legal transition and produce the next state
- Use a visited set keyed on the state tuple to avoid cycles
- BFS from the start state; the first time you pop a state matching the goal, its distance is the minimum move count
- Track which bucket holds the goal and the other bucket's value at that point
- NEVER skip the visited check — cycles will cause infinite loops
- ALWAYS encode forbidden moves as filters on transitions, not as special cases

## Example

Transitions for bucket pouring: fill A, fill B, empty A, empty B, pour A→B, pour B→A.

## Edge cases

If start_bucket is forbidden as an immediate "fill the wrong one first" move, encode that as a filter on the initial transitions.

## Example

Bucket pouring: state = (a, b). Transitions: fill A, fill B, empty A, empty B, pour A→B, pour B→A. BFS from (0, 0); first time a state has a goal value, that distance is the minimum.