divine-mobile

Run and debug Flutter E2E integration tests that exercise the real app against a local Docker backend (no mocks). Use when running E2E tests, debugging failures, or working on the local harness.

Review all uncommitted changes before pushing. Checks for dead code, stale comments, CLAUDE.md rule violations, unused imports, and inconsistencies introduced during the current session. Invoke with /review-before-commit.

Fix ArgoCD ExternalSecret deployment failing with "namespace X is not permitted in project Y". Use when: (1) ExternalSecret shows OutOfSync in ArgoCD but won't sync, (2) ArgoCD application status shows "namespace X is not permitted in project 'infrastructure'", (3) ExternalSecret targets a namespace managed by a different ArgoCD project, (4) Using apps-of-apps pattern with separate infrastructure and application projects.

Art direction for any content — reads text, PDF, Word, HTML, PPT, then proposes 2-3 creative directions with photography style, mood, and visual language. After selection, generates AI image prompts and visual briefs section-by-section. Use when the user shares content and needs visual direction, image sourcing, or creative direction for any material.

Fix "Null check operator used on a null value" errors when an object is set to null during an async await. Use when: (1) Object reference is nullified while awaiting, (2) Code accesses object with ! after await returns, (3) Cancel/dispose operations run concurrently with async operations on same object. Solution: capture local reference before await.

Add custom metadata headers (x-amz-meta-*) to AWS v4 signed requests for GCS S3-compatible API. Use when: (1) Adding custom metadata to GCS uploads via S3 API, (2) Getting signature mismatch errors after adding new headers, (3) x-amz-meta-* headers being ignored or causing 403 errors. Custom headers MUST be included in canonical headers and signed headers list.

Fix password/secret authentication failures caused by trailing newlines when creating Google Cloud secrets (or similar) with bash here-strings. Use when: (1) Password authentication fails with correct password, (2) Secret created with `<<< "value"` syntax, (3) Error like "password authentication failed" or "invalid token" despite correct value. Bash here-strings (`<<<`) add a trailing newline that corrupts secrets.

Fix silent video/media processing failures caused by URL extraction code that filters on file extensions (.mp4, .webm, .webp). Use when: (1) Media moderation, transcoding, or analysis silently skips files from Blossom or content-addressed storage servers, (2) URL extraction from Nostr event tags (imeta, r tags) drops URLs without recognized extensions, (3) CDN fallback URLs append .mp4 but the actual server uses extensionless content-addressed paths like /{sha256}. Common in Nostr video events (kind 34236) where different clients use different URL formats.

Fix cert-manager DNS01 ACME challenges stuck in "pending" state with "DNS record not yet propagated" inside GKE private clusters, even when TXT records exist in Cloudflare DNS. Use when: (1) cert-manager challenges show "pending" for hours with propagation check failures, (2) dig from outside cluster shows correct TXT records but cert-manager can't verify them, (3) Using Cloudflare DNS01 solver in a GKE private cluster with Cloud NAT, (4) Google Cloud intercepts 8.8.8.8 DNS queries returning NXDOMAIN for Cloudflare-managed records, (5) Even --dns01-recursive-nameservers with 1.1.1.1 doesn't fix the propagation check despite TXT records being verifiable from busybox pods in the same namespace. Covers the full debugging flow and certbot manual workaround.

Use when reviewing what was learned after debugging, workaround discovery, or trial-and-error investigation, and capture it as a dated journal entry under ~/.claude/journal

Fix ClickHouse query errors when querying AggregatingMergeTree tables that use state functions. Use when: (1) Query fails with type mismatch on AggregateFunction columns, (2) Using sum/count on columns created with sumState/countState/uniqState, (3) Creating views that JOIN with materialized views using AggregatingMergeTree, (4) Getting unexpected results from aggregate columns that show as AggregateFunction(sum, ...) type. The *State() functions store intermediate aggregate states, not final values - you must use *Merge() functions to finalize them.

Fix ClickHouse Cloud migration failures caused by multi-table RENAME statements. Use when: (1) Migration fails with "Database X is Shared, it does not support renaming of multiple tables in single query", (2) golang-migrate or other migration tools show dirty database version after a table-swap migration on ClickHouse Cloud, (3) Schema migration works on self-hosted ClickHouse but fails on ClickHouse Cloud. ClickHouse Cloud uses SharedMergeTree engine which has restrictions not present in regular MergeTree.

