incremental-implementation

Files (1)

• SKILL.md

SKILL.md (first lines)

# Incremental Implementation

## Overview

Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable, and it is exactly how `/opsx:ship-code` works through an OpenSpec change's work-units: one unit, Red→Green→one commit (ticking `tasks.md` off), before the next.

## When to Use

- Implementing any multi-file change
- Working through the work-units of an OpenSpec change (`/opsx:ship-code`)
- Building a new feature from a task breakdown
- Refactoring existing code
- Any time you're tempted to write more than ~100 lines before testing

**When NOT to use:** Single-file, single-function changes where the scope is already minimal.

## The Increment Cycle

```
┌──────────────────────────────────────┐
│                                      │
│   Implement ──→ Test ──→ Verify ──┐  │
│       ▲                           │  │
│       └───── Commit ◄─────────────┘  │
│              │                       │
│              ▼                       │
│          Next slice                  │
│                                      │
└──────────────────────────────────────┘
```

For each slice:

1. **Implement** the smallest complete piece of functionality
2. **Test** — run the narrow test target in the touched package's language; write the test first per `test-driven-development`
3. **Verify** — the resolver-selected gates stay green (uv/go/pnpm as applicable for the touched packages + `ci-free-gates.sh` on py/bench changes + `openspec validate "<change>" --strict`)
4. **Commit** — save progress with a descriptive message; tick off the matching `tasks.md` item if you're inside an OpenSpec change
5. **Move to the next slice** — carry forward, don't restart

## Slicing Strategies

### Vertical Slices (Preferred)

Build one complete path through the stack. In MeKnow, a "stack" is ingest → retrieve_kb → synthesize/cite/filter → API/portal:

```
Slice 1: filter stage refuses on missing citations   (rag-core filter.py + test_filter.py)
    → unit test passes, refuse_if no_citations enforced

Slice 2: retrieve_kb enforces tenant ACL server-side  (rag-core retrieve + pgvector test)
    → DB test passes, no chunk crosses tenant_id

Slice 3: synthesize emits memo_schema_ref-shaped output (agent-core, temperature==0)
    → deterministic test passes, raw chunks never leave the sub-agent

Slice 4: API surface exposes the answer endpoint        (apps/backend + generated portal types)
    → endpoint test passes, benchmark ladder green
```

Each slice delivers working end-to-end functionality.

### Contract-First Slicing

When the backend and portal (or two packages) evolve in parallel, pin the contract first. OpenAPI is the API contract and portal types are *generated*, never hand-written:

```
Slice 0: Define the contract (OpenAPI schema in apps/backend; regenerate portal types)
Slice 1a: Implement the backend side against the spec + pytest tests
Slice 1b: Implement the portal side against the generated types + vitest tests
Slice 2: Integrate and exercise the real path (benchmark ladder / pnpm test:e2e)
```

For the MCP boundary, pin the `kb.*` tool contract (capability `mcp-and-skills`) first, then implement the embedded-transport tool and its caller against it.

### Risk-First Slicing

Tackle the riskiest or most uncertain piece first:

```
Slice 1: Prove cross-tenant isolation holds in retrieve_kb under a cache-key collision (highest risk)
Slice 2: Build the citation/cite stage on the proven retrieval path
Slice 3: Add the synthesize + filter (refuse_if no_citations) stages on top
```

If Slice 1 fails, you discover it before investing in the later slices.

## Implementation Rules

### Rule 0: Simplicity First

Before writing any code, ask: "What is the simplest thing that could work?" After writing it, review against these checks — and if the answer is "simplify," reach for the `code-simplification` skill:

- Can this be done in fewer lines?
- Are these abstractions earning their complexity?
- Would a staff engineer say "why didn't you just..."?
- Am I building for hypothetical future requirements, or the current task?

```
SIMPLICITY CHECK:
✗ A generic agent-framework layer wrapping the LLM
✓ The thin BotPolicy interpreter on anthropic-sdk-python directly (no LangChain)

✗ A new interpreter branch for a new bot behavior
✓ A new BotVersion/BotPolicy row + prompt file (config, not code)

✗ An interface with a single implementation, added "for testing"
✓ The concrete type plus a stubbed LLM transport at the boundary
```

Three similar lines is better than a premature abstraction. Implement the naive, obviously-correct version first. Optimize only after correctness is proven with tests.

### Rule 0.5: Scope Discipline

Touch only what the task requires.

Do NOT:
- "Clean up" code adjacent to your change
- Reorder imports in files you're not modifying
- Remove comments you don't fully understand

From minhlucvan/emdesign, Apache-2.0.

More from minhlucvan/emdesign