Implementation Plan Authoring

Implementation Plan Authoring

Overview

From the design sections, write the plan section of the ONE analysis report (analiz-html-report) — the same HTML document attached with add_task_document, format: "html", titled analiz: <YYYY-MM-DD> <topic>. Never a separate plan: … document and never a file in the repo (you do not write or commit files during analysis). Write for a skilled developer who knows NOTHING about this codebase or problem domain and has questionable taste: document every file to touch, every interface, every command. DRY. YAGNI. TDD. Frequent commits — those commits are the implementer's, made later against the plan; the plan itself is never committed.

File Structure First

Before defining tasks, map every file the plan creates or modifies and what each is responsible for — this locks in the decomposition:

• One clear responsibility per file; prefer smaller focused files over catch-alls.
• Files that change together live together; split by responsibility, not technical layer.
• In existing code follow established patterns — don't unilaterally restructure.

Task Right-Sizing

A task is the smallest unit that carries its own test cycle and an independently testable deliverable. Fold setup/scaffolding into the task whose deliverable needs it. Split only where a reviewer could reject one task while approving its neighbor.

Plan Header (mandatory)

The plan section opens with the goal, architecture and constraints before its first step:

<section id="plan">
  <h2>Implementation plan</h2>
  <p><strong>Goal:</strong> one sentence. <strong>Architecture:</strong> 2–3 sentences. <strong>Tech stack:</strong> key technologies.</p>
  <h3 id="plan-constraints">Global constraints</h3>
  <ul><li>Project-wide rules copied VERBATIM from the design — version floors, locale/copy rules, layer boundaries — one line each. Every step implicitly includes this list.</li></ul>
  <h3 id="plan-review-focus">Review Focus</h3>
  <ul><li>Up to 5 inputs or conditions a real user will hit that no step's test covers — empty list, duplicate submit, a zero/negative amount, missing permission, a timeout — each assigned to the step whose test should cover it.</li></ul>
  <ol class="steps"> … </ol>
</section>

Review Focus exists because the spec implies inputs the steps don't always test for. List the ones a reviewer should check for explicitly; an empty list here is a claim that every edge case the spec implies is already tested somewhere in the plan.

Task Structure

Each task is one step — <li id="step-N"> in <ol class="steps"> — and lists:

• Files: exact paths — Create / Modify (with line ranges when known) / Test.
• Interfaces: Consumes (what it uses from earlier tasks — exact signatures) and Produces (what later tasks rely on — exact names, parameter and return types). An implementer sees only their own task; this block is how they learn neighboring names. A reference to another step means "use that step's Interfaces block" — never repeat that step's code here.
• Steps as checkboxes, one action each (2–5 min): write the failing test (show the test code) → run it, expect FAIL with the expected message → write minimal implementation → run it, expect PASS → commit (show the command).

What a Step Contains

A step is unambiguous, not complete — the implementer writes exactly one reasonable thing from it, nothing is invented, but it is not a transcript of the program:

• A test step gives the test name and its assertions as code — this one is always code, because "write a test" without the assertions is not a test.
• A code step gives the exact signature, the file, and any value the spec pins (a constant, a column name, an error type). The body appears only when the signature and the tests do not determine it on their own — an algorithm, a non-obvious ordering, a tricky edge case. A CRUD method whose body is "call the repo and return" does not need its body spelled out; its signature and test do.
• A verify step gives the command and what output means pass.