Explore AI Agent Skills & Claude Prompts

Verify which process actually owns a TCP port before assuming your fresh restart succeeded. Use when: (1) you killed an old server and started a new one but behaviour matches the OLD code/data, (2) `pkill -f pattern` returned 0 but old behaviour persists, (3) you embedded a new asset/binary but the served version is stale, (4) any "I just restarted X but I'm getting old results" situation. `pkill -f` matches against the process command line — if the live old process was started with `--port 0` (auto-assigned) and got the port you now want, the pattern won't match it. Always verify with `lsof -i :PORT` before debugging deeper.

schedule Updated 1 month ago

elixir-escript-daemon-stdio-encoding

Fix intermittent `{:no_translation, :unicode, :latin1}` crashes in Elixir escript daemons that use length-prefixed framed IPC on stdin/stdout. Use when: (1) daemon worker crashes only on some input files, usually ones with non-ASCII bytes (kanji, cyrillic, emoji); (2) error surfaces as `Protocol error` from daemon's error branch or as garbled frame-length bytes seen by the orchestrator/client side; (3) standalone one-shot mode works fine on the same input but multi-request daemon mode fails; (4) `IO.binread(:stdio, N)` returns `{:error, {:no_translation, :unicode, :latin1}}` despite the "bin" prefix suggesting it should be encoding-agnostic. Root cause is the escript default `:standard_io` encoding — it's `:unicode`, and `IO.binread` still routes through the io_server, which translates bytes to codepoints and errors when raw binary frames contain invalid UTF-8 sequences.

rfdb-manifest-l1-carryforward

Diagnose and fix RFDB data disappearing after compaction, where rfdb-server reports a tiny node count (e.g. "15 nodes") on startup despite manifest_index.json showing hundreds of thousands of nodes and segment files existing on disk. Use when: (1) rfdb-server logs "Default database: N nodes" with N orders of magnitude smaller than recent analysis output, (2) /api/stats returns only the most recent commit's nodes, (3) the issue appears AFTER a compaction event (manifest with l1_node_segments populated and node_segments: []), (4) subsequent commits dropped L1 references. Root cause: ManifestStore::create_manifest() initializes l1_node_segments/l1_edge_segments to Vec::new() instead of cloning from current manifest, so any commit AFTER compaction silently orphans all L1 data even though segment .seg files still exist on disk. Compaction injects L1 fields explicitly after create_manifest, but regular commits do not.

rfdb-datalog-hash-join-shared-var

Fix silent incorrect results in RFDB Datalog queries that share a variable between two edge atoms on opposite ends (e.g. self-join patterns like `edge(M, C, "T1"), edge(C, M, "T2")`). Use when: (1) a Datalog rule returns rows that look structurally wrong (e.g. a self-loop rule reports hits but pinning M to each reported id refutes the edge existence), (2) Cypher `MATCH (m)-[:R1]->(c)-[:R2]->(m)` returns the same bogus rows (engine-level bug, not Datalog-specific), (3) results change when you bind one variable explicitly vs. leave it free. Root cause: hash- join fast path in `eval_edge_hash_join` / `eval_incoming_hash_join` unconditionally rebinds the non-key Term::Var without checking whether the variable is already bound in the current row.

rfdb-stale-node-cleanup

Recover from stale RFDB nodes that survive `commit_batch` cleanup despite having their `file` field listed in `changed_files`. Use when: (1) re-running an enricher/orchestrator step but old data with the same file field stays in the graph, (2) `commit_batch(changed_files=[X], ...)` reports success but a query later still returns nodes with `file = X`, (3) you re-pointed structural nodes (e.g., DIRECTORY/FILE) from a synthetic file path to real file paths and the old synthetic-path nodes won't go away, (4) graph-stream / find_by_type returns a mix of "stale" and "new" nodes for the same logical entity. Root cause: `handle_commit_batch` calls `engine.find_by_attr({file: X})` to enumerate nodes-to-delete, but that query path returns only a PARTIAL set after compaction (L1 segments and the file→nodes index can desync). Workaround: enumerate stale nodes via the TS rfdb client `queryNodes({file: X})` (different code path that finds all of them) and call `deleteNode(id)` per node, then re-commit the intended state.

rfdb-v2-clear-ephemeral-trap

