Incremental Implementation

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.

When to Use

• Implementing any multi-file change
• 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-method 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 dotnet test (or write a test if none exists)
3. Verify — confirm the slice works as expected (tests pass, dotnet build -warnaserror is clean, manual check)
4. Commit -- save your progress with a descriptive message (see git-workflow-and-versioning for atomic commit guidance)
5. Move to the next slice — carry forward, don't restart

Slicing Strategies

Vertical Slices (Preferred)

Build one complete path through the stack:

Slice 1: Create a task (EF Core entity + migration + endpoint + basic view)
    → dotnet test passes, user can create a task via the UI

Slice 2: List tasks (query + endpoint + list view with bindings)
    → dotnet test passes, user can see their tasks

Slice 3: Edit a task (update command + endpoint + edit view)
    → dotnet test passes, user can modify tasks

Slice 4: Delete a task (delete command + endpoint + UI + confirmation)
    → dotnet test passes, full CRUD complete

Each slice delivers working end-to-end functionality.

Contract-First Slicing

When backend and frontend need to develop in parallel:

Slice 0: Define the contract in MyApp.Contracts (DTOs, request/response types, OpenAPI via Swashbuckle)
Slice 1a: Implement backend against the contract + integration tests (WebApplicationFactory)
Slice 1b: Implement frontend against mock data matching the contract
Slice 2: Integrate and test end-to-end

Risk-First Slicing

Tackle the riskiest or most uncertain piece first:

Slice 1: Prove the SignalR hub + client reconnection (highest risk)
Slice 2: Build real-time task updates on the proven connection
Slice 3: Add offline queue and reconnection storm handling

If Slice 1 fails, you discover it before investing in Slices 2 and 3.

Implementation Rules

Rule 0: Simplicity First

Before writing any code, ask: "What is the simplest thing that could work?"

After writing code, review it against these checks:

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

SIMPLICITY CHECK:
✗ Generic IEventBus<T> with middleware pipeline for one notification
✓ Direct method call on a service

✗ Abstract factory pattern for two similar ViewModels
✓ Two straightforward ViewModels with a shared base class

✗ Config-driven form builder for three Avalonia forms
✓ Three straightforward Avalonia views

Three similar lines of code 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 using directives in files you're not modifying
• Remove comments you don't fully understand
• Add features not in the spec because they "seem useful"
• Modernize syntax (primary constructors, collection expressions) in files you're only reading

If you notice something worth improving outside your task scope, note it — don't fix it:

NOTICED BUT NOT TOUCHING:
- MyApp.Core/Utilities/FormatHelper.cs has an unused using (unrelated to this task)
- The auth handler could use better error messages (separate task)
→ Want me to create tasks for these?

Rule 1: One Thing at a Time

Each increment changes one logical thing. Don't mix concerns:

Bad: One commit that adds a new view, refactors an existing ViewModel, and updates Directory.Packages.props.

Good: Three separate commits — one for each change.

Rule 2: Keep It Compilable

After each increment, dotnet build -warnaserror must succeed and dotnet test must pass. Don't leave the solution in a broken state between slices.

Rule 3: Feature Flags for Incomplete Features

If a feature isn't ready for users but you need to merge increments:

// appsettings.json:  "Features": { "EnableTaskSharing": false }
public sealed class FeatureOptions
{
    public bool EnableTaskSharing { get; init; }
}

// In the composition root:
builder.Services.Configure<FeatureOptions>(builder.Configuration.GetSection("Features"));

// At the call site:
if (_features.Value.EnableTaskSharing)
{
    // New sharing flow
}

This lets you merge small increments to the main branch without exposing incomplete work. For Avalonia/MAUI apps, the same pattern works with IOptions<FeatureOptions> injected into view models.

Rule 4: Safe Defaults

New code should default to safe, conservative behavior:

// Safe: opt-in, nullable input, explicit default
public sealed record TaskInput(string Title, string? Description = null);
public sealed record TaskOptions(bool Notify = false);

public Task<TaskId> CreateTaskAsync(
    TaskInput input,
    TaskOptions? options = null,
    CancellationToken cancellationToken = default)
{
    options ??= new TaskOptions();
    // ...
}

Nullable reference types enabled (<Nullable>enable</Nullable>) and explicit defaults keep safe behavior visible at the call site.

For library slices (class libraries consumed from WPF / WinForms / MAUI / Avalonia UI-thread callers), add .ConfigureAwait(false) on every public await — the UI hosts capture SynchronizationContext and resuming on it causes deadlocks under .Result/.Wait() at any callsite. ASP.NET Core hosts do not capture sync context since .NET Core 2.1, so ConfigureAwait(false) is a no-op there; in a library you don't know which host will consume you.

Rule 5: Rollback-Friendly