Fix HTTP 500 / ClickHouse "column not found" errors when filtering by a MATERIALIZED column through a VIEW that doesn't expose it. Use when: (1) a WHERE clause references alias.column on a view but the column is MATERIALIZED on the underlying table, (2) the query works on the raw table but fails through the view, (3) adding a new filter param to an API causes 500 even though the column exists in the base table. Fix by using a subquery against the base table instead of referencing the column directly on the view. Applies to ClickHouse views over tables with MATERIALIZED or ALIAS columns.

Fix duplicate Nostr events in ClickHouse when using ReplacingMergeTree for NIP-33 addressable events (Kind 30000+). Use when: (1) Edited videos/events appear as duplicates, (2) Same d_tag shows multiple events with different IDs, (3) FINAL keyword doesn't deduplicate properly for parameterized replaceable events. The issue is that FINAL deduplicates by ORDER BY key (typically `id`), not by (pubkey, kind, d_tag).

Fix ClickHouse query errors in Rust when using clickhouse-rs crate. Use when: (1) "string is not valid utf8" errors - typically FixedString columns need CAST to String, (2) "tag for enum is not valid" errors - typically Option<T> fields receiving non-NULL values, (3) Sum/count aggregations returning Float64 but Rust expects u64, (4) LEFT JOIN results with empty strings where Rust expects Option::None, (5) "not enough data, probably a row type mismatches a database schema" - query SELECT returns fewer columns than the Rust Row struct expects (common when multiple query functions share the same struct but one function is missing columns added later), (6) Garbled/corrupted data when INSERTing to FixedString(N) columns using String Rust type - silently corrupts data (no error!) because String adds a length prefix but FixedString expects exactly N raw bytes. Fix: use [u8; N] with #[serde(with = "BigArray")] from serde-big-array, (7) "the trait bound `[u8; 64]: serde::Serialize` is not satisfied" when using [u8; N]

Debug ClickHouse deserialization errors in Rust caused by column ORDER mismatch when using SELECT alias.* on a VIEW that adds computed columns. Use when: (1) Some query variants (e.g. sort=trending) return 500 but others (sort=recent) succeed, (2) Queries use SELECT view_alias.*, extra_cols FROM view JOIN ..., (3) The Rust Row struct has the right number and types of fields but deserialization fails anyway (wrong type error, not "not enough data"), (4) The VIEW was recently extended with a computed column (e.g. trending_score).

Fix ClickHouse "Code: 243 Cannot reserve 1.00 MiB, not enough space" errors caused by system log tables (text_log, trace_log, processors_profile_log, query_log) filling the disk. Use when: (1) ClickHouse inserts fail with NOT_ENOUGH_SPACE error, (2) Disk is 100% full but application tables are small, (3) system database is 10-100x larger than user databases, (4) Sentry shows batch insert/commit failures across multiple tables simultaneously. Covers both self-hosted ClickHouse (Altinity operator on K8s) and ClickHouse Cloud with different remediation paths for each.

Fix Cloud Run GPU deployment failures caused by quota errors. Use when: (1) `gcloud run deploy` fails with "You do not have quota for using GPUs with zonal redundancy" AND "You do not have quota for using GPUs without zonal redundancy", (2) The service already exists and is running with a GPU, (3) You only need to update the container image, not change GPU config. Uses `gcloud run services update --image` instead of `gcloud run deploy` to bypass quota re-validation on existing GPU services.

Set up Cloud Run Jobs with CloudSQL connection. Use when: (1) Deploying long-running batch jobs that need database access, (2) Errors like "Cloud SQL Proxy not found" in container, (3) "password authentication failed" despite correct credentials, (4) Job creation fails with permission errors. Covers socket path configuration, IAM permissions, and common gotchas.

Configure static outbound IP addresses for Google Cloud Run jobs/services. Use when: (1) External service needs to whitelist your IP (archive.org, APIs, firewalls), (2) Cloud Run requests appear from random/changing IPs, (3) Need consistent source IP for crawlers, scrapers, or API clients running on Cloud Run. Requires VPC connector + Cloud NAT + static IP reservation. Works for both Cloud Run services and jobs.

Fix Google Cloud Scheduler silently failing to trigger Cloud Run jobs with status code 7 (PERMISSION_DENIED). Use when: (1) Cloud Run jobs stop running but schedulers show ENABLED, (2) gcloud scheduler jobs describe shows lastAttemptTime but status.code: 7, (3) Jobs worked before but stopped after IAM changes or project updates. The scheduler service account needs roles/run.invoker on the project.

