Create Implementation

---
name: create-implementation
description: Implement a feature or task following the specification and plan, producing working, tested code.
argument-hint: "[task or specification]"
---

# Create Implementation

Implements a feature or task following its specification, plan, and task decomposition.
Produces working code that passes tests and meets all acceptance criteria.

## Prerequisites

- Apply the shared SDLC conventions in `skills/sdlc/references/shared.md`.
- If no argument is provided, locate the feature directory under `.sdlc/features/` whose frontmatter `issue` field references `$ISSUE_NUMBER`.
- A task description, specification, or plan provided in context or as `$1`
- `.sdlc/features/N-<slug>/lifecycle.md` (optional, if a lifecycle document was produced): implement state machines, transition guards, invariants, and retention policies alongside feature code
- `.sdlc/features/N-<slug>/telemetry.md` (optional, if a telemetry plan was produced): implement analytics events and telemetry alongside feature code
- `.sdlc/features/N-<slug>/observability.md` (optional, if an observability plan was produced): implement logging, metrics, tracing, and health checks alongside feature code
- Access to the codebase for reading and editing
- Test suite available (or created alongside the implementation)

## Workflow

```
Read spec / task
        |
        v
Create or reuse feature branch
        |
        v
Understand codebase context
(patterns, conventions, architecture)
        |
        v
Verify test coverage of code to modify
(add characterization tests if under-tested,
 commit them separately)
        |
        v
Implement in small, verifiable steps
        |
        v
Run tests after each step
        |
        v
All acceptance criteria met?
     /         \
   Yes           No
    |             |
    v             v
  Done          Fix gaps
```

## Steps

1. Read the task, specification, acceptance criteria, lifecycle document, telemetry plan, and observability plan (if present).
2. Set the task frontmatter `status: in-progress` in the corresponding `.sdlc/features/N-<slug>/tasks/N-<slug>.md` file.
3. Update the Task Progress table in `progress.md` to reflect the in-progress status.
4. Set up a feature branch (see Branching Strategy below).
5. Explore the codebase to understand existing patterns, naming conventions, and architecture.
6. Identify which files need to be created or modified.
7. For every existing part of the code you are about to modify, check its current test coverage. If it is not well covered, first write characterization tests that pin down the existing behavior. This keeps you from unintentionally changing behavior with your modifications.
8. Commit the characterization tests separately from the implementation changes, so there is a before/after trace of how the tests evolved.
9. Implement the changes in small increments, verifying each step with tests. Update the characterization tests as the behavior intentionally changes.
10. If a lifecycle document exists, implement state machines, transition guards, invariants, and retention policies as part of each relevant code change.
11. If a telemetry plan exists, implement analytics events and telemetry as part of each relevant code change.
12. If an observability plan exists, implement logging, metrics, tracing, and health checks as part of each relevant code change.
13. Ensure all acceptance criteria are met.
14. Check for code quality issues (naming, duplication, dead code).
15. Review the full diff and confirm the important parts of the changed code are covered by tests (see Test Coverage of Changes below).
16. Run the full test suite and confirm it passes.

## Branching Strategy

The implementation must happen on a dedicated branch, never directly on `main`.

### Branch creation

1. Start from an up-to-date `main`:
   ```
   git checkout main
   git pull
   ```
2. Create a feature branch using the convention `feat/<issue-number>-<short-description>`:
   ```
   git checkout -b feat/42-add-order-endpoint
   ```
   If a plan branch already exists (e.g., `plan/42` from `publish-plan`), create the feature branch from `main`, not from the plan branch. The plan PR is for review only and will be closed separately.

### Commit discipline

- Make small, atomic commits with descriptive messages.
- Commit characterization tests written before the implementation as their own commit, separate from implementation commits, so the test evolution has a clear before/after trace.
- Reference the issue number in at least the first commit (e.g., `feat: add POST /orders endpoint (#42)`).
- Rebase on `main` before pushing if the branch has been alive for a while:
   ```
   git fetch origin
   git rebase origin/main
   ```

### If a branch already exists

If you are resuming work on an existing feature branch, check it out and update it to the latest `main`:
```
git checkout feat/42-add-order-endpoint
git pull
git rebase origin/main
```

## Test Coverage of Changes

Before marking the task done, review the full diff (`git diff main`) and verify the important parts of the change are covered by tests. The important parts are:

