implementation-protocol

implementation-protocol

This skill orchestrates how you turn a feature request into a verified, reviewable change. It is not about writing code — it is about enforcing a contract between intent, change, and proof.

The discipline here exists because the most common failure mode for AI-driven implementation is overbuilding: hallucinated architecture, speculative abstractions, scope creep, and "looks correct" completion without proof. This skill prevents all of that by anchoring every action to observable behavior and failing signals.

When to use

• User asks you to implement a feature, endpoint, capability, or behavior
• User describes something they want working and expects you to build it
• Any non-trivial code change (more than a one-line fix)

When not to use

• Pure refactoring with no behavior change (use code-quality or simplify)
• Scaffolding a new project from scratch (use fastapi-init)
• One-line bug fixes where the fix is obvious

---

Phase 1 — Define the behavior

Never start with implementation. Start by defining what success looks like in concrete, observable terms.

Before touching any code, establish:

1. Inputs and outputs — what goes in, what comes out. Be specific: request shape, response shape, status codes, return types.
2. API contract — if this is an endpoint, what's the route, method, request/response schema?
3. Side effects — what changes in the world? DB writes, log entries, events emitted, files created.
4. Error cases — what happens when inputs are invalid, dependencies are unavailable, or preconditions aren't met?

The implementation ledger

Before proceeding, produce a short ledger that makes the rest of the process auditable. Write it in conversation (or in .dev/todos/<feature>.md if the user prefers a file). The ledger has four sections:

## Behaviors
- [ ] B1: POST /items returns 201 with created item
- [ ] B2: POST /items with missing name returns 422
- ...

## Files to change
- src/api/routes/items.py (new router)
- src/models/item.py (new model)
- ...

## Tests to add/update
- tests/test_items.py::test_create_item (B1)
- tests/test_items.py::test_create_item_missing_name (B2)
- ...

## Proof commands
- uv run pytest tests/test_items.py
- uv run pytest tests/ (full suite)
- uv run ruff check .