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>

documentation.md

@@ -63,3 +63,50 @@ Tells Claude (and independent agents) what the project is currently working on.
 - Keep it current — remove entries when work is complete
 - Orient agents — this is the primary mechanism for pointing independent agents at the right work
 - Complement, don't duplicate — CLAUDE.md has conventions, MEMORY.md has learnings, CONTEXT.md has the current focus
+
+## Research-Backed Document Generation
+
+When generating structured documents (contracts, specs, reports) from research, require every assertion or clause to link to a sourced finding file. Use a pipeline: `references/` → `research/[topic]/findings/` → `templates/`, with markdown links from clauses back to findings. A clause or claim without a traceable source is flagged as a gap. This turns document generation into an auditable process — reviewers can trace any statement back to its evidence, and missing support becomes visible rather than invisible.
+
+## Structured Q&A to Fill a CONTEXT Template
+
+For drafting tasks with many unknowns, start from a full section template with every field marked TBD, then resolve iteratively via Q&A with the user. Track a confidence level per section (e.g., High/Medium/Low/TBD) so remaining gaps stay visible. Prevents the common failure of premature drafting on incomplete context — the template surfaces what you don't know before the first sentence is written.
+
+## Sourced-Claim Writing: Match Claims to Sources Exactly
+
+When writing claims backed by sources, the claim must match the source exactly in scope, magnitude, population, units, qualifiers, and attribution. Common failure modes:
+- **Population drift** — "82% of organisations" vs source "82% of container users"
+- **Unit mismatch** — dollars vs percentage, per-year vs per-month
+- **Dropped qualifiers** — "not from X" vs source "not just from X"
+- **Year mislabelling** — citing a 2024 figure as 2025
+- **Attribution drift** — attributing a blog post to a famous report it merely references
+
+Fix: read the source before writing the sentence, never drop qualifiers when paraphrasing, and verify the attribution label against the finding's Source section. Paraphrasing from memory is the main cause of drift.
+
+## Three-Layer Verification for Sourced Documents
+
+For evidence-backed documents, run a three-layer check before shipping:
+
+1. **Story vs finding file** — every claim in the narrative matches the finding it cites
+2. **Finding vs reference file** — every finding accurately represents the underlying source
+3. **Structural checks** — every number has a link, every finding has a URL, no unsupported qualifiers
+
+Track verified files by checksum in a `VERIFICATION.md`, enforce via a pre-commit hook.
+
+**Hard rule:** never update a checksum without re-running verification. Structural edits don't change claims but do change the checksum — bumping it without re-verifying silently defeats the control.
+
+Second verification passes routinely catch 10-20+ new issues. Treat verification as iterative, not one-shot.
+
+## Research Workflow: REFERENCES_CONSIDERED Per Topic
+
+When running multi-topic research against a shared reference pool, create a `REFERENCES_CONSIDERED.md` per topic listing every reference and whether it was reviewed through that lens (YES / NO / N-A with a short reason). New topics introduced mid-project miss all previously-processed references unless the gap is made explicit. This file turns "have we checked everything?" into a zero-ambiguity work queue.
+
+Create the file immediately when a topic is created, not retroactively — retroactive creation loses the signal of which references were genuinely reviewed vs. assumed-reviewed.
+
+## Executive Document Structure: Conclusion-First, Glossary Pattern
+
+For documents aimed at senior or executive audiences:
+
+- **Conclusion-first** — put "Bottom Line" and "What We Should Do" ABOVE all evidence. Executive readers are top-down and may not reach the end; evidence becomes supporting detail rather than the main narrative.
+- **Glossary pattern** — replace inline concept explanations with a glossary. Each entry has a brief definition, a "Why leadership should care" hook, and a link to the full detail doc. Keeps the main flow readable while preserving depth for those who want it.
+- **Separate executive brief for long documents** — for compiled docs over ~60 pages, generate a separate 5-10 page brief containing just Bottom Line + Ask + key evidence summaries. The full document remains for reviewers who need detail; the brief is what actually gets read.