Change Contract Implementer

Purpose

Autonomously implement a Change Contract by translating its behavioral specifications into working code. Produce proof of compliance through automated tests and a compliance report. Operate idempotently—running against an already-implemented contract generates a compliance status report and offers to fill any gaps.

What This Skill Does

• Parse and validate Change Contracts before implementation
• Check existing codebase for partial or complete compliance
• Implement changes that fulfill contract invariants
• Create tests that map to Acceptance Checks
• Generate compliance reports documenting implementation status

What This Skill Does NOT Do

• Modify the Change Contract itself
• Invent requirements beyond what the contract specifies
• Implement features not covered by the contract
• Skip verification steps

Implementation Protocol

Phase 0: Locate Contract

If a specific contract path is provided, use it. Otherwise:

1. Look in docs/change-contracts/ for contract files (.md files, excluding *-compliance.md)
2. If no contracts found, report and stop
3. If one contract found, confirm with user: "Found contract: [name]. Implement this?"
4. If multiple contracts found, list them and ask which to implement

Phase 1: Contract Validation

Before any implementation, validate the contract is implementable.

1. Read the contract file
2. Parse all sections:
   • Intent
   • Non-goals
   • Behavioral Contract (Inputs, Outputs, Invariants, Failure Modes)
   • Operability Contract (Logs, Metrics, Load Behavior)
   • Acceptance Checks
3. Analyze the codebase to understand:
   • Existing architecture and patterns
   • Related functionality
   • Test framework in use
   • Logging/metrics infrastructure
4. Validate implementability:
   • Can all Inputs be received from specified sources?
   • Can all Outputs be produced in specified formats?
   • Are Invariants achievable within current architecture?
   • Are Acceptance Checks verifiable?

If gaps detected in contract:

"The contract has gaps that prevent implementation:

• [Gap 1]: [Why it's problematic]
• [Gap 2]: [Why it's problematic]

Please update the contract to address these gaps before proceeding."

Stop and wait for contract correction. Do not proceed with partial implementation of an invalid contract.

Phase 2: Compliance Check

Check what already exists before implementing anything.

1. Map contract requirements to codebase:

   • Identify existing code that fulfills Inputs/Outputs
   • Check if Invariants are already enforced
   • Locate existing error handling for Failure Modes
   • Find existing logging/metrics matching Operability Contract
   • Identify existing tests covering Acceptance Checks

2. Assess compliance status for each requirement:

   • Compliant: Fully implemented and verified
   • Partial: Partially implemented, gaps identified
   • Missing: Not implemented

3. Generate compliance status report (see Reporting Phase format)

4. If fully compliant:

   "This contract is fully implemented. See compliance report at [path]."

   Stop. No implementation needed.

5. If gaps exist:

   "This contract is partially implemented. Gaps identified:

   • [Gap 1]
   • [Gap 2]

   Would you like me to implement these gaps?"

   Wait for user confirmation before proceeding.

Phase 3: Implementation

Implement changes that fulfill contract invariants. Full leeway on HOW—the contract defines WHAT must be true, not how to achieve it.

Guiding Principles

1. Invariants are law: Every implementation choice must satisfy all Invariants
2. Non-goals are boundaries: Never implement anything listed as a Non-goal
3. Minimal footprint: Implement only what the contract requires
4. Codebase consistency: Match existing patterns, conventions, and style
5. Failure modes are requirements: Error handling is not optional

Implementation Order

1. Core behavior first: Implement Inputs → Processing → Outputs
2. Invariant enforcement: Add guards, validations, constraints
3. Failure handling: Implement all specified Failure Modes
4. Operability: Add logging, metrics, load behavior
5. Verification: Create tests for Acceptance Checks

Handling Unexpected Blockers

If implementation encounters an unforeseen obstacle:

1. Document the blocker with specifics
2. Implement everything else that is not blocked
3. Include blocker in compliance report with:
   • What was blocked
   • Why it was blocked
   • Suggested resolution path
4. Continue to verification phase for implemented portions

Do not stop entirely. Maximize implemented compliance and report what remains.

Phase 4: Verification

Create proof of compliance through automated tests.

1. Map Acceptance Checks to tests:

   • Each Acceptance Check should have corresponding test(s)
   • Use the project's existing test framework
   • Match existing test patterns and conventions

2. Test categories:

   • Behavioral tests: Verify Inputs produce expected Outputs
   • Invariant tests: Verify Invariants cannot be violated
   • Failure mode tests: Verify errors are handled as specified
   • Integration tests: Verify end-to-end scenarios from Acceptance Checks

3. Run tests and capture results

4. If tests fail:

   • Fix implementation issues
   • Re-run until passing
   • Document any tests that cannot pass (with explanation)

Phase 5: Reporting

Generate a compliance report documenting implementation status.

Report location: Create at docs/change-contracts/[contract-name]-compliance.md

Report structure:

# Compliance Report: [Contract Name]

**Contract**: [path to contract file]
**Generated**: [timestamp]
**Status**: [Compliant | Partial | Blocked]

## Summary

[1-2 sentence summary of compliance status]

## Implementation Status

### Behavioral Contract

#### Inputs
| Requirement | Status | Implementation |
|-------------|--------|----------------|
| [Input 1]   | [status] | [file:line or description] |

#### Outputs
| Requirement | Status | Implementation |
|-------------|--------|----------------|
| [Output 1]  | [status] | [file:line or description] |

#### Invariants
| Invariant | Status | Enforcement |
|-----------|--------|-------------|
| [Invariant 1] | [status] | [how enforced] |

#### Failure Modes
| Failure Mode | Status | Handler |
|--------------|--------|---------|
| [Mode 1]     | [status] | [file:line] |

### Operability Contract

#### Logs
| Requirement | Status | Location |
|-------------|--------|----------|
| [Log 1]     | [status] | [file:line] |

#### Metrics
| Metric | Status | Implementation |
|--------|--------|----------------|
| [Metric 1] | [status] | [description] |

#### Load Behavior
| Behavior | Status | Implementation |
|----------|--------|----------------|
| [Behavior 1] | [status] | [description] |

## Test Coverage

| Acceptance Check | Test | Result |
|------------------|------|--------|
| [Check 1]        | [test file:name] | [Pass/Fail] |

## Blockers

[If any blockers were encountered, list them here with details]

### [Blocker Title]
- **What**: [What couldn't be implemented]
- **Why**: [Why it was blocked]
- **Resolution**: [Suggested path forward]

Idempotent Behavior

Running this skill multiple times on the same contract produces convergent results:

1. First run: Full implementation + compliance report
2. Subsequent runs: Compliance check → report status → offer to fill gaps
3. On compliant contract: Confirm compliance, generate fresh report, exit

Each run should leave the codebase in an equal or better state of compliance.

Mode Transitions

Clearly distinguish operational modes:

• Validation mode: "Validating contract implementability..."
• Compliance check mode: "Checking existing compliance..."
• Implementation mode: "Implementing [section]..."
• Verification mode: "Creating tests for Acceptance Checks..."
• Reporting mode: "Generating compliance report..."

Announce transitions between modes to maintain clarity.

Integration with Change Contract Generator

This skill complements the change-contract-generator:

Generator (interview) → Change Contract → Implementer (this skill) → Working Code + Proof

The contract serves as the sole specification. Do not reference conversations, assumptions, or context outside the contract document. If something is not in the contract, it is not a requirement.