tda-representation-diagnostics

Diagnoses embedding stability, coordinate-frame alignment, and representation drift in TDL pipelines.

1|Updated Dec 13, 2025
One-click install
npx skills add https://github.com/ZK-Theory/TDL --skill tda-representation-diagnostics-zk-theory
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: tda-representation-diagnostics
Source: https://github.com/ZK-Theory/TDL/tree/main/.agents/skills/tda-representation-diagnostics
Command: npx skills add https://github.com/ZK-Theory/TDL --skill tda-representation-diagnostics-zk-theory

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Observed and null diagrams are sometimes compared after independently re-fitting PCA, scalers, or loadings, which silently invalidates persistent-homology comparisons and forces results under PROVISIONAL flags. This Skill runs the diagnostic checks that detect such frozen-loadings defects, representation drift, and misuse of visualization-only projections before they corrupt claim-bearing inference. ## Core Features & Use Cases - Coordinate-Frame Auditing: Verifies whether observed and null data share one frozen fitted frame or are re-fit per draw, flagging invalid comparisons. - Representation Status Classification: Distinguishes inference (claim-bearing) representations from visualization-only outputs such as UMAP and t-SNE projections. - Reproducibility and Language Checks: Confirms seeds, scalers, PCA, and loadings are recorded and pinned, and enforces associational-only phrasing for SHAP explanations. - Use Case: Before running a W2 distance comparison between observed and null PCA embeddings, run this diagnostic to confirm both were transformed with frozen loadings; if not, the result is flagged PROVISIONAL and routed to contract-first-tdd. ## Quick Start Ask the agent to run the representation diagnostics on the ngram_pca embedding before comparing observed and null persistent homology results.

Frequently Asked Questions about tda-representation-diagnostics

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if observed and null PCA embeddings are comparable?

Verify that both observed and null data were transformed using one shared fitted frame with frozen loadings. If PCA or the scaler was re-fit per draw, the comparison jointly tests generative difference and basis rotation, making results invalid until corrected.

Can I compute persistent homology directly on UMAP coordinates?

UMAP and t-SNE outputs are visualization-only unless explicitly contracted otherwise, and their distances are not the pipeline metric. Running VR persistence on them requires escalation to a representation-lane review first.

What is the frozen-loadings defect in topological data analysis?

It occurs when observed and null diagrams are compared after independently re-fitting PCA, scalers, or loadings. The coordinate frames no longer align, so distances conflate generative differences with basis rotation, forcing affected results under PROVISIONAL flags.

Can SHAP values be described as showing causal effects?

No. SHAP and similar feature explanations must use associational language only unless causality is separately justified. Phrasing like a feature "drives" an outcome is prohibited in this diagnostic's output records.

When should representation diagnostics escalate instead of fixing directly?

Escalate when the diagnostic implies a committed result sits on an invalid frame, which is a computational defect requiring a PROVISIONAL flag, or when a representation change is proposed, which routes through representation-freeze-audit and contract-first-tdd.