validate-piles-notation
Parse and validate PILES (Puzzle Input Line Entry System) notation for specifying piece fusion groups in jigsawR. Covers syntax validation, parsing into group lists, plain-language explanation, adjacency verification against puzzle results, and round-trip serialization. Use when validating user-supplied PILES strings before passing to generate_puzzle(), debugging fusion group issues, explaining the notation to users, or testing round-trip parse/serialize fidelity.
Best use case
validate-piles-notation is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Parse and validate PILES (Puzzle Input Line Entry System) notation for specifying piece fusion groups in jigsawR. Covers syntax validation, parsing into group lists, plain-language explanation, adjacency verification against puzzle results, and round-trip serialization. Use when validating user-supplied PILES strings before passing to generate_puzzle(), debugging fusion group issues, explaining the notation to users, or testing round-trip parse/serialize fidelity.
Teams using validate-piles-notation should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/validate-piles-notation/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How validate-piles-notation Compares
| Feature / Agent | validate-piles-notation | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Parse and validate PILES (Puzzle Input Line Entry System) notation for specifying piece fusion groups in jigsawR. Covers syntax validation, parsing into group lists, plain-language explanation, adjacency verification against puzzle results, and round-trip serialization. Use when validating user-supplied PILES strings before passing to generate_puzzle(), debugging fusion group issues, explaining the notation to users, or testing round-trip parse/serialize fidelity.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Validate PILES Notation
Parse and validate PILES notation strings for puzzle piece fusion groups.
## When to Use
- Validating user-supplied PILES strings before passing to `generate_puzzle()`
- Debugging fusion group issues (wrong pieces merged, unexpected results)
- Explaining PILES notation to users in plain language
- Testing round-trip fidelity: parse -> groups -> serialize -> parse
## Inputs
- **Required**: PILES notation string (e.g., `"1-2-3,4-5"`)
- **Optional**: Puzzle result object (for adjacency validation and keyword resolution)
- **Optional**: Puzzle type (for keyword support like `"center"`, `"ring1"`, `"R1"`)
## Procedure
### Step 1: Syntax Validation
```r
library(jigsawR)
result <- validate_piles_syntax("1-2-3,4-5")
# Returns TRUE if valid, error message if invalid
```
Check for common syntax errors:
- Unmatched parentheses: `"1-2(-3)-4"` with mismatched `()`
- Invalid characters: only digits, `-`, `,`, `:`, `(`, `)` and keywords allowed
- Empty groups: `"1-2,,3-4"` (double comma)
**Got:** `TRUE` for valid syntax, descriptive error for invalid.
**If fail:** Print the exact PILES string and the validation error message.
### Step 2: Parse into Groups
```r
groups <- parse_piles("1-2-3,4-5")
# Returns: list(c(1, 2, 3), c(4, 5))
```
For strings with ranges:
```r
groups <- parse_piles("1:6,7-8")
# Returns: list(c(1, 2, 3, 4, 5, 6), c(7, 8))
```
**Got:** List of integer vectors, one per fusion group, with correct piece IDs and group boundaries.
**If fail:** Check that the PILES string passed syntax validation in Step 1 first. If parsing returns unexpected groups, verify that `-` separates pieces within a group and `,` separates groups, and that range notation (`:`) expands to inclusive endpoints.
### Step 3: Explain in Plain Language
Describe each group for the user:
- `"1-2-3,4-5"` -> "Group 1: fuse pieces 1, 2, and 3. Group 2: fuse pieces 4 and 5."
- `"1:6"` -> "Group 1: fuse pieces 1 through 6 (6 pieces)."
- `"center,ring1"` -> "Group 1: center piece. Group 2: all pieces in ring 1."
**Got:** Each fusion group is described in plain language with piece counts and identifiers, making the notation understandable to non-technical users.
**If fail:** If keywords cannot be explained (e.g., `"ring1"` has no clear meaning), the notation may require a puzzle result object for context. Advise the user to provide the puzzle type or use numeric piece IDs instead.
### Step 4: Validate Against Puzzle Result (Optional)
If a puzzle result object is available, verify:
```r
# Generate the puzzle first
puzzle <- generate_puzzle(type = "hexagonal", grid = c(3), size = c(200))
# Parse with puzzle context (resolves keywords)
groups <- parse_fusion("center,ring1", puzzle)
```
Check:
- All piece IDs exist in the puzzle
- Keywords resolve to valid piece sets
- Fused pieces are actually adjacent (warning if not)
**Got:** All piece IDs valid. Adjacent pieces fuse cleanly.
**If fail:** List invalid piece IDs or non-adjacent pairs.
### Step 5: Round-Trip Serialization
Verify parse/serialize fidelity:
```r
original <- "1-2-3,4-5"
groups <- parse_piles(original)
roundtrip <- to_piles(groups)
# roundtrip should equal original (or canonical equivalent)
groups2 <- parse_piles(roundtrip)
identical(groups, groups2) # Must be TRUE
```
**Got:** Round-trip produces identical group lists, confirming that `parse_piles()` and `to_piles()` are inverses.
**If fail:** If round-trip differs, check whether the serializer normalizes the notation (e.g., sorting piece IDs or converting ranges to explicit lists). Canonical differences are acceptable as long as `identical(groups, groups2)` returns `TRUE`.
## PILES Quick Reference
```
# Basic syntax
"1-2" # Fuse pieces 1 and 2
"1-2-3,4-5" # Two groups: (1,2,3) and (4,5)
"1:6" # Range: pieces 1 through 6
# Keywords (require puzzle_result)
"center" # Center piece (hex/concentric)
"ring1" # All pieces in ring 1
"R1" # Row 1 (rectangular)
"boundary" # All boundary pieces
# Functions
parse_piles("1-2-3,4-5") # Parse PILES string
parse_fusion("1-2-3", puzzle) # Auto-detect format
to_piles(list(c(1,2), c(3,4))) # Convert to PILES
validate_piles_syntax("1-2(-3)-4") # Validate syntax
```
## Validation
- [ ] `validate_piles_syntax()` returns TRUE for valid strings
- [ ] `parse_piles()` returns correct group lists
- [ ] Round-trip serialization preserves groups
- [ ] Keywords resolve correctly with puzzle context
- [ ] Invalid syntax produces clear error messages
## Pitfalls
- **Keyword without puzzle context**: Keywords like `"center"` require a puzzle result object. Pass it to `parse_fusion()`, not `parse_piles()`.
- **1-indexed pieces**: Piece IDs start at 1, not 0.
- **Adjacent vs non-adjacent fusion**: Fusing non-adjacent pieces works but may produce unexpected visual results. Validate adjacency when possible.
- **Range notation**: `"1:6"` includes both endpoints (1, 2, 3, 4, 5, 6).
## Related Skills
- `generate-puzzle` — generate puzzles with fusion groups
- `add-puzzle-type` — new types need PILES/fusion support
- `run-puzzle-tests` — test PILES parsing with the full suiteRelated Skills
validate-statistical-output
Validate statistical analysis output through double programming, independent verification, and reference comparison. Covers comparison methodology, tolerance definitions, and deviation handling for regulated environments. Use when validating primary or secondary endpoint analyses for regulatory submissions, performing double programming (R vs SAS or independent R implementations), verifying that analysis code produces correct results, or re-validating after code or environment changes.
validate-references
Check BibTeX entries for completeness, DOI resolution, and broken links. Verify required fields per entry type (article, book, inproceedings), resolve and validate DOIs via the CrossRef API, check URL accessibility, and flag duplicate entries, missing abstracts, and inconsistent formatting. Use when preparing a manuscript bibliography for journal submission, auditing a shared .bib file before a project milestone, after merging bibliographies from multiple sources, when citations render incorrectly, or as a CI check on version-controlled .bib files.
validate-analytical-method
Validate a chromatographic analytical method per ICH Q2(R2) guidelines: define the validation scope by method category, establish specificity through forced degradation, determine linearity and range, assess accuracy and precision, and establish detection limits and robustness for regulatory submission.
decommission-validated-system
Decommission a validated computerized system at end-of-life. Covers data retention assessment by regulation, data migration validation (mapping, transformation, reconciliation), archival strategy, access revocation, documentation archival, and stakeholder notification. Use when a validated system is being replaced, reaching end-of-life without replacement, vendor support is discontinued, multiple systems are consolidating, or regulatory changes render a system obsolete.
skill-name-here
One to three sentences describing what this skill accomplishes, followed by key activation triggers. This field is the primary mechanism agents use to decide whether to activate the skill — it is read during discovery before the full body is loaded. Start with a verb. Include the most important "when to use" conditions inline. Max 1024 characters.
write-vignette
Create R package vignettes using R Markdown or Quarto. Covers vignette setup, YAML configuration, code chunk options, building and testing, and CRAN requirements for vignettes. Use when adding a Getting Started tutorial, documenting complex workflows spanning multiple functions, creating domain-specific guides, or when CRAN submission requires user-facing documentation beyond function help pages.
write-validation-documentation
Write IQ/OQ/PQ validation documentation for computerized systems in regulated environments. Covers protocols, reports, test scripts, deviation handling, and approval workflows. Use when validating R or other software for regulated use, preparing for a regulatory audit, documenting qualification of computing environments, or creating and updating validation protocols and reports for new or re-qualified systems.
write-testthat-tests
Write comprehensive testthat (edition 3) tests for R package functions. Covers test organization, expectations, fixtures, mocking, snapshot tests, parameterized tests, and achieving high coverage. Use when adding tests for new package functions, increasing test coverage for existing code, writing regression tests for bug fixes, or setting up test infrastructure for a package that lacks it.
write-standard-operating-procedure
Write a GxP-compliant Standard Operating Procedure (SOP). Covers regulatory SOP template structure (purpose, scope, definitions, responsibilities, procedure, references, revision history), approval workflow design, periodic review scheduling, and operational procedures for system use. Use when a new validated system requires operational procedures, when existing informal procedures need formalisation, when an audit finding cites missing procedures, when a change control triggers SOP updates, or when periodic review identifies outdated procedural content.
write-roxygen-docs
Write roxygen2 documentation for R package functions, datasets, and classes. Covers all standard tags, cross-references, examples, and generating NAMESPACE entries. Follows tidyverse documentation style. Use when adding documentation to new exported functions, documenting internal helpers or datasets, documenting S3/S4/R6 classes and methods, or fixing documentation-related R CMD check notes.
write-incident-runbook
Create structured incident runbooks with diagnostic steps, resolution procedures, escalation paths, and communication templates for effective incident response. Use when documenting response procedures for recurring alerts, standardizing incident response across an on-call rotation, reducing MTTR with clear diagnostic steps, creating training materials for new team members, or linking alert annotations directly to resolution procedures.
write-helm-chart
Create production-ready Helm charts for Kubernetes application deployment with templating, values management, chart dependencies, hooks, and testing. Covers chart structure, Go template syntax, values.yaml design, chart repositories, versioning, and best practices for maintainable and reusable charts. Use when packaging a Kubernetes application for repeatable deployments, parameterizing manifests for multiple environments, managing complex multi-component applications with dependencies, or standardizing deployment practices with versioned rollback capability across teams.