Fix psycopg2 "could not receive data from server: Operation timed out" or "connection already closed" errors when using Cloud SQL with long-running Python scripts. Use when: (1) psycopg2.OperationalError after a period of no DB activity, (2) DB connection works initially but fails after a non-DB phase (API calls, file processing, CDX scans), (3) Cloud SQL managed PostgreSQL kills idle connections. The fix is to defer DB connection opening until needed, or add reconnection logic for long-running batch processes.

CRITICAL: Never modify files in content-addressable storage systems where the filename IS the content hash (SHA256, IPFS CID, etc.). Use when: (1) Working with Blossom protocol, IPFS, or any CAS system, (2) Considering "optimizing" stored files (faststart, compression), (3) Implementing transcoding or processing pipelines for hash-identified content, (4) Building on top of ProofMode or any cryptographic verification system. Modifying files in place breaks hash verification and content integrity.

Fix misleading HTTP response header values when debugging with curl -I or curl -sI. Use when: (1) Response headers differ between curl testing and actual browser/client behavior, (2) Cache-Control or other headers show unexpected values despite correct middleware code, (3) Server-side middleware that only applies to GET requests appears to not work when testing with curl -I. The -I flag sends HEAD requests, and middleware that checks for GET method will skip processing, returning handler-level headers instead of middleware-overridden ones.

Fix Dart/Flutter services where calling start() after stop() is a silent no-op because stop() sets a _disposed (or similar) flag that start()'s guard short-circuits on. Use when: (1) A repository/service/controller has startListening/stopListening, subscribe/unsubscribe, open/close, or similar lifecycle methods, (2) Re-opening the service after closing it appears to do nothing — no subscription, no events, no error, (3) Unit tests that only exercise a single mount/open/start cycle pass while the real app breaks on the second visit to a screen, (4) A boolean flag is used both for "in the middle of tearing down this instance forever" AND for "currently stopped, can be re-started". Common in Riverpod/Bloc-driven screens that wire startListening() in initState and stopListening() in dispose — the second time the user visits the screen, nothing happens.

Recover content from "dead" CDNs where DNS no longer resolves but servers still respond. Use when: (1) A service shut down but you have URLs to their CDN, (2) DNS lookups fail but you suspect the CDN provider (Fastly, CloudFront, Akamai) still has the content, (3) Archiving content from defunct services like Vine, Tumblr, etc. The key insight: CDN providers often keep serving content long after DNS dies - hit the IP directly with the original Host header.

Fix incorrect priority ordering when using denormalized aggregate columns. Use when: (1) Records are processed in wrong order despite ORDER BY on count/sum columns, (2) Top items by some metric aren't being selected first, (3) Aggregate columns show 0 or NULL for records that should have high values, (4) Priority queue processes low-value items before high-value ones. The root cause is often that denormalized columns (vine_count, loop_count, total_orders, etc.) weren't backfilled or maintained properly. Solution: JOIN with source tables to compute actual aggregates at query time.

Use when starting work in any divine-* repo (divine-web, divine-mobile, divine-funnelcake, keycast, divine-blossom, divine-router, etc.) or when you've learned a cross-repo fact worth sharing back. The shared divine-context handbook at ~/code/divine/divine-context/ is the source of truth for cross-cutting architecture, Nostr usage, terminology, and the project catalog across the ~50 divine-* repos.

Fix "blocked: event rejected by relay policy" errors when publishing Kind 34236 (video) events to divine relays. Use when: (1) Kind 0 profile events succeed but Kind 34236 fails, (2) Generic policy rejection with no specific reason, (3) Video events work on other relays but fail on divine relays. The divine relay requires thumbnails for all video events - stricter than NIP-71 spec.

Fix deployed Rust binaries not reflecting code changes when using docker buildx. Use when: (1) Code changes are verified locally (tests pass) but production behavior doesn't change after deploy, (2) Docker image has a new tag but contains old compiled binary, (3) Dockerfile uses multi-stage build with dependency pre-compilation layer and source copy layer. Docker buildx layer caching can serve stale compilation output even when source files change, especially with cross-compilation (--platform linux/amd64).

Fix LRU-bounded Flutter/bloc state classes that silently lose insertion-order updates. Use when: (1) a state class uses `Equatable` with a `LinkedHashMap<K, V>` field to preserve insertion order (LRU, MRU, recent-items caches), (2) `Cubit.emit` appears to drop emissions when an existing key is re-inserted or moved to most-recent, (3) LRU eviction evicts the "wrong" entry after a refresh, (4) a test that reports the same key twice and then overflows the cap sees the refreshed entry evicted instead of the oldest. Root cause: Equatable's default map comparison is structural (unordered), so reordering without changing keys/values produces an "equal" state that `Cubit.emit` suppresses.

