implementation-notes

Maintain a live implementation-notes.md while implementing a written spec, so that design decisions, intentional deviations, alternatives considered, and open questions stay visible during review instead of being reverse-engineered from the diff.

Core principle

A spec is never complete. As you implement, you will make choices the spec did not name. The diff records what you did. Commit messages record what changed. Neither captures why this option over the alternative, which spec line you knowingly departed from, or which question you still need a human to answer. This file does.

The goal is not to write more documentation. It is to give yourself a legitimate place to record the judgment calls you would otherwise either bury silently in code or interrupt the user to ask about.

When to start

Start before the first edit, when all of the following are true:

• A written spec exists — PRD, design doc, GitHub issue, approved plan, or a multi-paragraph prompt.
• Implementation will span multiple files or multiple commits.
• The spec contains at least one ambiguity, gap, or area where a reasonable implementer would face a choice.

If no written spec exists yet, stop and invoke writing-plans first. This skill does not replace planning; it captures what happens after planning meets reality.