Implementation Notes

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, create or obtain a written plan first (use your environment's planning workflow if one is available). This skill does not replace planning; it captures what happens after planning meets reality.

When to skip

Do not start this file for:

• Single-line or single-file fixes where the change is self-explanatory.
• Pure investigation, debugging, or reading code.
• One-off scripts, throwaway experiments, or work no one will review later.
• Specs under ~50 lines where the implementation produces a single commit. Put the reasoning in the commit body instead.

If you start the file and realize the work is too small, delete it. An empty notes file is worse than no file.

File location

Default location: implementation-notes.md at the root of the spec. If the spec lives inside the repo and the root is reserved for other use, place it at .notes/.md.

If the spec is in a PR, the notes file ships with the change in the same PR.

The four sections

Every entry under each section must answer something the diff cannot. Each entry is one to three sentences. Link to file paths, line ranges, or commit SHAs where useful.

Decisions

Choices made where the spec was ambiguous or silent. Record the choice point and why this option was picked over a named alternative.

• Good: "Used a single SQLite file for the cache instead of one file per project. Reason: simpler GC and we never need cross-project queries. See cache/store.py:42."
• Bad: "Added caching to the API." (This belongs in the commit message; the diff already shows it.)

Deviations

Places where the implementation intentionally departs from the spec. Quote the spec line, then state the change and the reason.

• Good: "Spec §3.2 says retries: 5. Implemented with retries: 3 because the upstream rate-limits at 4 req/s and 5 retries blows the budget. See client.py:88."
• Bad: "Changed retry count." (Does not name the spec line or the reason.)

Tradeoffs

Alternatives considered and rejected. Include the rejection criterion so a reviewer does not waste cycles re-evaluating the same option.

• Good: "Considered Redis for the queue. Rejected because it adds a deployment dependency the user explicitly wanted to avoid (spec.md:14). In-process queue is sufficient at current scale (

Spec: Started:

Decisions

• (none yet)

Deviations

• (none yet)

Tradeoffs

• (none yet)

Open questions

• (none yet)

Keep the four headings even when empty. The empty heading is a question to yourself at the next decision point.

## Quality checklist

Before requesting review:

- [ ] Every entry answers something the diff cannot.
- [ ] No entry could be reconstructed from `git log --stat` alone.
- [ ] Every `Deviations` entry quotes the spec line it departs from.
- [ ] Every `Open questions` entry is phrased so a reviewer can answer yes/no or pick one.
- [ ] The PR description links to this file.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bahayonghang](https://github.com/bahayonghang)
- **Source:** [bahayonghang/my-ai-cli-toolkit](https://github.com/bahayonghang/my-ai-cli-toolkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.