Each increment should be independently revertable:

• Additive changes (new files, new methods) are easy to revert
• Modifications to existing code should be minimal and focused
• EF Core migrations should have a matching Down method (generated by dotnet ef migrations add); never hand-edit a migration after it has been applied to a shared environment
• Avoid deleting something in one commit and replacing it in the same commit — separate them

Working with Agents

When directing an agent to implement incrementally:

"Let's implement Task 3 from the plan.

Start with just the EF Core entity + migration (run `dotnet ef migrations add`).
Don't touch the UI yet — we'll do that in the next increment.

After implementing, run `dotnet test` and `dotnet build -warnaserror` to verify
nothing is broken."

Be explicit about what's in scope and what's NOT in scope for each increment.

Increment Checklist

After each increment, verify:

• The change does one thing and does it completely
• All existing tests still pass (dotnet test)
• The solution builds with warnings-as-errors (dotnet build -warnaserror)
• Formatting is clean (dotnet format --verify-no-changes)
• The new functionality works as expected
• The change is committed with a descriptive message

Note: Run each verification command (dotnet test, dotnet build -warnaserror, dotnet format --verify-no-changes) after a change that could affect it. After a successful run, don't repeat the same command unless the code has changed since — re-running on unchanged code adds no information.

Common Rationalizations

Red Flags

• More than 100 lines of code written without running dotnet test
• Multiple unrelated changes in a single increment
• "Let me just quickly add this too" scope expansion
• Skipping the test/verify step to move faster
• Build or tests broken between increments
• Large uncommitted changes accumulating
• Building abstractions before the third use case demands it
• Touching files outside the task scope "while I'm here"
• Creating new utility projects for one-time operations
• Editing an already-applied EF Core migration by hand
• Running the same dotnet build/dotnet test command twice in a row without any intervening code change

Verification

After completing all increments for a task:

• Each increment was individually tested and committed
• The full test suite passes (dotnet test)
• The solution builds clean (dotnet build -warnaserror)
• The feature works end-to-end as specified
• No uncommitted changes remain

Source & Modifications

• Upstream: https://github.com/addyosmani/agent-skills/blob/44dac80216da709913fb410f632a65547866346f/skills/incremental-implementation/SKILL.md
• Pinned commit: 44dac80216da709913fb410f632a65547866346f (synced 2026-04-19)
• Status: modified
• Changes:
  • Vertical/contract-first/risk-first slice examples retargeted: EF Core entities + migrations, SignalR hub reconnection, MyApp.Contracts + Swashbuckle as the contract surface, WebApplicationFactory for integration tests
  • Simplicity-check examples swapped to .NET scenarios (generic IEventBus<T>, abstract factory for ViewModels, Avalonia forms)
  • Scope-discipline examples mention using directives, primary constructors, and collection expressions instead of JS/TS imports and modernization
  • Feature-flag example rewritten as IOptions<FeatureOptions> + appsettings.json (works identically in ASP.NET Core, Avalonia, and MAUI via Microsoft.Extensions.Options)
  • Safe-defaults example rewritten as a C# record + CancellationToken parameter with Nullable enabled
  • Rollback-Friendly section: database-migration guidance retargeted to EF Core dotnet ef migrations add + Down method, with the explicit rule not to hand-edit already-applied migrations
  • Agent-direction example uses dotnet ef migrations add, dotnet test, dotnet build -warnaserror
  • Increment Checklist replaces npm test / npm run build / npx tsc --noEmit / npm run lint with dotnet test / dotnet build -warnaserror / dotnet format --verify-no-changes (type check is subsumed by dotnet build)
  • Red-flag list adds "editing an already-applied EF Core migration by hand"
  • All structural sections, rationalizations, and rule ordering preserved from upstream verbatim
• Downstream patches (applied after the initial sync; not tracked against upstream):
  • 2026-04-19 (plugin v1.0.3) — Rule 4 Safe Defaults extended with a ConfigureAwait(false) note for library slices. Library code consumed from WPF / WinForms / MAUI / Avalonia UI-thread callers captures SynchronizationContext by default — every public await in a library should .ConfigureAwait(false) to avoid the deadlock trap. ASP.NET Core has no sync context since .NET Core 2.1, so it's a no-op there, but a library doesn't know which host will consume it.
• Upstream sync 2026-06-14 (plugin v2.6.0) — re-pinned to 3a6fc63. Ported the upstream "no redundant re-runs" guidance (added to the verification checklist as a **Note:**, a new rationalization row, and a new red-flag): after a successful dotnet test/dotnet build -warnaserror run, re-running the same command on unchanged code adds no information. Retargeted from upstream's generic build/test wording to the dotnet CLI.
• License: MIT © 2025 Addy Osmani — see ../../LICENSES/agent-skills-MIT.txt