Fix silent failures in Fastly Compute@Edge when using send_async for fire-and-forget requests. Use when: (1) Background tasks (migrations, webhooks, notifications) triggered from Compute never complete, (2) send_async PendingRequest is immediately dropped, (3) Fire-and-forget pattern works locally but fails in production, (4) An async trigger "logs as triggered" but the target service never receives the request (especially after renaming backend constants — the URL hostname is cosmetic, the backend name determines routing, so a global rename can silently reroute calls to the wrong service). Also covers silent backend-not-found errors when FALLBACK_BACKENDS or other backend constants reference names not configured in the Fastly dashboard.

Fix "Requested backend named 'X' does not exist" or TLS alert errors in Fastly Compute@Edge. Use when: (1) Backend works locally but fails in production with "backend does not exist", (2) TLS alert received (alert_id=0) errors when calling external APIs from Fastly, (3) Backends defined in fastly.toml aren't available after deployment. The fastly.toml [[backends]] section only applies during initial service creation - existing services require backends to be added via CLI or API with proper SSL/SNI configuration.

Debug Fastly Compute deployments that appear successful but return stale/wrong responses. Use when: (1) fastly compute publish succeeds but version check shows old version, (2) new endpoints return 404 after deployment, (3) cache-busted requests work but regular requests fail, (4) fastly domain list doesn't show your custom domain. Covers edge propagation timing, cached error responses, and domain management API differences.

Fix Fastly Compute Rust crate `cargo test` failures with "ld: symbol(s) not found" errors for Fastly SDK symbols like `_version_set`, `_body_new`, `_req_send` on native host builds. Use when: (1) `cargo test` on a Fastly Compute crate fails at link time with errors mentioning libfastly and symbols with names like `fastly::http::response::handle::...`, (2) You added a `#[cfg(test)]` module to a file in a Fastly Compute binary crate and the tests never seem to run or fail to link, (3) Existing `#[cfg(test)]` modules in src/main.rs or its sibling modules appear dead despite being present in the source tree, (4) `cargo test --lib` works but `cargo test` fails.

Fix "backend exists on a draft version but isn't reachable from the new Compute deploy" bugs after `fastly compute publish`. Use when: (1) You ran `fastly service backend create --autoclone` (or any dashboard/CLI change that creates a draft version) but did not activate that draft, (2) You then ran `fastly compute publish` which appeared successful but your backend / ACL / header / dictionary change is missing from the active version, (3) Compute code returns backend-not-found errors or misroutes requests, (4) You're surprised to see your draft version number "skipped over" in the version chain. Root cause: `fastly compute publish` clones from the currently-active version, not from the latest draft, so dashboard changes made in an un-activated draft get stranded.

Fix Fastly Compute Rust build failures caused by edition2024 dependencies. Use when: (1) cargo build fails with "feature `edition2024` is required", (2) wit-bindgen or wasip2 crates fail to download/parse, (3) Fastly SDK pulls in incompatible transitive dependencies, (4) Build worked before but fails after dependency update. Solves by pinning wit-bindgen, wasip2, and related crates to pre-edition2024 versions.

Fix .well-known files (apple-app-site-association, assetlinks.json) being served as HTML by the @fastly/compute-js-static-publish SPA fallback instead of JSON. Use when: (1) iOS Universal Links or Android App Links are broken because the verification files return text/html instead of application/json, (2) PublisherServer with spaFile config intercepts /.well-known/ paths and returns index.html (200, text/html) instead of 404 for missing files, (3) apple-app-site-association (no file extension) gets wrong content type even when correctly stored in KV. Covers both apex domain and subdomain handler patterns.

Fix "Fastly error: unknown domain" 500 errors when custom domains return "Domain Not Found" despite being created with domain-v1 CLI. Use when: (1) fastly domain-v1 create succeeds but domain returns 500, (2) Domain shows activated:false in API response, (3) Classic domain API returns "deprecated" error, (4) Custom domain works on edgecompute.app but not on your domain. Covers Fastly Compute domain setup post-September 2025.

Fix intermittent 500 errors with "Failed to store" in Fastly KV Store during concurrent writes. Use when: (1) Batch operations fail with ~10-20% error rate, (2) Error contains "Failed to store list" or similar KV write failures, (3) Multiple requests updating the same KV key simultaneously, (4) Read-modify-write pattern without locking. The fix is adding a retry loop that re-reads before each write attempt.