lite-sdd-implement

Plan the implementation of a spec.md, build it, and keep implementation.md as the living technical image of the code. Each feature folder holds one spec.md (functional source of truth) and one implementation.md (technical image); for where they live see lite-sdd-overview → ## Repository layout.

The loop is always the same and runs in this order:

spec.md (ready)
   └─▶ Phase 0 — plan (in plan mode, not stored)
          └─▶ user approves the plan
                 └─▶ Phase 1 — technical implementation
                        └─▶ Phase 2 — update implementation.md to match the real code

spec.md is the what and stays functional. implementation.md is the how it is actually built and stays technical. Never start Phase 1 before the plan is approved; never finish a feature without Phase 2.

Phase 0 — Plan (blocking, plan is not stored)

Before touching any file:

1. Push the user into plan mode. If the agent is not already in plan mode, recommend switching to it (Claude Code: Shift+Tab → Plan mode) and say why: plan mode makes the harness physically refuse file edits until the plan is approved, so it is a hard guardrail, not just a promise.
2. Produce the plan in the conversation. Plan the implementation of the spec (new feature, or the part of the spec just changed). The plan is temporal ("add this, replace that") and therefore never written to disk — only implementation.md persists. Git holds the history; the plan does not.
3. Get explicit approval. Present the plan and wait for the user to approve it.

Do not modify any file until the plan is approved. If you are in plan mode, leave it through the native approval gate; if you are not, self-enforce this gate anyway — the rule binds whether or not plan mode is on.

Phase 1 — Technical implementation

Build exactly the approved plan. If reality forces a departure from the plan (a lib behaves differently, a better approach surfaces), that is fine — the plan was only a means. What matters is that Phase 2 documents what you actually built, not what the plan predicted.

Phase 2 — Update implementation.md (mandatory, every time)

After the code is written, always review and update implementation.md so it matches the code that now exists. This is not optional and not deferred to "later".

• Document what is, not what was planned. Read the code you wrote and describe the real behaviour. Where it diverged from the plan, the code wins.
• Compare to the spec. implementation.md must be able to honour every rule in spec.md. A rule with no corresponding implementation is a gap — surface it.
• Rewrite, don't append. See ## implementation.md reflects the real state below.

What implementation.md is

The exhaustive technical image of how the feature is really built — the technical counterpart to the functional spec.md. Its job is to let the next person (human or agent) implement the next feature without re-discovering how this one works, and without repeating mistakes already made here.

It is exhaustive on what matters and silent on the trivial. Trace everything that shapes real behaviour; skip boilerplate, obvious wiring, and noise.

Trace (exhaustive)	Skip (futile)
Every API call: trigger, endpoint/operation, params, response handling	Trivial getters, obvious imports, framework boilerplate
Every filter, query, sort, and pagination rule actually applied	Self-evident one-liners with no behavioural weight
Every behaviour change on a UI event (click a button, an event fires)	Restating the spec's functional rules verbatim
Non-obvious UI behaviours worth knowing for future features — patterns to reuse, pitfalls and mistakes not to reproduce	Step-by-step narration of how the code was written

Suggested skeleton — adapt the sections to the feature, keep it token-light:

# NNN — <Feature title> · Implementation

## Overview

One paragraph: how the feature is built — the main modules/components and how they
fit together.

## API calls

| Trigger | Endpoint / operation | Params / payload | Response handling |
|---|---|---|---|
| … | … | … | … |

## Filters & queries

The filters, queries, sort and pagination rules actually applied (and where).

## Event → behaviour

| Event (click, load, change, …) | What the app does |
|---|---|
| … | … |

## Notable UI behaviour

Non-obvious behaviours worth knowing for future features: patterns to reuse,
gotchas hit here, mistakes not to reproduce.

## Key files

Where the above lives in the codebase (paths), so the next reader finds it fast.

implementation.md reflects the real state, not the history

Like spec.md, implementation.md always describes the state that exists now, never how it got there. When a behaviour changes, rewrite the affected part: no changelogs, no "previously…" notes, no struck-through lines, no plan leftovers. This is exactly why the plan is never stored — a stored plan would rot into a stale, temporal record. History lives in git; implementation.md stays a clean image of the current code.

Anti-patterns (DO NOT DO)

Anti-pattern	Correct approach
Editing files before the plan is approved	Phase 0 gate — recommend plan mode, present the plan, wait for approval
Writing the plan to disk (plan.md, a stored design doc)	Keep the plan in the conversation; only implementation.md persists
Writing implementation.md before coding	It is a descriptive image of real code — write/update it in Phase 2, after the build
Skipping the implementation.md update when "the change was small"	Phase 2 is mandatory every time; an un-synced doc is a stale doc
Documenting what the plan predicted instead of what was built	Read the real code; where code and plan diverge, the code wins
Padding implementation.md with trivia (boilerplate, obvious wiring)	Trace API calls, filters, event→behaviour and notable UI behaviour; skip the futile
Keeping changelogs / "previously…" notes when behaviour changes	Rewrite to the current state; history lives in git

Skill boundaries

• Project layout, numbering, and skill routing → lite-sdd-overview
• New project setup → lite-sdd-init
• Writing or updating a specification → lite-sdd-specify