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>

debugging.md

@@ -22,6 +22,15 @@ After wiring up any new service:
 
 Use `curl --resolve` to test specific paths without depending on DNS propagation.
 
+## Split-Horizon DNS Can Hide Bugs from Local Testing
+
+When `/etc/hosts` or internal DNS points a public hostname at an internal IP, local `curl` bypasses the external path (VPS, CDN, cloud LB) and masks bugs that are only visible to external users. Always verify production behaviour through the actual public path:
+
+- `curl --resolve domain:443:<public-ip> https://domain/...` to force the real external IP
+- Or test from an external machine (phone on cellular, a cloud VM, etc.)
+
+Applies to reverse-proxy routing bugs, HTTP/2 SAN mismatches, and TLS configuration that differs between internal and external ingress.
+
 ## When Something Doesn't Sync/Apply
 
 - Check resource exclusions in the GitOps controller immediately
@@ -79,6 +88,20 @@ Before building a new service, component, or script, read existing patterns in t
 
 Known issues documented in CLAUDE.md or MEMORY.md but not applied to new scripts/configs waste debugging time. Search your own documentation before writing automation that touches areas with known gotchas.
 
+## Read the Spec Before Proposing a Workaround
+
+When a mid-implementation design question arises in a subsystem that already has a written spec, **read the spec before proposing a bridge hack**. The correct design is often already documented. One session burned hours considering Phase 1 bearer-token bypasses before realising the spec already defined the Phase 2 design (bootstrap tokens + mTLS).
+
+Rule: specs exist to prevent this — grep `spec/` or re-read the relevant spec file before inventing a workaround.
+
+## Budget Infrastructure-Recovery Time After Disruptions
+
+After any disruption (power cut, network outage, cluster reboot, registry migration), start the next session with an **infrastructure health check before planning feature work**. Snap confinement quirks, stuck `Terminating` pods, read-only filesystems, and unreachable Git remotes each consume meaningful time to diagnose. Budget recovery as an explicit first phase rather than discovering it mid-task.
+
+## Parallel Research Agents for Broad Topic Coverage
+
+When researching a topic with multiple independent facets, dispatch **parallel research agents** (e.g., one per sub-topic or source type) rather than sequential queries. Scope each agent narrowly (e.g., jurisdiction, domain filter, doc set) to reduce noise and improve signal. Cheap when facets are independent; poor fit when later queries depend on earlier results.
+
 ## API Token Scope Errors
 
 When an API endpoint returns a permission/scope error, read the error response body before guessing. Many APIs (Gitea, GitHub, GitLab) explicitly state the required scope in the error message (e.g., `required=[write:admin]`). This is faster and more reliable than consulting documentation or iterating one scope at a time.
@@ -97,3 +120,11 @@ When a service appears down, check its logs for successful requests from other c
 ## Structured JSON Logging from Application Entry Points
 
 Web frameworks like uvicorn don't configure application-level loggers — only access logs appear by default. Named loggers have no handler unless `logging.basicConfig()` is called explicitly. This makes application logs invisible in production (K8s, Docker) with no error — just silence. Always call `logging.basicConfig()` with a structured format (JSON) early in application startup, before any `getLogger()` calls.
+
+## Verify DB Schema Matches Application Models After Every Deployment
+
+After deploying a new version of an application that uses an ORM or schema migration tool, verify that the live database schema matches what the application expects. Common failure mode: a migration ran in dev/staging but not in production, or a new field was added to a model without a corresponding migration.
+
+**Quick check:** run the application's schema validation command, or compare `alembic current` vs `alembic head`, or run `SELECT column_name FROM information_schema.columns WHERE table_name='<table>'` and diff against the model definition.
+
+**When to check:** after every deployment that touches models or migrations — not just on explicit migration commits. An ORM auto-create (e.g., SQLAlchemy `create_all`) can silently succeed while leaving optional columns missing, causing subtle bugs rather than hard crashes.