SystangoTechnologies/incremental-implementation

Incremental Implementation

Overview

Build in thin vertical slices — implement one piece, verify it compiles, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a compilable state. Read pending tasks from specs/tasks/todo.md, process them in order, and update checkboxes as you complete work. 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-function changes where the scope is already minimal.

The Increment Cycle

┌─────────────────────────────────────────────────┐
│                                                 │
│   Read task ──→ Identify domain ──→             │
│   Load domain skill ──→ Implement ──→           │
│   Verify build compiles ──→                     │
│   Mark [x] in todo.md ──→ Next task             │
│                                                 │
└─────────────────────────────────────────────────┘

For each task:

1. Read the task from specs/tasks/todo.md — description, acceptance criteria, files likely touched
2. Identify the domain — UI, API/interface, or security/auth (see Domain Skill Routing below)
3. Load the domain skill — consult the relevant skill before writing any code
4. Implement the smallest complete piece of functionality
5. Verify — confirm the build compiles (npm run build) and type checking passes (npx tsc --noEmit)
6. Update todo — mark the task [x] in specs/tasks/todo.md immediately after verification
7. Move to the next task — continue until all tasks are done or the session ends

Todo File Integration

Tasks come from {project-root}/specs/tasks/todo.md, generated by the planning-and-task-breakdown skill.

Reading Tasks

Open specs/tasks/todo.md and find the first unchecked task:

- [ ] Task 3: Add user authentication endpoint

Read the full task block: description, acceptance criteria, dependencies, and files likely touched. Confirm any listed dependencies are already checked before starting.

Marking Completion

After each task's build verifies, update the todo immediately:

- [x] Task 3: Add user authentication endpoint

Do this before starting the next task — the checkbox is durable across context compaction; in-progress code is not.

Partial Implementation

If a task is only partially implemented when a session ends, do NOT mark it [x]. Leave it unchecked so the next session resumes from a clean starting point.

If Todo.md Does Not Exist

Stop and run the planning-and-task-breakdown skill first to generate it.

Skipping Test Commands and Unit Tests Sections

When reading a task, two things must be skipped — both are reserved for the /test phase:

1. npm test commands in the Verification block — if a task's Verification block includes npm test commands, skip those. Only run npm run build and npx tsc --noEmit as verification.
2. Unit Tests (deferred) section — every task includes a **Unit Tests (deferred):** block with a - [ ] Tests written checkbox and notes on what to test. Do NOT write those tests during the build phase. Do not create test files. Do not write test code. Do not check the Tests written checkbox. Treat the entire section as read-only context for the future /test phase.

Pre-Implementation Checkpoint (Mandatory)

Before writing any code for a task, complete this checklist:

1. Read the task from specs/tasks/todo.md — including the **Domain skill:** field 1.5 Read project context — check .context/conventions.md for project-specific naming and pattern rules that apply to this task. Check .context/concerns.md for known hazards in the files you'll touch.
2. Classify the domain — if the task has a **Domain skill:** field, use it directly. If the field is missing or says None, check which applies:
   • [ ] UI work (components, layouts, state) → load frontend-ui-engineering
   • [ ] API work (endpoints, contracts, middleware, HTTP status codes) → load api-and-interface-design
   • [ ] Security work (auth, validation, PII, sessions) → load security-and-hardening
   • [ ] None of the above → proceed directly
3. State the loaded skill explicitly before writing any code — e.g., "Loading api-and-interface-design for this task (from Domain skill field)."

Skipping steps 2 and 3 is a process violation. "I'll apply the patterns intuitively" is not a substitute for loading the skill. If the task's **Domain skill:** field names a skill, you must load it — no exceptions.

Domain Skill Routing

Before writing any code for a task, identify its domain and load the corresponding skill. Domain skills encode patterns that prevent entire categories of bugs.

| If the task involves… | Load this skill | |---|---| | UI components, layouts, responsive design, accessibility, state management | frontend-ui-engineering | | API endpoints, REST design, TypeScript interfaces, module boundaries, type contracts | api-and-interface-design | | Authentication, authorization, input validation, PII, session management, external integrations | security-and-hardening |

How to Identify the Domain

Look at the task's description and files likely touched:

• Files in components/, pages/, views/, .tsx/.jsx → frontend-ui-engineering
• Files in routes/, api/, controllers/, services/, types/, interfaces/ → api-and-interface-design
• Tasks mentioning auth, login, tokens, passwords, user input, PII, permissions → security-and-hardening

A task may span more than one domain. Load both skills and apply each where relevant.

When No Domain Skill Applies

Pure infrastructure tasks (build config, migrations with no auth surface, utility functions) do not require a domain skill. Proceed directly to implementation.

Slicing Strategies

Vertical Slices (Preferred)

Build one complete path through the stack:

