菜单
Use when changing gene clustering (STRING/Leiden functional axis or phenotype MCA/HCPC), the analysis snapshot builder or validator, the memoised clustering cache, cache coherence, or LLM cluster summaries — or deploying a clustering change so public endpoints and summaries reflect it
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Use when adding or changing an external HTTP provider call in SysNDD (gnomAD, Ensembl, UniProt, AlphaFold, MGI, RGD, PubMed, PubTator, MONDO, JAX/HPO) or touching external-call timeouts, retries, caching, or per-request time budgets
Use when wiring a SysNDD Vue 3 view or component to the backend API, adding a typed API client, handling API errors, or binding backend data into BootstrapVueNext tables and tooltips — especially around Plumber response shapes and BVN table/tooltip quirks
Use when adding or changing a SysNDD DB migration, editing a SQL view (especially ndd_entity_view or the core read views), touching the migration runner or manifest, restoring a database, or diagnosing a startup failure related to migrations
Use when reviewing or writing SysNDD code for security vulnerabilities or correctness bugs — authorization/role gates, SQL/expression injection, credential and secret handling, data exposure through public or MCP surfaces, resource-exhaustion/DoS from external calls, error/info leakage, and the repo's known R/Plumber footguns — especially before merging a diff or PR
Use when writing, running, or fixing SysNDD R/Plumber API tests (testthat) — including database-writing tests, running a single test inside the API container, mocking external providers, or diagnosing SKIP-vs-PASS, helper-loading, or path-resolution issues
Use when adding or changing durable async jobs, worker-executed code, job handlers, queue lanes or priorities in SysNDD — or diagnosing why a submitted job never runs, stays queued, or fails with "No durable async job handler registered"
| name | sysndd-analysis-snapshots |
| description | Use when changing gene clustering (STRING/Leiden functional axis or phenotype MCA/HCPC), the analysis snapshot builder or validator, the memoised clustering cache, cache coherence, or LLM cluster summaries — or deploying a clustering change so public endpoints and summaries reflect it |
Use this skill before touching clustering, the snapshot builder/validator, the clustering cache, or LLM cluster summaries. This subsystem (#508–#514) is coherence-sensitive: a subtle mistake serves a stale, internally-incoherent snapshot that still activates as public-ready.
/api/analysis/functional_clustering, .../phenotype_clustering) read activated analysis_snapshot_* rows — not live compute. Nothing public changes until a snapshot refresh job (worker) rebuilds and activates a new row.gen_string_clust_obj, gen_mca_clust_obj, gen_network_edges) is memoised to a disk cache on a named volume that SURVIVES redeploys (bootstrap/init_cache.R).validate_functional_clusters, not memoised) recomputes fresh. They are coherent only when both clustered the identical graph with the identical seed.analysis_snapshot_payload_hash excludes partition_validation and reproducibility (analysis-snapshot-builder.R). So new validation metrics are additive — they never change cluster_hash and never invalidate LLM summaries. Only changes to cluster membership (graph construction, STRING channel, MCA hygiene, Leiden/HCPC params) change cluster_hash.
The memoise key is call-args plus a call-time .cache_fingerprint (analysis-cache-fingerprint.R).
CLUSTER_LOGIC_VERSION. This is the only thing that changes the key for a code-only change; the data-identity components (STRING channel, exp+db file size:mtime, MCA prevalence band) won't. This supersedes the manual CACHE_VERSION bump for clustering caches (CACHE_VERSION nukes all memoised .rds and still governs other return-shape changes).The builder joins validation onto membership only through analysis_snapshot_join_validated_clusters() → analysis_snapshot_assert_partition_coherent() (analysis-snapshot-coherence.R). It refuses to publish (throws → refresh fails → prior public-ready retained) when the visible membership cluster set ≠ the validation set, a visible cluster lacks a stability score, or the membership channel ≠ the validation channel. Never reintroduce a bare left_join(clusters, val$per_cluster). ANALYSIS_SNAPSHOT_REQUIRE_COHERENCE defaults true; setting it false to "get a refresh through" re-opens the incoherent-publish hole — bump CLUSTER_LOGIC_VERSION instead.
Keyed by per-cluster cluster_hash plus LLM_SUMMARY_PROMPT_VERSION (llm-summary-config.R). A membership change changes cluster_hash, so old summaries retire and regenerate. Bump LLM_SUMMARY_PROMPT_VERSION only when the prompt or generation/judge logic changes — not for a clustering change (the hash already handles that; bumping would gratuitously blank untouched clusters).
api/data/9606.protein.links.expdb.v11.5.min400.txt.gz) if the functional axis needs it — else clustering silently falls back to the text-mining graph (loud via warning() + health flag).CLUSTER_LOGIC_VERSION (only for a code change).worker and worker-maintenance (worker-executed code; the refresh runs on the worker).POST /api/admin/analysis/snapshots/refresh?analysis_type=functional_clusters&force=true (and …phenotype_clusters). force is required — a non-forced refresh skips a preset whose current snapshot is still available.POST /api/llm/regenerate?cluster_type=functional&force=true (and …phenotype). force required here too, else it short-circuits on existing is_current rows.health_endpoints.R): analysis.cluster_logic_version == new value, analysis.expdb_edges_file_present == true.GET /api/admin/analysis/snapshots/status: preset available, fresh timestamps.n/a), metrics agree, and weight_channel/membership_weight_channel == experimental_database.cluster_hash. In the batch-generation log, "all cached / 0 generated" means membership did not change — the change was additive and a forced regen is wasteful.