Implementation Plans (IPs)

A minimal template and process for writing Implementation Plans alongside your code. Drop these two files into any repository under docs/ip/ and start writing.

Why this exists. AI coding tools made code cheap. They did not make the reasoning behind the code cheap. The IP is the artifact that travels with the code so that the next session — yours, an AI's, or the next engineer's — can retrieve what was decided instead of guessing.

Long-form essay: The Implementation Plan: How to Keep Context When AI Codes Faster Than You Can Think.

---

The one rule

No gaps, ever. Every IP closes the architectural gaps it identifies. Open questions, TBD tasks, and "fix it later" flags are gaps that eventually fire in production.

When a fix would derail the current IP, the answer is not deferral. You open a new IP for it on the spot. At AI implementation velocity, context disappears in a blink — for you and for the model. Use the context while you have it.

---

Writing a new IP

1. Pick the next IP number. One unbroken sequence per repository (IP-001, IP-002, …). Numbers are permanent — they are how code comments and other IPs will reference this one.
2. Copy TEMPLATE.md to docs/ip/ip-XXX-short-description.md. Lowercase, hyphenated, descriptive.
3. Fill in the metadata table at the top: ID, title, status, created/updated dates, author, dependencies, target component.
4. Write the overview before anything else. If you cannot state the problem and solution in three bullets, you are not ready to hand this to an AI agent.
5. Decompose into phases with task IDs (XXX-PPTT), tests, and checkpoints. Each phase has an exit criterion — when you cross it, you move on.
6. Reference the IP from the code it produces. A comment in the source file such as // IP-042: signal scope rules, per-item outputs go to stream not registry is a pointer back to the decision and the tests that proved it.

---

Required sections

Every IP MUST include these — the template provides the structure.

• Metadata table — eight fields, compact.
• Overview — problem, solution, key benefits.
• Architecture — at least one ASCII diagram. Before/after for refactors; data flow or component diagram for new features.
• Task Tracker — IDs in XXX-PPTT form, dependencies, status.
• Phases — each with a goal, tasks, a test-first example, and a checkpoint.
• Files to Implement — directory tree with a total count.
• Retrospective — filled in after the IP ships.

Add ADRs only when there were two viable options and the choice was non-obvious.

---

Tests before commit

Every implementation task must have a passing unit test before the code is committed.

1. Write the test first.
2. Confirm it fails.
3. Apply the implementation.
4. Confirm the test passes.
5. Commit (test and code together).

A green build alone is not sufficient. A build can pass while the new code is dead, unreachable, or wired to the wrong type. The test is what proves the code does what the IP says it should do.

---

Status values

Status	Meaning
Draft	Initial proposal, gathering requirements
Planning	Requirements defined, designing implementation
Pending	Approved, waiting to start
In Progress	Active development
Done	All tasks done, pending merge
Complete	Merged to main
Superseded	Replaced by a newer IP
Abandoned	Dropped, not being pursued

---

ADR format

### ADR-XXX-01: {Decision Title}

- **Decision:** what was chosen.
- **Context:** what forced the choice.
- **Options:**
  - **Option A** — description. Why rejected.
  - **Option B (chosen)** — description.
- **Rationale:** the synthesis — why B won.
- **Consequences:** what this decision will require downstream.

Number ADRs per-IP starting at 01 (e.g. ADR-049-01, ADR-049-02).

---

Completeness checklist

Before you mark an IP Done:

• Metadata table complete and current
• Overview explains the problem and solution
• Architecture diagram included
• Every task has an ID, dependencies, and a status
• Each phase has a goal, test-first example, and checkpoint
• Every implementation task has a passing unit test
• Files to Implement section lists everything
• No TBD or open question left unresolved
• Retrospective filled in

---

License

These templates are in the public domain. Use, adapt, redistribute — no attribution required, none refused.