contract-first-tdd

Implements result-bearing code through contract-governed red-green-refactor test cycles.

1|Updated Dec 13, 2025
One-click install
npx skills add https://github.com/ZK-Theory/TDL --skill contract-first-tdd-zk-theory
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: contract-first-tdd
Source: https://github.com/ZK-Theory/TDL/tree/main/.agents/skills/contract-first-tdd
Command: npx skills add https://github.com/ZK-Theory/TDL --skill contract-first-tdd-zk-theory

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Result-bearing scientific code — pipeline seams, null models, statistical calculations, provenance fields — often gets implemented before its governing contract exists, producing silently wrong outputs. This Skill enforces a contract-first TDD workflow where the governing contract is resolved before any implementation code is written, and every behaviour slice is tested through the public or scientific interface. ## Core Features & Use Cases - Contract Resolution Gate: Requires an upstream contract (or an explicit documented N/A) before writing result-bearing code; the implementer never authors its own contract. - Interface-Level Testing: Tests cross the public/scientific seam — input stage, seeds, null-model order, output schema, error modes — not private internals, so they survive refactors. - Control Classification: Classifies each new control as remediation-red (must fail on the parent) or preservation-green (must pass on both), bound to the seam it exercises. - Exact-Value Assertions: Contract-pinned fields are asserted by exact value and type (e.g. n == 711, family == "quasibinomial") with negative cases, never key-presence checks. - Use Case: When adding a new output field to a statistical pipeline, resolve the schema contract first, write one failing test against the public seam, implement the minimal slice, then run contract binding and provenance checks before proceeding. ## Quick Start Ask the agent to implement a new result-bearing pipeline behaviour using contract-first TDD, resolving the governing schema contract before writing any implementation code.

Frequently Asked Questions about contract-first-tdd

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I practice TDD on scientific or statistical code?

Use contract-first TDD: resolve the governing contract before implementation, then write one failing test per behaviour slice against the public scientific interface. Assert exact values and types for contract-pinned fields rather than key presence, and watch each test fail before making it pass.

What is contract-first test-driven development?

Contract-first TDD is red-green-refactor TDD with a contract layer in front: the governing schema or behaviour contract must exist (or be explicitly documented as not applicable) before any result-bearing implementation code is written. The implementing agent never authors its own contract.

Should tests target public interfaces or private internals?

Tests should cross the public or scientific interface — the seam callers actually use — including input stage, seeds, output schema, and error modes. Testing private internals couples tests to implementation details and breaks them during refactors.

When should I not use contract-first TDD?

Do not use it to author a math-correctness contract for code you are about to implement; contracts must arrive from upstream via schema-contract-design. If the needed contract does not exist, escalate and request upstream authorship instead of proceeding.

What is the difference between remediation-red and preservation-green tests?

A remediation-red control demonstrates behaviour the current change alters and must fail on the parent code. A preservation-green control characterizes behaviour that must remain true and must pass both before and after the change.