Feature Implementation Workflow
Follow this six-phase flow when implementing any new feature. Each phase has a
gate: do not advance until the gate is satisfied. If a gate fails, stay in
the phase or step back — never skip ahead.
Keep changes surgical. Every changed line should trace directly to the feature.
State assumptions before coding; if intent is ambiguous, stop and ask.
Phase 1 — Plan & Impact Analysis
Goal: Understand the change fully before touching code.
- Read the relevant existing code, specs, and data models first.
- Define the feature's success criteria in verifiable terms (inputs, outputs,
observable behavior).
- Map the blast radius: which modules, endpoints, database entities, and
callers are affected (use Gitnexus MCP if have).
- List assumptions and open questions. Surface tradeoffs and simpler
alternatives. Ask if anything is unclear.
- Produce a short numbered plan, each step paired with how it will be verified.
Gate: Plan is written, assumptions are stated, and success criteria are testable. No coding before this is done.
Phase 2 — Update OpenAPI Specs
Goal: Define the contract before the implementation.
- Add or update paths, request/response schemas, status codes, and error
shapes in the OpenAPI spec.
- Keep naming, versioning, and error conventions consistent with the existing
spec.
- Treat the spec as the source of truth that tests and implementation follow.
Gate: Spec is updated and valid (lints/parses cleanly), and it fully
describes the new behavior including error cases.
Phase 3 — Write Tests (cover all cases)
Goal: Encode the contract as failing tests before implementing.
- Choose only the test types needed (unit: business logic, component: UI components, integration: system interactions, end-to-end: only for critical user journeys).
- Write normal-path tests for expected inputs and outputs.
- Write edge-case tests: empty/null, boundary values, invalid input,
auth/permission failures, conflicts, duplicated requests, concurrent operations,
and error responses from the spec.
- Aim to cover every documented case in the OpenAPI contract.
- Tests must fail for the right reason (feature not implemented yet), not
because of setup errors.
Gate: Tests exist for normal and edge cases, run, and fail because the
feature is not yet implemented.
Phase 4 — Implement (pass all tests)
Goal: Write the minimum code that makes the tests pass.
- Implement the simplest solution that satisfies the spec and tests.
- Take care database safety (backward compatibility, indexes, constraints), concurrency & idempotency (duplicate requests, race conditions, retries, lost updates, double execution), observability (show logging, metrics, tracing if important to fix issues), and security (auth, permissions, input validation).
- No features, abstractions, or configurability beyond what was asked.
- Match existing project style, patterns, and libraries. Don't introduce new
ones without reason.
- Run tests and iterate until green.
Gate: All tests pass. The build/compile step runs clean.
Phase 5 — Fix & Refactor
Goal: Improve quality without changing behavior.
- Run linters, type checks, and the full test suite.
- Refactor for clarity and remove duplication introduced by this feature.
- Remove imports/variables/functions that YOUR changes made unused. Don't
delete pre-existing dead code — mention it instead.
- Confirm the spec, tests, and implementation still agree.
Gate: Full suite, build, and linters pass. Behavior is unchanged from the
end of Phase 4 (tests still green).
Phase 6 — Complete & Squash Commit
Goal: Ship a clean, reviewable unit of work.
- Verify the feature end-to-end against the Phase 1 success criteria.
- Clean up temporary files and scaffolding created during development.
- Squash the work into a single, coherent commit with a clear message
(what and why). Only commit when explicitly asked.
- Stage specific files rather than everything; flag any files that may contain
secrets before committing.
Gate: Success criteria met, working tree clean, and a single squashed
commit ready with a descriptive message.
1---2name: best-tdd-workflow3description: Use this skill whenever implementing a new feature end-to-end, especially ones that touch an API contract, database entities, or multiple callers. It is a six-phase workflow that emphasizes planning, testing, and incremental development.4---56# Feature Implementation Workflow78Follow this six-phase flow when implementing any new feature. Each phase has a9**gate**: do not advance until the gate is satisfied. If a gate fails, stay in10the phase or step back — never skip ahead.1112Keep changes surgical. Every changed line should trace directly to the feature.13State assumptions before coding; if intent is ambiguous, stop and ask.1415---1617## Phase 1 — Plan & Impact Analysis1819**Goal:** Understand the change fully before touching code.2021- Read the relevant existing code, specs, and data models first.22- Define the feature's success criteria in verifiable terms (inputs, outputs,23 observable behavior).24- Map the blast radius: which modules, endpoints, database entities, and25 callers are affected (use Gitnexus MCP if have).26- List assumptions and open questions. Surface tradeoffs and simpler27 alternatives. Ask if anything is unclear.28- Produce a short numbered plan, each step paired with how it will be verified.2930**Gate:** Plan is written, assumptions are stated, and success criteria are testable. No coding before this is done.3132---3334## Phase 2 — Update OpenAPI Specs3536**Goal:** Define the contract before the implementation.3738- Add or update paths, request/response schemas, status codes, and error39 shapes in the OpenAPI spec.40- Keep naming, versioning, and error conventions consistent with the existing41 spec.42- Treat the spec as the source of truth that tests and implementation follow.4344**Gate:** Spec is updated and valid (lints/parses cleanly), and it fully45describes the new behavior including error cases.4647---4849## Phase 3 — Write Tests (cover all cases)5051**Goal:** Encode the contract as failing tests before implementing.5253- Choose only the test types needed (unit: business logic, component: UI components, integration: system interactions, end-to-end: only for critical user journeys).54- Write normal-path tests for expected inputs and outputs.55- Write edge-case tests: empty/null, boundary values, invalid input,56 auth/permission failures, conflicts, duplicated requests, concurrent operations,57 and error responses from the spec.58- Aim to cover every documented case in the OpenAPI contract.59- Tests must fail for the right reason (feature not implemented yet), not60 because of setup errors.6162**Gate:** Tests exist for normal and edge cases, run, and fail because the63feature is not yet implemented.6465---6667## Phase 4 — Implement (pass all tests)6869**Goal:** Write the minimum code that makes the tests pass.7071- Implement the simplest solution that satisfies the spec and tests.72- Take care database safety (backward compatibility, indexes, constraints), concurrency & idempotency (duplicate requests, race conditions, retries, lost updates, double execution), observability (show logging, metrics, tracing if important to fix issues), and security (auth, permissions, input validation).73- No features, abstractions, or configurability beyond what was asked.74- Match existing project style, patterns, and libraries. Don't introduce new75 ones without reason.76- Run tests and iterate until green.7778**Gate:** All tests pass. The build/compile step runs clean.7980---8182## Phase 5 — Fix & Refactor8384**Goal:** Improve quality without changing behavior.8586- Run linters, type checks, and the full test suite.87- Refactor for clarity and remove duplication introduced by this feature.88- Remove imports/variables/functions that YOUR changes made unused. Don't89 delete pre-existing dead code — mention it instead.90- Confirm the spec, tests, and implementation still agree.9192**Gate:** Full suite, build, and linters pass. Behavior is unchanged from the93end of Phase 4 (tests still green).9495---9697## Phase 6 — Complete & Squash Commit9899**Goal:** Ship a clean, reviewable unit of work.100101- Verify the feature end-to-end against the Phase 1 success criteria.102- Clean up temporary files and scaffolding created during development.103- Squash the work into a single, coherent commit with a clear message104 (what and why). Only commit when explicitly asked.105- Stage specific files rather than everything; flag any files that may contain106 secrets before committing.107108**Gate:** Success criteria met, working tree clean, and a single squashed109commit ready with a descriptive message.
TuanO20