agentleFS
TrecekTrecek/useful-claude-skills/.claude/skills/exp-lens-comparator-construction/SKILL.md

exp-lens-comparator-construction

Skill1 starsChanged 8 months agoMITView on GitHub

Create Comparator Construction experimental design analysis assessing whether baselines and controls are fair and relevant. Counterfactual lens answering "Is the comparator fair and relevant?

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 9 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    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
  1. Distinctive:

    Do not litter the codebase with useless comments, TODO markers, or explanatory annotations — the skill output and diagram speak for …

    line 30
  2. Distinctive:

    Check for confounding differences in implementation, tuning, data access, and compute

    line 35
  3. Very specific:

    BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY

    line 38
  4. Distinctive:

    Look for: baseline, control, comparison, prior, state-of-the-art, vanilla, default, reference

    line 50
  5. Distinctive:

    Look for: reproduce, reimplement, original, paper, author, tuned, optimized, hyperparameter

    line 54
  6. Distinctive:

    Look for: version, library, framework, gpu, hardware, environment, checkpoint

    line 58
  7. Distinctive:

    Look for: tune, search, grid, optuna, sweep, budget, trials, epochs

    line 62
  8. Distinctive:

    Look for: date, published, year, updated, latest, deprecated, legacy

    line 66
  9. Distinctive:

    If a diagram adds value, create a simplified flowchart.

    line 88
  10. Very specific:

    Write the analysis to: temp/exp-lens-comparator-construction/exp_diag_comparator_construction_{YYYY-MM-DD_HHMMSS}.md

    line 104
  11. Distinctive:

    Before creating the diagram, verify:

    line 204

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Comparator Construction Experimental Design Lens

Philosophical Mode: Counterfactual Primary Question: "Is the comparator fair and relevant?" Focus: Baseline Choice, Control Realism, Version Matching, Effort Symmetry, Baseline Drift

When to Use

  • Benchmark comparisons where baseline quality is questioned
  • Ablation studies needing fair controls
  • Claims of improvement over prior work
  • User invokes /exp-lens-comparator-construction or /make-experiment-diag comparator

Critical Constraints

NEVER:

  • Modify any source code or experiment files
  • Do not litter the codebase with useless comments, TODO markers, or explanatory annotations — the skill output and diagram speak for themselves
  • Accept at face value that baselines received symmetric treatment

ALWAYS:

  • Build a fairness matrix covering all treatment-vs-comparator pairs
  • Check for confounding differences in implementation, tuning, data access, and compute
  • Assess whether each comparator is the best available alternative at the time of the experiment
  • Identify temporal drift in baseline relevance
  • BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY

Analysis Workflow

Step 1: Launch Parallel Exploration Subagents

Spawn Explore subagents to investigate:

Baseline/Control Definitions

  • Find what the proposed method is compared against
  • Look for: baseline, control, comparison, prior, state-of-the-art, vanilla, default, reference

Implementation Parity

  • Find whether baselines get equal engineering effort
  • Look for: reproduce, reimplement, original, paper, author, tuned, optimized, hyperparameter

Version & Environment Match

  • Find whether baselines use the same software/hardware environment
  • Look for: version, library, framework, gpu, hardware, environment, checkpoint

Tuning Protocol Symmetry

  • Find whether hyperparameter tuning is symmetric
  • Look for: tune, search, grid, optuna, sweep, budget, trials, epochs

Temporal Baseline Drift

  • Find whether baselines have been updated or are stale
  • Look for: date, published, year, updated, latest, deprecated, legacy

Step 2: Build the Comparator Inventory

For each comparator, assess:

  1. Is it the best available alternative?
  2. Is it given equal engineering effort?
  3. Is it run in the same environment?
  4. Is the tuning budget symmetric?
  5. Has it drifted since originally published?

Step 3: Construct the Fairness Matrix

CRITICAL — Analyze Counterfactual Quality: For each treatment-vs-comparator pair:

  • Does the comparison isolate the intended factor?
  • Are there confounding differences in implementation, tuning, data access, or compute?