- New public functions, methods, classes, and API endpoints.
- Changed logic: branches added, modified, or removed; changed conditions and error paths.
- Bug fixes: a regression test that fails without the fix and passes with it.
- Lifecycle rules, invariants, and transition guards (per the lifecycle document, if present).

Not every line needs a test. Skip boilerplate, trivial accessors, and code the framework or type system already guarantees. If an important part is impractical to test directly (e.g. requires external services), cover it with the closest practical test or note the gap in the task or PR description.

## Implementation Guidelines

- Follow the existing code style and naming conventions in the codebase.
- Write the minimum code needed to meet the acceptance criteria — no speculative features.
- Add comments only where the WHY is non-obvious.
- Handle error cases at system boundaries; trust internal code and framework guarantees.
- Do not introduce new dependencies unless specified in the plan.
- Ensure new code is covered by the tests defined in the test plan.
- Ensure the important parts of the changed code are covered by tests (see Test Coverage of Changes above).
- Design public contracts and persisted data for evolution: tolerate unknown fields, handle unknown enum values gracefully, and prefer additive changes so future versions stay forward compatible.

## Checklist Before Marking Done

- [ ] Working on a feature branch (not `main`)
- [ ] All acceptance criteria satisfied
- [ ] State machines, transition guards, invariants, and retention policies implemented per lifecycle document (if present)
- [ ] Analytics events implemented per telemetry plan (if present)
- [ ] Logging, metrics, tracing, and health checks implemented per observability plan (if present)
- [ ] Tests written and passing
- [ ] Code modified was covered by tests first (characterization tests added where coverage was missing, committed separately)
- [ ] Important parts of the diff covered by tests (new public code, changed logic, regression tests for fixes)
- [ ] No linting or type errors
- [ ] No dead code or commented-out code introduced
- [ ] Ready for `/refactor-implementation`: no speculative abstraction or single-implementation indirection was added
- [ ] Public contracts and persisted data tolerate future additions (forward compatible)
- [ ] Existing tests still pass (no regressions)
- [ ] Branch rebased on latest `main`
- [ ] Task frontmatter updated: `status: done`, `completed_date: <today>`
- [ ] `progress.md` Task Progress table updated
- [ ] Self-check the change against the [`review-implementation` checklist](../review-implementation/SKILL.md) and fix what you can before requesting review

## Handling Blockers

If a task cannot be completed due to an external dependency, missing information, or infrastructure issue:

1. Set the task frontmatter `status: blocked` and fill in `blocker` with a brief description.
2. Update the Task Progress table in `progress.md` and the Current Blocker section.
3. Record the blocker as an assumption via `/create-assumption` if it carries meaningful risk.
4. Move to the next task if it has no dependency on the blocked task.
5. If all remaining tasks depend on the blocked task, stop and write a session end marker to `progress.md`.

When a blocker is resolved:
1. Set the task frontmatter `status: in-progress` and `blocker: null`.
2. Update `progress.md` accordingly.
3. Continue implementation.

## Outcome

If `$OUTCOME_YAML` is set, emit `verdict: approved` there per `skills/sdlc/references/shared.md` once the implementation `impl/` PR is opened. If no PR was opened (e.g. blocked), omit the file.

## Example Usage

**Scenario 1: API endpoint task**
Task T-03: "Implement POST /orders endpoint per spec."
Read spec for request/response schema, find existing endpoint patterns, create route + handler + validation + service layer, write integration test, confirm all test cases pass.

**Scenario 2: Bug fix task**
Task describes a null pointer in the login flow.
Locate the defect, implement the fix, write a regression test that would have caught the bug.

## Next Step

Continue with `/refactor-implementation` to add only the abstractions and seams the change needs, keeping behavior identical.
It then dispatches the review subagent that runs `/review-implementation` to audit correctness, quality, security, and spec alignment.
Once findings are resolved, continue with `/create-documentation`, then `/validate-implementation` to capture visual proof and get user sign-off before opening a PR, then `/create-pr`.

## Useful Commands Reference

Use the tools available in the current session to read files, run tests, and edit code.

| Action | Common commands |
|---|---|
| Run tests | `pytest`, `npm test`, `go test ./...` |
| Type check | `mypy`, `tsc`, `pyright` |
| Lint | `ruff check`, `eslint` |
| Format | `ruff format`, `prettier` |