incremental-implementation

Incremental Implementation

Overview

Ship thin vertical slices: implement, test, verify, commit — one task at a time. Never write a large batch of changes all at once. Each increment should leave the system in a working, deployable state. This protects against regressions, makes reviews easier, and provides clean rollback points.

When to Use

• Any change touching more than one file
• Implementing a task from an existing plan
• When you're tempted to "just write it all out first and then test"
• Any feature that takes more than one focused session to implement

When NOT to use: Single-line typo fixes or isolated config changes with no behavior impact.

The Increment Loop

For every task, follow this exact loop:

1. Read Before Writing

• Read the task's acceptance criteria
• Load the relevant existing code (the files this task touches)
• Identify the pattern being extended, not invented
• Confirm the approach matches the spec

Stop if: The approach differs significantly from the spec. Update the spec or plan first.

2. Write a Failing Test (RED)

Write a test that describes the expected behavior. The test must fail before you write any implementation code.

# Example for a FastAPI endpoint
def test_export_skill_returns_zip():
    """Skill export endpoint should return a valid zip file."""
    response = client.post("/api/skills/export", json={"repo": "owner/repo"})
    assert response.status_code == 200
    assert response.headers["content-type"] == "application/zip"

If the test passes before you write the implementation, the test is wrong. Fix it.

3. Implement the Minimum (GREEN)

Write only the code needed to make the test pass. No more, no less.

• Follow existing patterns in the codebase
• No premature abstractions
• No "while I'm here" refactors
• No adding features that aren't in the acceptance criteria

4. Run All Tests

pytest tests/ -v              # full suite
pytest tests/ -k "test_name"  # targeted run for the new test