SKILL.md
Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.
Incremental Implementation
Adapted from addyosmani/agent-skills (MIT), commit 82ceff41ed4d3c644e3dcca8a0514390b2911223.
Overview
Implement changes in small, complete slices. Each slice should leave the system buildable, testable, and easier to reason about than one large unverified batch of edits.
When to Use
- Any multi-file feature or refactor
- Work that crosses API, UI, and data boundaries
- Any task where you are tempted to write a large amount of code before verifying
Increment Cycle
- Implement the smallest complete slice.
- Run the most relevant tests.
- Verify the slice behaves as expected.
- Checkpoint the progress in a reviewable state.
- Move to the next slice.
Rules
Simplicity First
Start with the smallest obviously correct solution. Do not introduce abstractions before the problem actually needs them.
Scope Discipline
Touch only what the current slice requires. Note unrelated cleanup separately instead of mixing it into the implementation.
Keep It Working
Do not leave the codebase knowingly broken between slices. If incomplete work must exist, hide it behind safe defaults or a feature flag.
Prefer Vertical Slices
When possible, deliver one thin end-to-end path through the stack instead of building every layer in parallel without verification.
Slicing Strategies
Vertical Slice
- database change
- API path
- basic UI integration
- verification
Contract First
When multiple layers depend on the same interface, define the contract first and build both sides against it.
Risk First
If one part of the task is uncertain or expensive, prove that part first before investing in the rest.
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "It is faster to do it all at once" | It only feels faster until you have to debug a large unverified diff. |
| "These changes are too small to verify individually" | Small slices are exactly what make debugging and review cheaper. |
| "I will add the flag or guard later" | Incomplete work should not leak into user-visible behavior. |
Verification
- The slice does one coherent thing
- Relevant tests pass after the slice
- Build succeeds
- The next slice can start from a clean, working state
Anti-Rationalization Table
| Excuse | Counter |
|---|---|
| "It's faster to do it all at once" | It only feels faster until you have to debug a large unverified diff. |
| "These changes are too small to verify individually" | Small slices are exactly what make debugging and review cheaper. |
| "I'll add the flag or guard later" | Incomplete work should not leak into user-visible behavior. |
| "The slice doesn't do much on its own" | A slice does not need to be user-visible. It needs to be buildable and testable. |
| "I can skip verification for this slice" | Unverified slices accumulate risk. Verify each one before moving to the next. |