Slice 1: Create a task (DB + API + basic UI)
    → Tests pass, user can create a task via the UI

Slice 2: List tasks (query + API + UI)
    → Tests pass, user can see their tasks

Slice 3: Edit a task (update + API + UI)
    → Tests pass, user can modify tasks

Slice 4: Delete a task (delete + API + UI + confirmation)
    → Tests pass, 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 API contract (types, interfaces, OpenAPI spec)
Slice 1a: Implement backend against the contract + API tests
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 WebSocket connection works (highest risk)
Slice 2: Build real-time task updates on the proven connection
Slice 3: Add offline support and reconnection

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 EventBus with middleware pipeline for one notification
✓ Simple function call

✗ Abstract factory pattern for two similar components
✓ Two straightforward components with shared utilities

✗ Config-driven form builder for three forms
✓ Three form components

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
• Refactor imports 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 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:
- src/utils/format.ts has an unused import (unrelated to this task)
- The auth middleware 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 increment that adds a new component, refactors an existing one, and updates the build config.

Good: Three separate logical changes implemented in sequence, each tracked in todo.md as its own completed task.

Rule 2: Keep It Compilable

After each increment, the project must build (npm run build) and type checking must pass (npx tsc --noEmit). Don't leave the codebase in a broken state between tasks. Tests are not run per-increment — they are deferred to a separate testing session.

Rule 3: Feature Flags for Incomplete Features

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

// Feature flag for work-in-progress
const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';

if (ENABLE_TASK_SHARING) {
  // New sharing UI
}

This lets you merge small increments to the main branch without exposing incomplete work.

Rule 4: Safe Defaults

New code should default to safe, conservative behavior:

// Safe: disabled by default, opt-in
export function createTask(data: TaskInput, options?: { notify?: boolean }) {
  const shouldNotify = options?.notify ?? false;
  // ...
}

Rule 5: Rollback-Friendly

Each increment should be independently revertable:

• Additive changes (new files, new functions) are easy to revert
• Modifications to existing code should be minimal and focused
• Database migrations should have corresponding rollback migrations
• Avoid deleting something and replacing it in the same increment without a clear intermediate state — separate them across increments when risk warrants it

Working with Agents

When directing an agent to implement incrementally:

"Let's work through the tasks in specs/tasks/todo.md.

For each task: identify the domain (UI, API, or security/auth),
load the relevant skill, implement the slice, verify it compiles,
and mark it complete in todo.md.

Do not write tests during implementation."

Be explicit about what's in scope and what's NOT for each task. The agent should verify dependencies are complete before starting each task.

Increment Checklist

After each task, verify:

• [ ] The change does one thing and does it completely
• [ ] The build succeeds (npm run build)
• [ ] Type checking passes (npx tsc --noEmit)
• [ ] Linting passes (npm run lint)
• [ ] The new functionality works as expected
• [ ] The task is marked [x] in specs/tasks/todo.md

Version control

This skill does not prescribe when or how to commit. When the user or project needs git workflow (branching, messages, atomicity), use the git-workflow-and-versioning skill.

Common Rationalizations

| Rationalization | Reality | |---|---| | "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. | | "It's faster to do it all at once" | It feels faster until something breaks and you can't find which of 500 changed lines caused it. | | "These changes are too small to split" | Small, focused increments are easier to verify and roll back than one large mixed change. | | "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. | | "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. | | "I'll write tests for this later" | Correct — and intentional. The task's Unit Tests (deferred) section already captures what to test. Run /test after the build phase. Do not write tests now, even if the section makes it tempting. | | "I should checkpoint in git before moving on" | Mark the todo checkbox when the task is verified — it is durable across compaction. Use git-workflow-and-versioning only when the user or project asks for commits. |

Red Flags

• Multiple unrelated changes in a single increment
• "Let me just quickly add this too" scope expansion
• Skipping the build/compile verify step to move faster
• Build or linting broken between increments
• Many files changing without marking completed tasks [x] in todo.md
• Building abstractions before the third use case demands it
• Touching files outside the task scope "while I'm here"
• Creating new utility files for one-time operations
• Starting implementation without loading the relevant domain skill first (stating "Loading api-and-interface-design" before writing endpoint code is required, not optional)
• Writing API endpoint code without loading api-and-interface-design — the skill catches missing versioning, inconsistent error schemas, wrong status codes
• Todo.md not updated immediately after each completed task
• Creating test files or writing test code during the build phase (reserved for the /test phase)
• Checking the Tests written checkbox in a task's Unit Tests section (only the /test phase does this)

Verification

After all tasks in a session are complete:

• [ ] All completed tasks are marked [x] in specs/tasks/todo.md
• [ ] The build is clean (npm run build)
• [ ] Type checking passes (npx tsc --noEmit)
• [ ] Linting passes (npm run lint)
• [ ] The feature works end-to-end as specified by acceptance criteria