implementation-notes

Implementation Notes

No plan survives contact with the codebase. Log what changed and why, without stopping the work.

Workflow

1. At the start of implementation, create implementation-notes.md in the project root. If the file already exists, do not overwrite it — when its latest section is this same task, keep appending there; otherwise append a new # Implementation Notes — <task name> (<YYYY-MM-DD>) section at the end, opening with the same AGENT comment as the template below. Do not commit the file unless the user asks (once committed, the exclude stops applying — keep later edits out of unrelated commits). If this is a git repo, exclude it locally (not .gitignore — that would show up in the diff): n=implementation-notes.md; p="$(git rev-parse --git-path info/exclude 2>/dev/null)" && { mkdir -p "$(dirname "$p")" && { grep -qxF "$n" "$p" || echo "$n" >> "$p"; }; } 2>/dev/null || echo "note: could not exclude $n — leaving it untracked, never staging it" (worktree-safe; if the write is blocked, leave the file untracked and never stage it). Structure:

# Implementation Notes — <task name> (<YYYY-MM-DD>)
<!-- AGENT (re-read this even after context compaction): running log for this
task. (1) Log every decision and deviation immediately, 1-3 lines each;
deviations as: plan said / found / did instead / why. (2) Re-read this file
before every commit and after each completed todo; log anything the plan
didn't say before moving on. (3) Never commit or stage this file. (4) Before
the session ends: re-read it, give the user a digest of THIS task's
Deviations and Open Questions, and remind them to feed this file into the
next planning round (or pitch-explainer / change-quiz). Full workflow: read
the implementation-notes skill. -->

## Context
Links to the plan/spec/prototype/taking list this run is based on (e.g.
implementation-plan.md, ./design-directions/). If the plan lives only in
chat, restate its one-line goal and key decisions here.

## Decisions
Choices made where the plan was silent. One line each: what + why.

## Deviations
Where reality forced a change from the plan.
Each entry: what the plan said / what was found / what was done instead / why.

## Surprises & Open Questions
Edge cases, dead code, wrong assumptions in the plan — anything the next
planning session should know.