planninglisted

# Planning ## Overview **Core principle:** Write the plan for someone with **zero context, questionable taste, and no instinct to test** — because that someone is a fresh subagent, or you after compaction, or you at 2am. Everything the implementer needs is *in the plan*; nothing lives only in your head or the chat. A good plan turns a design into a sequence of tasks that each end in something you can *run and check*. It is the bridge between **shaping** (what & why) and the build (how). ## Map the Structure First Before tasks, lay out the pieces: what files/modules exist, each with **one responsibility**. A clear structure makes the tasks fall out naturally. If you can't name a piece cleanly, the design isn't settled — go back to **shaping** (and see **naming-as-design**). ## Right-Size the Tasks - A task is the **smallest chunk worth a reviewer's gate** — it ends in an independently testable, runnable deliverable. Not "build the parser" (too big); not "add a semicolon" (too small). - Inside a task, steps are **bite-sized** (a couple of minutes each), test-first where it's keeper code. - Each task names its **interfaces**: what it consumes and what it produces, with the *actual* signatures — not "a function that parses input" but the real name, args, and return shape. ## No Placeholders ``` IF THE PLAN SAYS "TBD" OR "SIMILAR TO ABOVE", IT ISN'T A PLAN YET ``` Ban "add error handling", "etc.", "TBD", "like task 2". Write the real thing. A placeholder is a decisio