incremental-implementation
Use when building multi-day features, avoiding long-lived branches, features taking >1 day, changes touching multiple systems, or high-risk changes needing gradual rollout - break features into deployable increments that each provide value
When & Why to Use This Skill
The Incremental Implementation skill is a specialized methodology for software development that emphasizes breaking down complex, multi-day features into small, manageable, and independently deployable increments. By prioritizing vertical slicing over horizontal layers and adhering to the INVEST criteria, this skill ensures that every code change provides immediate value while maintaining system stability. It is designed to eliminate long-lived branches, reduce merge conflicts, and streamline the code review process by keeping pull requests concise and focused.
Use Cases
- Complex Feature Decomposition: Breaking down a large-scale system overhaul into small, low-risk PRs that are each under 500 lines and independently deployable.
- Vertical Slicing Implementation: Developing a new user feature by delivering a fully functional slice (UI, API, and Database) in a single increment rather than building layers in isolation.
- Risk-Mitigated Rollouts: Using feature flags and backward-compatible patterns (like nullable fields and API aliasing) to safely deploy high-risk changes to production.
- Continuous Integration Optimization: Ensuring the main branch remains in a deployable state by avoiding 'work in progress' merges and 'Part 1 of N' commits that lack immediate utility.
- Technical Debt Prevention: Applying structured migration paths for database and API changes to ensure zero downtime and maintain backward compatibility during transitions.
| name | incremental-implementation |
|---|---|
| description | Use when building multi-day features, avoiding long-lived branches, features taking >1 day, changes touching multiple systems, or high-risk changes needing gradual rollout - break features into deployable increments that each provide value |
Incremental Implementation
Persona: Surgeon who makes small, precise incisions - each cut is complete and leaves the patient stable.
Core principle: Every commit to main should be deployable. No "work in progress" merges.
Should NOT Attempt
- PRs >500 lines without explicit approval
- "Part 1 of N" where parts aren't independently deployable
- Horizontal slicing (all UI, then all API, then all DB)
- Breaking changes without migration path
- Merging incomplete features behind no flag
- Bundling unrelated changes "while I'm here"
Vertical Slicing (Preferred)
BAD (Horizontal) GOOD (Vertical)
Week 1: All UI Day 1: Login (UI+API+DB)
Week 2: All API Day 2: Register (UI+API+DB)
Week 3: All Database Day 3: Profile (UI+API+DB)
INVEST criteria: Each increment should be:
- Independent - Can be developed/deployed separately
- Negotiable - Scope can adjust based on feedback
- Valuable - Delivers user or business value
- Estimable - Small enough to estimate accurately
- Small - Completable in 1-3 days
- Testable - Has clear acceptance criteria
Increment Patterns
| Pattern | When to Use |
|---|---|
| API-First | Backend-heavy, multiple clients |
| UI-First with Stub | UI/UX feedback needed early |
| Database-First | Complex data model, careful schema planning |
| Feature Flag | High risk, gradual validation needed |
Example: Good vs Bad
BAD: PR #1: "Add user profile" (2000 lines - everything)
GOOD:
PR #1: "Add user_profiles table" (50 lines)
PR #2: "Add Profile model/repository" (100 lines)
PR #3: "Add GET /api/profile" (80 lines)
PR #4: "Add profile page UI" (150 lines)
PR #5: "Add PUT /api/profile" (100 lines)
PR #6: "Add profile edit form" (200 lines)
Backward Compatibility
Adding fields: nullable first -> backfill -> make non-nullable Changing APIs: add new alongside old -> update clients -> deprecate old -> remove Renaming: add alias -> update callers -> remove old name
Planning Steps
- List all changes - Database, models, APIs, UI
- Find dependencies - What needs what?
- Order by dependencies - Bottom-up
- Size each increment - Target <500 lines
Checkpoint Criteria
Each increment must:
- All tests pass
- Can be deployed independently
- Doesn't break existing functionality
Escalation Triggers
Escalate to architect/lead when:
- Feature cannot be sliced without breaking existing API contracts
- Increment requires data migration affecting >10% of production data
- Dependencies form a cycle that prevents clean ordering
- Smallest viable increment exceeds 500 lines
- Feature requires coordinated deployment across multiple services
How to escalate:
SLICING BLOCKED: [feature name]
Minimum viable increment: [size estimate]
Blocking dependency: [what prevents smaller slices]
Options considered: [A, B, C]
Recommendation: [path forward]
Failure Behavior
When increment cannot be made deployable:
- State what blocks independent deployment
- Present options: feature flag, temporary compatibility layer, or accept larger increment
- Document the technical debt if larger increment accepted
When slicing introduces complexity:
- Compare: complexity of slicing vs. complexity of large PR review
- If slicing adds more risk than it removes, accept larger increment with extra review
Red Flags
- PR >500 lines without good reason
- "WIP" commits on main
- "Part 1 of 3" where parts aren't independent
- Features that "only work when everything is done"
Related Skills
- git-workflow: Isolate incremental work in worktrees, handle completion
- test-driven-development: TDD for each increment
Integration
- git-workflow skill - Isolate each increment in worktree, merge/PR when complete
- orchestrator agent - Help plan increment ordering
- test-driven-development skill - Each increment needs tests
- verification-before-completion skill - Verify before merging each increment