Fix RFDB V2 graph data silently not persisting to disk after analysis. Use when: (1) rfdb-server reports "0 nodes, 0 edges" on restart despite successful analysis, (2) segment directories exist but are empty (no .bin files), (3) manifest_index.json shows total_nodes: 0 despite analysis logging 70k+ nodes, (4) Docker builds produce empty graph databases, (5) --clear flag used before analyze command. Root cause: GraphEngineV2::clear() replaces the store with MultiShardStore::ephemeral() which has path: None, causing all flush operations to write to in-memory buffers only.

schedule Updated 13 days ago

rfdb-write-lock-edge-flush-gotcha

RFDB server becomes unresponsive (60s+ timeouts) during enricher addEdges write storms. Use when: (1) RFDB CPU spikes to 60-90% after addEdges calls; (2) subsequent reads time out at 60s; (3) server stays catatonic for 5-15 min after a write storm; (4) Tokio main thread parked (write-lock contention). Root cause: add_edges() calls maybe_auto_flush() which has a memory-pressure path that fires on NODE count — not edge count — and holds the exclusive write lock during disk I/O. Fix: separate maybe_auto_flush_edges() uses byte-limit only.

rfdb-metadata-gotchas

Fix silent metadata issues in RFDB node storage. Covers two traps: (1) metadata flattening — nested metadata fields become top-level after serialization, so node.metadata.field is undefined but node.field works. (2) reserved keys — fields named "type", "id", "name", "file", "exported" are silently stripped from metadata by _parseNode() to prevent overwriting top-level node fields.

schedule Updated 1 month ago

rfdb-batchhandle-deletes-existing-nodes

Fix nodes silently disappearing from RFDB when an enricher or post-resolution pass writes new nodes via BatchHandle. Use when: (1) writing a TypeScript enricher that should ADD nodes/edges to existing files, (2) after calling `client.createBatch()` + `batch.addNode({file: 'X', ...})` + `batch.commit()` the original nodes in file X have vanished, (3) tests that load a graph fixture, run an enricher, then query original nodes get empty results, (4) a verification step shows expected nodes pre-enrichment but 0 post-enrichment. Root cause: `BatchHandle.commit()` invokes RFDB's `commit_batch` which AUTO-POPULATES `changed_files` from each added node's `file` field, then the server DELETES all existing nodes whose `file` matches before inserting new ones — file-level upsert semantics. This is correct for the JS/Haskell analyzers (which fully re-emit a file's contents) but catastrophic for enrichers that only ADD to existing files.

grafema-snapshot-ci-friction

Fix GraphSnapshot tests blocking CI on every feature PR. Use when: (1) every PR fails CI with "Snapshot mismatch" despite correct behavior, (2) fixing snapshots requires build → regen → commit → wait CI cycle per PR, (3) snapshot test in test/unit/*.test.js glob breaks on any intentional change, (4) pre-push hook runs pnpm build + snapshots:update on every push (2-3min overhead). Solution: move GraphSnapshot.test.js to test/unit/snapshots/ so it's excluded from the *.test.js glob. Run manually via pnpm snapshots:update when needed.

schedule Updated 3 months ago

rust-embed-rebuild-invalidation

Force `rust-embed` to re-embed assets from `$GRAFEMA_UI_DIST` (or any env-driven path) when cargo's incremental compilation skips the macro re-expansion. Use when: (1) you rebuilt the GUI bundle but the rust-server binary still serves the OLD bundle, (2) `cargo build --release` finishes in seconds (incremental hit) and `strings target/release/binary | grep <new-hash>` finds nothing, (3) any rust-embed pipeline where assets live outside the cargo source tree and are picked up via env var or symlink. Cargo only re-runs the proc macro when the rust file declaring `#[derive(RustEmbed)]` changes — env var changes alone don't trigger it.

schedule Updated 1 month ago

hex-grid-lattice-mc-refinement

star 32

Design guide + benchmarked pitfalls for building Monte-Carlo / Simulated Annealing refinement layers on top of greedy hex-grid layouts for code visualization (packages/gui/src/store/hexLayout.ts, sandbox/hex-sandbox, future Rust ports). Use when: (1) planning to add MC/SA on top of an existing hex-grid pack, (2) deciding whether a simpler SA would match a hierarchical MC with force-directed + chain drag, (3) budgeting wall-clock for million-node cold-start, (4) debugging "blob turns Swiss-cheese" or "folders stop nucleating" during MC refinement, (5) choosing between folder cohesion and raw Σ-link-length as cost function. Contains four hard-won, quantified lessons and anti-patterns that would take a full day of experiments to rediscover.