# 03 — Flawless Execution **Goal:** plan development so implementation is clear, fast, and maintainable — and dissolve knowledge gaps on the fly without stalling. > **The core principle:** The cost of a bug or a rewrite is cheapest at the *planning* moment. Ten minutes of structured breakdown saves ten hours of unclear implementation. A feature is not "started" when you open the editor — it is started when the plan is written. --- ## Part 1 — The pre-implementation planning system ### 1.1 The feature one-pager (write before code — 30–45 min) Every feature above ~1 day of work gets this document (in the ticket, not a side file): | Section | Content | Exits when… | |---|---|---| | **Problem** | One sentence: user pain + why now | Stakeholders agree it's the actual problem | | **Success metric** | The number that proves it worked (INP, conversion, usage, error rate) | You can name the measurement point | | **Contract** | API shape, types, URL structure, event names | Backend/QA signed off (01 influence) | | **UI states** | Empty / loading / error / offline / success / edge (per state, not one happy path) | The list is exhaustive enough to hand QA | | **Behavior spec** | Interactions as Given/When/Then (3–8 scenarios) | A QA engineer could test from it without asking you | | **Rollout** | Flag name, canary plan, rollback trigger | It fits the release discipline (02) | ### 1.2 Task breakdown — the 4-hour rule Break the feature into tasks with a hard rule: **no task larger than 4 hours of focused work** (ideally 1–2). If a task can't be broken that small, you don't understand it yet — see Part 2. Each task carries: - **Definition of done (DoD):** the observable result (not "implement X" but "X works when: …") - **Test list:** the cases the task must cover (they become your QA handoff, 04) - **Dependencies:** what must land first - **Risk:** anything uncertain → explicitly mark as *spike* or *unknown* (Part 2) **Dependency graph, not a list:** order tasks so each commit leaves the app *working* (vertical slices: thin end-to-end first, then thicken). Never order as "all backend → all UI → all tests" — that's how weeks go dark with nothing shippable (01's visibility killer). ### 1.3 The implementation loop (per task) 1. **Read the DoD aloud** — if you can't say what "done" looks like, you're not ready to code. 2. **Write the test names first** (the cases from 1.2) — test names are the truest spec. 3. **Implement against the tests** (TDD where the logic is non-trivial; for UI, write the state/behavior tests around the component). 4. **Run the pre-PR gate** (04) before opening the PR. 5. **Self-review the diff as a stranger** (04's fresh-eyes pass) before requesting review. ### 1.4 Estimation that survives contact - Estimate in **relative effort (S/M/L), then convert** — never absolute hours from the hip. - Add the **unknown tax**: any task touching an area you haven't worked in 30 days = S+1 / M+2 days. Knowledge gaps are the #1 estimation error (Part 2 exists because of this). - **Communicate confidence, not just a number:** "2 days, 80% confidence, the risk is the auth edge cases." PMs trust honest confidence more than optimistic dates (01). --- ## Part 2 — Killing knowledge gaps on the fly ### 2.1 The 30-minute rule (structured unblocking) When stuck, run this ladder — never skip a rung, never stay stuck: 1. **0–5 min — Reformulate the question.** Write the exact error/symptom + what you expected. Half of "unknowns" dissolve when precisely stated (this is the debugging discipline of 04, applied early). 2. **5–10 min — Official docs first.** Framework docs (Next.js docs for App Router/caching, React docs, TS handbook), not blog posts. Docs answer versions; blogs answer vibes. 3. **10–15 min — Targeted search.** Search the exact error string (quotes), filter by version, check the GitHub issue tracker for your framework version — a closed issue with a fix is the fastest answer on earth. 4. **15–25 min — Reproduce minimally.** Strip the problem to the smallest repro (a sandbox or a 30-line file). If you can't reproduce small, you don't know what's failing. 5. **25–30 min — Escalate WITH evidence.** Ask the team/backend with: what I tried, the minimal repro, and the specific question. A colleague answers a good question in 2 minutes; a vague one takes an hour of back-and-forth. **The rule:** if you've spent 30 minutes without *narrowing* the problem, you are spinning — escalate. Spinning is not diligence; narrowing is. ### 2.2 The AI pair-debugging protocol (Claude Code / Copilot) AI is exceptional at *narrowing*, mediocre at *deciding*: - **Give it the repro, not the symptom.** Paste the minimal repro + stack trace + expected vs actual. Vague prompts return confident nonsense. - **Ask for hypotheses ranked by likelihood**, then verify the top one yourself with a log/console — never apply an AI fix you don't understand (that's how cargo cults enter codebases). - **Use it to generate the test that proves the fix** — a failing test you understand beats a patch you don't. - **Sandbox spikes for whole unknowns** ("implement a POC of X in a scratch branch") — timeboxed, disposable, and reviewable before it touches real code. - **The honesty rule:** if the AI's explanation doesn't match the code in front of you, the AI is wrong. Your local truth wins. ### 2.3 The knowledge-gap inventory (prevention) - **Every Friday:** note the 2–3 areas where you felt slow this week (a framework API, a domain concept, a tool). Pick one for a **30-min deliberate study** next week (docs walkthrough or a tiny spike). Gaps closed on purpose stop ambushing you in sprints. - **Before starting a feature in an unfamiliar area:** do a 1-hour "recon spike" first (read the docs section, build a 20-line proof) and *include that hour in the estimate*. --- ## Part 3 — The daily execution cadence - **Plan the day in the morning (10 min):** pick the ONE task that matters most; everything else is secondary. Context-switching is the silent killer of senior output — protect 2–3 hour **deep blocks** (calendar-blocked, notifications off). - **WIP limit of 1–2:** one task in implementation, one in review. More open PRs than that = fragmentation, and fragmented seniors look busy and ship slowly. - **Commit in reviewable slices** with conventional-commit messages (`feat(ui): …`); every commit should be *safe to read alone*. - **The 4-hour task rule enforced:** if a task bleeds past its box, re-plan (split it) before continuing — never "just push through," that's how the plan silently becomes fiction. - **Close the loop daily:** at day's end, one line in the ticket: what's done, what's next, what's blocked. Your future self and your PM both thank you (01). --- ## ✅ The execution checklist (per feature) - [ ] Feature one-pager written (problem, metric, contract, states, scenarios, rollout) - [ ] Broken into ≤4h tasks, each with a DoD + test list - [ ] Ordered as vertical slices — every commit leaves the app working - [ ] Unknowns flagged; spikes timeboxed; recon hour included in estimates - [ ] Test names written before implementation for non-trivial logic - [ ] 30-minute rule honored; no >30 min spins without escalation - [ ] Deep blocks protected; WIP ≤ 2 - [ ] Ticket updated daily (done / next / blocked) - [ ] AI used for narrowing and generation, never for unexamined patches → Next: [04 — QA & Reliability](04-qa-and-reliability.md) · Back: [02 — Architectural Mastery](02-architectural-mastery.md)