From b11cfd66b185a253fecf10ad06080ae165f32a74 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 19 Apr 2026 16:12:02 -0500
Subject: feat: adopt pairwise-tests (PICT combinatorial) + cross-reference
 from existing testing skills
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Forked verbatim from omkamal/pypict-claude-skill (MIT). LICENSE preserved.
Renamed from `pict-test-designer` to `pairwise-tests` — technique-first
naming so users invoking "pairwise" or "combinatorial" find it; PICT
remains the tool under the hood.

Bundle (skill-runtime only):
  pairwise-tests/SKILL.md                    (renamed, description rewritten)
  pairwise-tests/LICENSE                     (MIT, preserved)
  pairwise-tests/references/pict_syntax.md
  pairwise-tests/references/examples.md
  pairwise-tests/scripts/pict_helper.py      (Python CLI for model gen / output fmt)
  pairwise-tests/scripts/README.md

Upstream's repo-level docs (README, QUICKSTART, CONTRIBUTING, etc.) and
`examples/` dir (ATM + gearbox walkthroughs — useful as reading, not as
skill-runtime) omitted from the fork. Attribution footer added.

Cross-references so /add-tests naturally routes to /pairwise-tests when
warranted:

- add-tests/SKILL.md Phase 2 step 8: if a function in scope has 3+ parameters
  each taking multiple values, surface `/pairwise-tests` to the user before
  proposing normal category coverage. Default continues with /add-tests;
  user picks pairwise explicitly.
- claude-rules/testing.md: new "Combinatorial Coverage" section after the
  Normal/Boundary/Error categories. Explains when pairwise wins, when to
  skip (regulated / provably exhaustive contexts, ≤2 parameters, non-
  parametric testing), and points at /pairwise-tests.
- languages/python/claude/rules/python-testing.md: new "Pairwise /
  Combinatorial for Parameter-Heavy Functions" subsection under the
  parametrize guidance. Explains the pytest workflow: /pairwise-tests
  generates the matrix, paste into pytest parametrize block, or use
  pypict helper directly.

Mechanism note: cross-references are judgment-based — Claude reads the
nudges in add-tests/testing/python-testing and acts on them when appropriate,
not automatic dispatch. Craig can still invoke /pairwise-tests directly when
he already knows he wants combinatorial coverage.

Makefile SKILLS extended; make install symlinks /pairwise-tests globally.
---
 pairwise-tests/scripts/README.md | 77 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 pairwise-tests/scripts/README.md

(limited to 'pairwise-tests/scripts/README.md')

diff --git a/pairwise-tests/scripts/README.md b/pairwise-tests/scripts/README.md
new file mode 100644
index 0000000..87ea259
--- /dev/null
+++ b/pairwise-tests/scripts/README.md
@@ -0,0 +1,77 @@
+# Scripts
+
+This directory contains helper scripts for working with PICT models and test cases.
+
+## Available Scripts
+
+### pict_helper.py
+
+A Python utility for:
+- Generating PICT models from JSON configuration
+- Formatting PICT output as markdown tables
+- Parsing PICT output into JSON
+
+**Installation:**
+```bash
+pip install pypict --break-system-packages
+```
+
+**Usage:**
+
+1. **Generate PICT model from config:**
+   ```bash
+   python pict_helper.py generate config.json > model.txt
+   ```
+
+2. **Format PICT output as markdown:**
+   ```bash
+   python pict_helper.py format output.txt
+   ```
+
+3. **Parse PICT output to JSON:**
+   ```bash
+   python pict_helper.py parse output.txt
+   ```
+
+**Example config.json:**
+```json
+{
+    "parameters": {
+        "Browser": ["Chrome", "Firefox", "Safari"],
+        "OS": ["Windows", "MacOS", "Linux"],
+        "Memory": ["4GB", "8GB", "16GB"]
+    },
+    "constraints": [
+        "IF [OS] = \"MacOS\" THEN [Browser] <> \"IE\"",
+        "IF [Memory] = \"4GB\" THEN [OS] <> \"MacOS\""
+    ]
+}
+```
+
+## Future Scripts
+
+We welcome contributions for:
+- Test automation generators
+- Export to test management tools (JIRA, TestRail)
+- Integration with CI/CD pipelines
+- Coverage analysis tools
+- Constraint validation utilities
+
+## Contributing
+
+Have a useful script to share?
+
+1. Add your script to this directory
+2. Update this README with usage instructions
+3. Add comments and examples in your script
+4. Submit a pull request
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
+
+## Dependencies
+
+Current scripts use:
+- Python 3.7+
+- pypict (optional, for direct PICT integration)
+
+All dependencies should be clearly documented in each script.
-- 
cgit v1.2.3