exp-lens-unit-interference
Skill1 starsChanged 8 months agoMITView on GitHub
Create Unit Interference experimental design diagram showing unit hierarchy, cluster structure, shared resources, and SUTVA violation pathways. Causal-Structural lens answering "What is the unit, and can treatments spill over?
In this repository59 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- arch-lens-c4-containerSkill
- arch-lens-concurrencySkill
- arch-lens-data-lineageSkill
- arch-lens-deploymentSkill
- arch-lens-developmentSkill
- arch-lens-error-resilienceSkill
- arch-lens-module-dependencySkill
- arch-lens-operationalSkill
- arch-lens-process-flowSkill
- arch-lens-repository-accessSkill
- arch-lens-scenariosSkill
- arch-lens-securitySkill
- arch-lens-state-lifecycleSkill
- audit-archSkill
- audit-bugsSkill
- audit-cohesionSkill
- audit-defense-standardsSkill
- audit-frictionSkill
- audit-implSkill
- audit-testsSkill
- design-guardsSkill
- dry-walkthroughSkill
- elaborate-phaseSkill
- exp-lens-benchmark-representativenessSkill
- exp-lens-causal-assumptionsSkill
- exp-lens-comparator-constructionSkill
- exp-lens-error-budgetSkill
- exp-lens-estimand-claritySkill
- exp-lens-exploratory-confirmatorySkill
- exp-lens-fair-comparisonSkill
- exp-lens-governance-riskSkill
- exp-lens-iterative-learningSkill
- exp-lens-measurement-validitySkill
- exp-lens-pipeline-integritySkill
- exp-lens-randomization-blockingSkill
- exp-lens-reproducibility-artifactsSkill
- exp-lens-sensitivity-robustnessSkill
- exp-lens-severity-testingSkill
- exp-lens-validity-threatsSkill
- exp-lens-variance-stabilitySkill
- id-slopSkill
- implement-worktreeSkill
- investigateSkill
- make-arch-diagSkill
- make-experiment-diagSkill
- make-groupsSkill
- make-planSkill
- make-reqSkill
- make-scenariosSkill
- mermaidSkill
- plan-arcSkill
- rectifySkill
- review-approachSkill
- update-architectureSkill
- update-reqsSkill
- update-specsSkill
- verify-diagSkill
- verify-proposed-diagSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
Do not litter the codebase with useless comments, TODO markers, or explanatory annotations — the skill output and diagram speak for …
- Very specific: line 37
BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY
- Distinctive: line 50
Look for: user, request, session, query, item, sample, trial, instance
- Distinctive: line 55
Look for: cluster, group, shard, server, region, batch, household, team
- Distinctive: line 60
Look for: cache, queue, pool, database, service, load_balancer, gpu, memory
- Distinctive: line 65
Look for: network, graph, friend, neighbor, link, message, recommend, influence
- Distinctive: line 70
Look for: bucket, hash, experiment_id, variant, flag, feature_flag, rollout
- Very specific: line 120
Write the diagram to: temp/exp-lens-unit-interference/exp_diag_unit_interference_{YYYY-MM-DD_HHMMSS}.md
- Distinctive: line 165
TREAT["Treatment Units<br/>━━━━━━━━━━<br/>receive variant"] CTRL["Control Units<br/>━━━━━━━━━━<br/>receive baseline"] end
- Distinctive: line 244
Before creating the diagram, verify:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Unit Interference Experimental Design Lens
Philosophical Mode: Causal-Structural Primary Question: "What is the unit, and can treatments spill over?" Focus: Experimental Unit, Cluster Structure, Shared Resources, Network Effects, SUTVA Violations
When to Use
- Online A/B tests with shared infrastructure
- Distributed systems where units share caches, queues, or services
- Social or network experiments where units are connected
- User invokes
/exp-lens-unit-interferenceor/make-experiment-diag unit
Critical Constraints
NEVER:
- Modify any source code files
- Do not litter the codebase with useless comments, TODO markers, or explanatory annotations — the skill output and diagram speak for themselves
ALWAYS:
- Focus on the unit definition and whether SUTVA is plausible
- Map the full unit-cluster-resource hierarchy before assessing interference
- Identify every shared resource that could transmit treatment effects across groups
- Distinguish direct spillover (shared cache) from indirect spillover (market equilibrium)
- BEFORE creating any diagram, LOAD the
/mermaidskill using the Skill tool - this is MANDATORY
Analysis Workflow
Step 1: Launch Parallel Exploration Subagents
Spawn Explore subagents to investigate:
Unit Definition
- Find what constitutes one experimental unit
- Is it a user, request, session, query, item, sample, trial, or instance?
- Look for: user, request, session, query, item, sample, trial, instance
Cluster & Group Structure
- Find groupings of units that might share treatment effects
- Identify natural clustering that predates treatment assignment
- Look for: cluster, group, shard, server, region, batch, household, team
Shared Resources
- Find infrastructure shared across treatment groups
- Identify components both treatment and control units touch
- Look for: cache, queue, pool, database, service, load_balancer, gpu, memory
Network & Social Connections
- Find connections between units that could transmit treatment effects
- Identify paths by which a treated unit could alter a control unit's experience
- Look for: network, graph, friend, neighbor, link, message, recommend, influence
Treatment Assignment Boundary
- Find where the treatment boundary is drawn
- Identify whether the assignment is at the unit level or a coarser level
- Look for: bucket, hash, experiment_id, variant, flag, feature_flag, rollout
Step 2: Map the Unit-Cluster-Resource Hierarchy
For each level of the hierarchy:
- Can treatment at one level affect outcomes at another?
- Identify specific spillover pathways between levels
- Assess whether SUTVA (stable unit treatment value assumption) is plausible at each level
Document:
- Unit Level: The atomic entity receiving treatment
- Cluster Level: Natural groupings of units with shared context
- System Level: Infrastructure shared across all groups
Step 3: Analyze Interference Pathways
CRITICAL — Analyze Interference Pathways: For every shared resource or connection:
- Could treatment group A's behavior change the experience of control group B?
- Is this interference direct (shared cache hit rates) or indirect (market-level equilibrium effects)?
- What is the likely magnitude: negligible, moderate, or invalidating?
- Is there a mitigation strategy (cluster-level randomization, holdout, depletion correction)?
Rate each pathway:
- HIGH: Interference almost certainly contaminates the control group
- MEDIUM: Plausible interference under realistic usage patterns
- LOW: Theoretical but unlikely to affect measured outcomes
Step 4: Create the Diagram
Use flowchart with:
Direction: TB (units nested within clusters nested within the system)
Subgraphs:
- "EXPERIMENTAL UNITS" (the atomic entities being randomized)
- "CLUSTER STRUCTURE" (groupings above the unit level)
- "SHARED RESOURCES" (infrastructure accessible by both groups)
- "INTERFERENCE PATHWAYS" (explicit spillover routes)
Node Styling:
cliclass: Experimental unitsphaseclass: Cluster / group nodesstateNodeclass: Shared resourcesgapclass: Interference pathwayshandlerclass: Treatment assignmentdetectorclass: SUTVA boundary
Step 5: Write Output
Write the diagram to: temp/exp-lens-unit-interference/exp_diag_unit_interference_{YYYY-MM-DD_HHMMSS}.md
Output Template
# Unit Interference Diagram: {System / Experiment Name}
**Lens:** Unit Interference (Causal-Structural)
**Question:** What is the unit, and can treatments spill over?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}
## Unit Hierarchy
| Level | Count | Shared Resources | Interference Risk |
|-------|-------|-----------------|-------------------|
| {unit level} | {N} | {resources} | {LOW / MEDIUM / HIGH} |
| {cluster level} | {N} | {resources} | {LOW / MEDIUM / HIGH} |
| {system level} | {N} | {resources} | {LOW / MEDIUM / HIGH} |
## Unit-Cluster Diagram
```mermaid
%%{init: {'flowchart': {'nodeSpacing': 40, 'rankSpacing': 50, 'curve': 'basis'}}}%%
flowchart TB
%% CLASS DEFINITIONS %%
classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
classDef gap fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#000;
classDef integration fill:#c62828,stroke:#ef9a9a,stroke-width:2px,color:#fff;
subgraph Assignment ["TREATMENT ASSIGNMENT"]
ASSIGN["Assignment Logic<br/>━━━━━━━━━━<br/>hash / flag / bucket"]
SUTVA{"SUTVA<br/>Boundary<br/>plausible?"}
end
subgraph Units ["EXPERIMENTAL UNITS"]
direction TB
TREAT["Treatment Units<br/>━━━━━━━━━━<br/>receive variant"]
CTRL["Control Units<br/>━━━━━━━━━━<br/>receive baseline"]
end
subgraph Clusters ["CLUSTER STRUCTURE"]
direction TB
CL_T["Treatment Cluster<br/>━━━━━━━━━━<br/>shared context"]
CL_C["Control Cluster<br/>━━━━━━━━━━<br/>shared context"]
end
subgraph Shared ["SHARED RESOURCES"]
direction TB
RES1["Shared Cache<br/>━━━━━━━━━━<br/>cross-group access"]
RES2["Shared Queue<br/>━━━━━━━━━━<br/>cross-group access"]
end
subgraph Interference ["INTERFERENCE PATHWAYS"]
direction TB
PATH1["Spillover Path 1<br/>━━━━━━━━━━<br/>mechanism + magnitude"]
PATH2["Spillover Path 2<br/>━━━━━━━━━━<br/>mechanism + magnitude"]
end
%% ASSIGNMENT %%
ASSIGN --> TREAT
ASSIGN --> CTRL
ASSIGN --> SUTVA
%% CLUSTER NESTING %%
TREAT --> CL_T
CTRL --> CL_C
%% SHARED RESOURCE ACCESS %%
CL_T --> RES1
CL_C --> RES1
CL_T --> RES2
CL_C --> RES2
%% INTERFERENCE %%
RES1 -.->|"spillover"| PATH1
RES2 -.->|"spillover"| PATH2
PATH1 -.->|"contaminates"| CTRL
PATH2 -.->|"contaminates"| CTRL
%% CLASS ASSIGNMENTS %%
class TREAT,CTRL cli;
class CL_T,CL_C phase;
class RES1,RES2 stateNode;
class PATH1,PATH2 gap;
class ASSIGN handler;
class SUTVA detector;Color Legend:
| Color | Category | Description |
| Dark Blue | Units | Experimental units receiving treatment or control |
| Purple | Clusters | Cluster / group nodes above the unit level |
| Dark Teal | Shared Resources | Infrastructure accessible by both groups |
| Yellow | Interference | Spillover and contamination pathways |
| Orange | Assignment | Treatment assignment logic |
| Red | SUTVA Boundary | Plausibility check for the independence assumption |
Interference Pathway Analysis
| Source | Mechanism | Magnitude Estimate | Mitigation |
| {resource} | {how spillover occurs} | {negligible / moderate / invalidating} | {strategy} |
SUTVA Assessment
- Independence assumption: {plausible / violated / unknown}
- Identified violations: {list specific pathways or "none detected"}
- Recommended mitigation: {cluster randomization / geo holdout / none needed / further investigation}
---
## Pre-Diagram Checklist
Before creating the diagram, verify:
- [ ] LOADED `/mermaid` skill using the Skill tool
- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)
- [ ] Diagram will include a color legend table
---
## Related Skills
- `/make-experiment-diag` - Parent skill for experimental lens selection
- `/mermaid` - MUST BE LOADED before creating diagram
- `/exp-lens-causal-assumptions` - For DAG-level causal structure analysis
- `/exp-lens-randomization-blocking` - For randomization strategy and blocking designDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