Build a fairness matrix with rows = comparators, columns = fairness dimensions.

Step 4: Create the Optional Comparison Diagram

If a diagram adds value, create a simplified flowchart. This is OPTIONAL for this hybrid lens — the tables are the primary output.

Direction: LR (treatment and comparator flow in parallel toward evaluation)

Subgraphs: "PROPOSED METHOD", "COMPARATOR(S)", "SHARED EVALUATION"

Node Styling:

  • cli class: proposed method nodes
  • phase class: comparator method nodes
  • handler class: shared evaluation pipeline nodes
  • output class: results nodes
  • gap class: asymmetries flagged
  • detector class: parity checks

Step 5: Write Output

Write the analysis to: temp/exp-lens-comparator-construction/exp_diag_comparator_construction_{YYYY-MM-DD_HHMMSS}.md


Output Template

# Comparator Construction Analysis: {Experiment Name}

**Lens:** Comparator Construction (Counterfactual)
**Question:** Is the comparator fair and relevant?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}

## Comparator Inventory

| Comparator | Source | Reimplemented? | Same Environment? | Same Tuning Budget? |
|------------|--------|---------------|-------------------|---------------------|
| {name} | {paper/repo} | Yes / No / Partial | Yes / No | Yes / No / Unknown |

## Fairness Matrix

| Comparator | Best Available? | Equal Effort? | Same Env? | Symmetric Tuning? | Temporally Current? |
|------------|----------------|--------------|-----------|-------------------|---------------------|
| {name} | Yes / No | Yes / No | Yes / No | Yes / No | Yes / No |

## Comparison Diagram (Optional)

```mermaid
%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart LR
    %% 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 Proposed ["PROPOSED METHOD"]
        METHOD["Proposed Method<br/>━━━━━━━━━━<br/>{method name}"]
    end

    subgraph Comparators ["COMPARATOR(S)"]
        COMP1["Comparator 1<br/>━━━━━━━━━━<br/>{name}"]
        COMP2["Comparator 2<br/>━━━━━━━━━━<br/>{name}"]
    end

    subgraph Evaluation ["SHARED EVALUATION"]
        EVAL["Evaluation Pipeline<br/>━━━━━━━━━━<br/>{dataset/benchmark}"]
        RESULTS["Results<br/>━━━━━━━━━━<br/>{metrics reported}"]
        PARITY["Parity Check<br/>━━━━━━━━━━<br/>{asymmetry found}"]
        ASYM["Asymmetry<br/>━━━━━━━━━━<br/>{description}"]
    end

    METHOD -->|"evaluated on"| EVAL
    COMP1 -->|"evaluated on"| EVAL
    COMP2 -->|"evaluated on"| EVAL
    EVAL --> RESULTS
    RESULTS --> PARITY
    PARITY -.->|"flagged"| ASYM

    class METHOD cli;
    class COMP1,COMP2 phase;
    class EVAL handler;
    class RESULTS output;
    class PARITY detector;
    class ASYM gap;

Color Legend:

ColorCategoryDescription
Dark BlueProposed MethodThe method being evaluated
PurpleComparatorsBaselines and controls
OrangeEvaluationShared evaluation pipeline
Dark TealResultsReported outcomes
RedParity ChecksFairness verification points
YellowAsymmetriesFlagged unfair differences

Asymmetry Register

#AsymmetryAffectsImpact AssessmentRemediation
1{description}{comparator(s)}High / Medium / Low{how to fix}

Recommendations

  1. {Most critical fairness fix — e.g., retune baseline with same budget}
  2. {Version alignment or environment standardization needed}
  3. {Additional comparator that should be included}

---

## 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 lens selection
- `/mermaid` - MUST BE LOADED before creating diagram
- `/exp-lens-estimand-clarity` - For clarifying what the comparison is measuring
- `/exp-lens-fair-comparison` - For deeper analysis of evaluation protocol fairness

Download now (ZIP)

Does 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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.