add-puzzle-type

Files (1)

• SKILL.md

SKILL.md (first lines)

# Add Puzzle Type

Scaffold a new puzzle type across all pipeline integration points in jigsawR.

## When to Use

- Adding a completely new puzzle type to the package
- Following the established integration checklist (CLAUDE.md 10-point pipeline)
- Ensuring nothing is missed when wiring a new type end-to-end

## Inputs

- **Required**: New type name (lowercase, e.g. `"triangular"`)
- **Required**: Geometry description (how pieces are shaped/arranged)
- **Required**: Whether the type needs external packages (add to Suggests)
- **Optional**: Parameter list beyond the standard (grid, size, seed, tabsize, offset)
- **Optional**: Reference implementation or algorithm source

## Procedure

### Step 1: Create Core Puzzle Module

Create `R/<type>_puzzle.R` with the internal generation function:

```r
#' Generate <type> puzzle pieces (internal)
#' @noRd
generate_<type>_pieces_internal <- function(params, seed) {
  # 1. Initialize RNG state
  # 2. Generate piece geometries
  # 3. Build edge paths (SVG path data)
  # 4. Compute adjacency
  # 5. Return list: pieces, edges, adjacency, metadata
}
```

Follow the pattern in `R/voronoi_puzzle.R` or `R/snic_puzzle.R` for structure.

**Got:** Function returns a list with `$pieces`, `$edges`, `$adjacency`, `$metadata`.

**If fail:** Compare the return structure against `generate_voronoi_pieces_internal()` to identify missing list elements or incorrect types.

### Step 2: Wire into jigsawR_clean.R

Edit `R/jigsawR_clean.R`:

1. Add `"<type>"` to the `valid_types` vector
2. Add type-specific parameter extraction in the params section
3. Add validation logic for type-specific constraints
4. Add filename prefix mapping (e.g., `"<type>"` -> `"<type>_"`)

```r
# In valid_types
valid_types <- c("rectangular", "hexagonal", "concentric", "voronoi", "snic", "<type>")
```

**Got:** `generate_puzzle(type = "<type>")` is accepted without "unknown type" error.

**If fail:** Verify the type string is added to `valid_types` exactly as spelled, and that parameter extraction covers all required type-specific arguments.

### Step 3: Wire into unified_piece_generation.R

Edit `R/unified_piece_generation.R`:

1. Add dispatch case in `generate_pieces_internal()`
2. Add fusion handling if the type supports PILES notation

```r
# In the switch/dispatch
"<type>" = generate_<type>_pieces_internal(params, seed)
```

**Got:** Pieces are generated when the type is dispatched.

**If fail:** Confirm the dispatch case string matches the type name exactly and that `generate_<type>_pieces_internal` is defined and exported from the puzzle module.

### Step 4: Wire into piece_positioning.R

Edit `R/piece_positioning.R`:

Add positioning dispatch for the new type. Most types use shared positioning logic, but some need custom handling.

**Got:** `apply_piece_positioning()` handles the new type without errors and pieces are placed at correct coordinates.

**If fail:** Check whether the new type needs custom positioning logic or can reuse the shared positioning path. Add a dispatch case if the default path does not apply.

### Step 5: Wire into unified_renderer.R

Edit `R/unified_renderer.R`:

1. Add rendering case in `render_puzzle_svg()`
2. Add edge path function: `get_<type>_edge_paths()`
3. Add piece name function: `get_<type>_piece_name()`

**Got:** SVG output is generated for the new type with correct piece outlines and edge paths.

**If fail:** Verify `get_<type>_edge_paths()` returns valid SVG path data and `get_<type>_piece_name()` produces unique identifiers for each piece.

### Step 6: Wire into adjacency_api.R

Edit `R/adjacency_api.R`:

Add neighbor dispatch so `get_neighbors()` and `get_adjacency()` work for the new type.

**Got:** `get_neighbors(result, piece_id)` returns correct neighbors for any piece in the puzzle.

**If fail:** Check that the adjacency dispatch returns the correct data structure. Test with a small grid and manually verify neighbor relationships against the geometry.

### Step 7: Add ggpuzzle Geom Layer

Edit `R/geom_puzzle.R`:

Create `geom_puzzle_<type>()` using the `make_puzzle_layer()` factory:

```r
#' @export
geom_puzzle_<type> <- function(mapping = NULL, data = NULL, ...) {
  make_puzzle_layer(type = "<type>", mapping = mapping, data = data, ...)
}

From pjt222/agent-almanac, MIT.

More from pjt222/agent-almanac