feat: add python-property-based-testing skill

[azaharizaman]

Summary

• New independently installable Hypothesis-led property skill (quantified properties, strategies, shrinking, seed/replay; stateful deferred to v1)
• Stdlib-only plan_property_matrix.py planner with deterministic tests
• SKILL.md, three references, eight eval fixtures, catalog and CI integration

Test Plan

• uv run ruff check . (pass)
• uv run ruff format --check . (pass)
• uv run pytest -q (546 passed)
• skills-ref validate for all five skills (valid)
• skills discovery smoke lists all five skills
• git diff --check clean; no secrets or shell=True

Summary by Sourcery

Add an independently installable Python property-based testing skill with Hypothesis guidance, deterministic planning, evidence requirements, and repository-wide integration.

New Features:

• Add the independently installable python-property-based-testing skill for quantified Hypothesis-led properties, oracle design, strategy planning, shrinking, and reproducible replay.
• Provide a standard-library-only property matrix planner with bounded deterministic Cartesian and seeded planning.
• Add property-based testing references, evidence templates, evaluation fixtures, and safety contracts.

Enhancements:

• Define the boundary between finite parameterized testing and quantified property-based testing, with stateful sequence testing deferred for v1.

CI:

• Integrate the new skill into structural and quality contract tests, skills validation, and discovery smoke checks.

Documentation:

• Document the new skill in the README, changelog, contribution guidance, and skills catalog.

Tests:

• Add deterministic planner behavior, malformed-input, non-finite JSON, help, and safety-oriented tests.

[sourcery-ai]

Sorry @azaharizaman, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 5 days and 9 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

Adds and integrates an independently installable Python property-based-testing skill centered on Hypothesis strategies, independent oracles, shrinking, deterministic replay, and honest evidence, with a safe stdlib planner, comprehensive evaluation fixtures, repository contracts, documentation, catalog registration, and CI validation.

Sequence diagram for deterministic property planning and replay

sequenceDiagram
    participant User
    participant Planner as plan_property_matrix.py
    participant Test as Deterministic tests
    participant Runner as Project-native runner
    participant Report as Evidence report
    User->>Planner: Provide JSON target, properties, dimensions, and max_cases
    Planner-->>User: Return bounded matrix and strategy_sketches
    Test->>Planner: Repeat the same payload
    Planner-->>Test: Return deterministic JSON plan
    Runner->>Runner: Execute generated property witnesses
    Runner-->>Report: Record seed, settings, counts, and exit status
    Runner-->>Report: Record minimized failure and replay command

Loading

Flow diagram for the Hypothesis-led property testing workflow

flowchart TD
    Scope["Define quantified property and independent oracle"] --> Domain["Separate valid, invalid, unsupported, and environment domains"]
    Domain --> Strategy["Design bounded strategies and assume budgets"]
    Strategy --> Generate["Generate deterministic witnesses"]
    Generate --> Run["Run with project-native runner"]
    Run --> Failure{"Failure found?"}
    Failure -->|yes| Shrink["Shrink and minimize counterexample"]
    Shrink --> Replay["Replay with seed and settings"]
    Replay --> Evidence["Record evidence, limitations, and coverage gaps"]
    Failure -->|no| Evidence

Loading

File-Level Changes

Change	Details	Files
Adds a standalone Hypothesis-oriented skill covering quantified properties, oracle design, strategy planning, shrinking, replay, and safety boundaries, while explicitly deferring stateful testing.	Defines activation rules and a project-native workflow for property-based testing. Documents property families, independent-oracle and recurrence checks, domains, strategies, shrinking, fallback generation, budgets, and evidence reporting. Adds safety guidance for synthetic data, secret refusal, approval-gated live work, bounded capture, and untrusted output. Provides a canonical evidence-report template and three supporting references.	src/python-property-based-testing/SKILL.md src/python-property-based-testing/references/properties-and-strategies.md src/python-property-based-testing/references/hypothesis-and-shrinking.md src/python-property-based-testing/references/evidence-report.md
Introduces a deterministic, standard-library-only planner for bounded property and strategy matrices.	Accepts validated JSON describing a target, properties, dimensions, boundaries, limits, and optional seed/sample size. Prioritizes boundary values, supports deterministic Cartesian or seeded sampling, reports truncation, and emits strategy sketches. Rejects malformed, non-finite, oversized, or incomplete input with status 2. Adds tests for determinism, boundary ordering, sampling requirements, malformed input, help output, and import safety.	src/python-property-based-testing/scripts/plan_property_matrix.py tests/test_property_matrix.py
Adds eight evaluation fixtures and extends repository quality contracts for the new skill.	Adds positive fixtures for Unicode round trips, independent money oracles, and bounded assume/shrink behavior. Adds near-miss fixtures distinguishing finite tables from quantified properties and implementation-derived recurrence from independent oracles. Adds safety fixtures for live credentials/cost/destructive work and untrusted-output redaction. Adds an evidence fixture requiring complete property-run reporting fields. Registers skill-specific structure, report, fixture, and safety expectations.	src/python-property-based-testing/evals/cases.yaml tests/test_quality_contracts.py tests/test_skill_structure.py
Integrates the fifth skill into project discovery, documentation, contributor validation, and CI.	Adds the skill to the skills.sh catalog and README routing/install documentation. Adds skills-ref validation and discovery-smoke coverage in CI. Adds the validation command to contributor documentation and documents the feature in the changelog.	skills.sh.json README.md .github/workflows/ci.yml CONTRIBUTING.md CHANGELOG.md
Captures the implementation rationale and scope boundary in design and execution-plan documents.	Records the split between finite parameterized matrices and quantified property depth. Documents the canonical source tree, helper safety model, testing architecture, and non-goals. Defines implementation tasks and final verification expectations.	docs/superpowers/plans/2026-10-09-python-property-based-testing.md docs/superpowers/specs/2026-10-09-python-property-based-testing-design.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.