implement-feature

Implement Feature Skill

Full workflow: CONTRIBUTION_GUIDE.md

Pre-Implementation Checklist

1. Verify context: TZ='America/New_York' date && git status
2. Check/create GitHub issue: gh issue list --state open
3. Check research registry if implementing a technique

Hard Design Decisions — Constraint-Divergent Design

When the problem has multiple plausible approaches (e.g., "event-driven or polling?", "synchronous vs queue-based?", "monolithic helper vs split modules?"), do not generate the same solution three times with different variable names. Instead, articulate 2–3 distinct constraints first, then sketch one solution per constraint and compare.

Anchor constraints in real tradeoffs:

• "minimize allocations" vs "minimize lines of code" vs "minimize external deps"
• "lowest latency" vs "lowest memory" vs "easiest to test"
• "fewest moving parts" vs "easiest to extend" vs "matches existing pattern X"

Three constraints that each eliminate ~70% of the solution space leave you searching ~2.7% of it — a focused region, not blind sampling. (Pattern adapted from itigges22/ATLAS PlanSearch; the math is theirs.)

Apply this discipline only for genuinely-multivalent decisions. Indicators:

• Multiple plausible architectures where reviewers would reasonably disagree
• A wrong choice would be expensive to reverse (data-shape migration, public API surface, cross-package boundary)
• You catch yourself thinking "I'll just pick one and see what review says" — pick deliberately, by constraint, instead

Out of scope: routine work where the approach is dictated by canonical paths or existing patterns. Don't over-apply.

Implementation Process

Phase 1: Interface First

// Define interface FIRST
interface IFeature {
  method(input: Input): Promise<Result<Output, Error>>;
}

See CONTRIBUTION_GUIDE.md for boundary checklist.

Phase 2: TDD

1. Write failing test
2. Run: pnpm test -- --watch
3. Implement to pass

Phase 3: Quality Gates

pnpm lint && pnpm typecheck && pnpm test

Phase 4: Commit and PR

git commit -m "feat(scope): description

Closes #<issue>

Co-Authored-By: Claude Opus 4.6 <[email protected]>"

gh pr create --title "feat(scope): description" --base main

Quality Checklist

See CODING_STANDARDS.md for full checklist.

• Tests pass, coverage ≥ 80%
• Lint and types clean
• Files ≤ 400 lines, functions ≤ 50 lines
• Interface defined first

Implementation Complete Checklist

Before marking ANY technique or feature as "implemented", verify ALL of the following:

Code Requirements

• Code exists in specified integration_files
• All functions have explicit return types
• No any types (use unknown instead)

Quality Gates

• pnpm lint passes with zero errors
• pnpm typecheck passes
• pnpm test passes (relevant tests)

Documentation Updates (if research-related)

• docs/research/registry/techniques.yaml: status: implemented, decision_history entry
• docs/research/registry/papers.yaml: implementation_status updated
• docs/research/RESEARCH_INDEX.md: Quick Stats updated if counts changed

GitHub Tracking

• Implementation issue closed with summary comment
• PR merged (if applicable)

Do NOT mark as implemented if: tests fail, implementation is partial, or feature is behind a flag.

Thin vertical slices (incremental implementation)

Build the smallest end-to-end working piece first, then expand. Avoid implementing the whole feature in one pass — each slice should leave the system in a working, testable state.

The increment cycle

Implement → Test → Verify → Commit → Next slice

For each slice:

1. Implement the smallest complete piece of functionality (must be end-to-end, not just one layer)
2. Test — run the test suite (write a new test if none covers this slice — see test-driven-development skill)
3. Verify — confirm the slice works (tests pass, build succeeds, manual check if user-facing)
4. Commit — small, focused commit with a clear message
5. Next slice — only after the previous one is verifiable

The 100-line rule

If you're about to write more than ~100 lines without testing, stop. Either:

• Split the work into a smaller slice that fits the cycle, OR
• Confirm with the user that the larger scope is justified (e.g., a generated stub from a schema)

Larger commits hide bugs, fight git bisect, and bloat code review surface. Small commits compound; large commits accumulate risk.

Anti-rationalization — Incremental implementation

Excuse	Counter
"It's all related, makes sense to commit together"	"Related" hides the failure boundary. Atomic commits separate "the failing change" from "everything else."
"I'll test it all at the end"	The end is when you're already deep into the next problem. The cycle catches issues while you still have context.
"Splitting this is artificial"	Each slice should be end-to-end (vertical, not horizontal). If you can't make a slice end-to-end, the design is too coupled.
"This is faster as one big push"	Maybe per-keystroke. Per-PR-merged-to-main, the cycle is faster because debug time grows superlinearly with diff size.
"I'll commit when tests pass"	Tests passing is the floor, not the ceiling. Each slice gets its own commit; tests passing is what makes the commit safe.

Red flags

• Implementation merged with pnpm test failing
• Tests added but coverage dropped (test-quality regression)
• Feature behind a flag with no documented removal date
• "Implemented" marked in research registry but feature not actually exercising in production paths
• Files exceeding the 400-line gate without eslint-disable justification