distill: best practices from 2026-04-19 cross-project run

Adds 3 new topic files (ai-parallel-agents, api-integration,
python-patterns) and extends 21 existing topic files with new gotchas
and patterns surfaced from memory across tracked projects. Index
updated accordingly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

spec-driven-development.md

@@ -80,6 +80,16 @@ Guidelines:
 - Name the scenario descriptively — it becomes the test function's docstring
 - Include enough setup detail that an agent can write the test without guessing
 
+## Plan Mode Produces Architecture, Not Contracts
+
+Plans and specs answer different questions:
+- **Plans** answer "what we'll build" — milestones, tech choices, deployment shape, high-level architecture
+- **Specs** answer "how it must behave" — numbered requirements, scenarios, data models, interfaces
+
+Skipping specs and jumping straight from plan to code forces retroactive spec writing once behaviour questions surface — and then tests written against the implementation have to be rewritten against the spec. This has been measured at ~30% of a session in one case.
+
+**Rule:** for any multi-milestone coding project, enforce Plan → Spec → Test → Code. The plan is not a substitute for the spec.
+
 ## The Spec → Test → Code Workflow
 
 This is the core development loop. Tests are written from the spec before code exists.
@@ -229,6 +239,16 @@ Integration failures fall into a taxonomy of root causes. Categorize failures be
 
 When splitting work into parallel agent tasks, ensure each task writes to distinct files. When two agents must modify the same file, make the shared changes small and predictable — identify the conflict point upfront so the merge is trivial. File-boundary decomposition produces zero-conflict assemblies.
 
+### Parallel Agent Patterns: File Contention, WebFetch Limits, Narrow Reads
+
+When using parallel subagents (Task tool with multiple concurrent invocations):
+
+1. **Never have two agents edit the same file concurrently.** Subagent writes silently collide — one agent's edit wins and the other is lost with no error. Instead, have each agent RETURN prepared text in its response and apply the edits sequentially from the main thread. The main thread owns writes; agents produce content.
+2. **Subagents cannot use WebFetch** (permission denied in the subagent sandbox). Perform web fetches in the main conversation and pass the retrieved content to agents as input. Delegate file processing and analysis to agents, not network IO.
+3. **Give agents narrow read instructions** (e.g., "read only the Key Data Points section of finding X") to prevent expensive full-file reads that blow their context budget.
+
+Verified pattern: 4 parallel agents splitting files 3-4 each verified 195 claims across 16 files in a single round, returning prepared findings to the main thread for sequential application.
+
 ### Choose Manual Implementation for Tightly-Coupled Cross-Component Work
 
 When changes are small per file (5-15 lines) but tightly coupled across many files (each change depends on the previous), skip agent orchestration and implement manually. The assembly overhead exceeds the implementation time. Agent orchestration excels when tasks are independent and substantial; manual implementation excels when work is sequential and interconnected.
@@ -278,3 +298,13 @@ Agents working in isolated worktrees or containers cannot discover mock targets
 ## Plan-First Approach Eliminates Fix Cycles for Cross-Cutting Changes
 
 For changes touching 5+ files across multiple subsystems, invest 30-45 minutes in exploration and planning before writing code. Measured results: sessions with plan-first had 0 fix commits; sessions with code-first had 7:1 fix:forward ratios. Use parallel exploration agents to cover different dimensions of the problem space.
+
+## Wave-Based TDD Dispatch
+
+For large milestones with many subsystems, dispatch test-writing and implementation as two explicit waves rather than interleaving them per agent:
+
+**Wave 1 — Test agents:** Each agent receives the spec for one subsystem and writes all tests. No implementation code yet. Tests must all fail (or be skipped) at the end of Wave 1. Commit the test files to the agents branch.
+
+**Wave 2 — Implementation agents:** Each agent receives the spec + the failing tests written by Wave 1. The agent's success criterion is "make your tests pass without modifying the test file." This hard separation prevents the common failure mode where an agent makes a test pass by weakening it.
+
+**Human review gate between waves:** Before starting Wave 2, review the Wave 1 test files for coverage gaps and assert quality. It's cheaper to fix tests before implementation than after. Check that tests are genuinely failing (not just skipped), that assertions are specific, and that edge cases from the spec scenarios are covered.