agentleFS
ai-analyst-labai-analyst-lab/ai-analyst/.claude/skills/runs/SKILL.md

runs

Skill304 starsChanged 2 months agoMITView on GitHub

Browse, inspect, compare, and clean up past pipeline runs. This skill is your window into analysis history — every `/run-pipeline` execution creates a tracked run with its own working directory, outputs, and state. Use this skill whenever the user wants to see what analyses have been executed, review past work, compare different approaches to the same problem, or clean up old runs. Trigger on phrases like "/runs", "show me my past analyses", "what pipeline runs do I have?", "list my pipeline runs", "show run history", "what did we analyze last week?", "compare these two analyses", "clean up old runs", "show me the latest run", "what was that analysis we did on [dataset]?", "review past work", "show me completed analyses", or any mention of viewing, listing, comparing, or managing previous pipeline executions. Also trigger when users reference a specific analysis by date or dataset name and want to see its details. This skill provides critical context for iterative analytical work — users often need to revisit, compare, or build on previous analyses rather than starting from scratch every time.

  • Deletes or force-pushes

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

26 rules. About 0 are common, 14 are distinctive, and 12 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈14

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When the user wants to see what analyses have been executed

    line 33
  2. Distinctive:

    This command requires scanning BOTH sources: Follow this exact sequence:

    line 57
  3. Very specific:

    Check if directory exists: ls working/runs/

    line 60
  4. Distinctive:

    If missing or empty, note "No active pipeline runs found"

    line 61
  5. Distinctive:

    If present, list subdirectories

    line 62
  6. Very specific:

    Read pipeline_state.json to extract:

    line 64
  7. Very specific:

    If pipeline_state.json is missing/corrupted, infer:

    line 68
  8. Very specific:

    Check if file exists: ls .knowledge/analyses/index.yaml

    line 73
  9. Distinctive:

    If missing, note "No archived analyses found"

    line 74
  10. Very specific:

    If present, read .knowledge/analyses/index.yaml

    line 75
  11. Very specific:

    If the same analysis appears in both (check by date + dataset + title match), show it once with status from working/runs/ (more current)

    line 82
  12. Very specific:

    If working/runs/ doesn't exist: Show only archived analyses with note "No active runs found.

    line 109
  13. Very specific:

    If .knowledge/analyses/index.yaml doesn't exist: Show only active runs with note "No archived analyses yet."

    line 110
  14. Distinctive:

    If both are missing: "No analyses found.

    line 111
  15. Very specific:

    Read the working/latest symlink to determine which run is latest:

    line 115
  16. Very specific:

    If working/latest doesn't exist: "No active pipeline runs found.

    line 127
  17. Distinctive:

    If symlink is broken: "Latest run symlink is broken.

    line 128
  18. Very specific:

    If the run has a validation report in outputs/ or working/, extract and show the confidence grade.

    line 157
  19. Distinctive:

    If no match found: "No run matching '{id}' found.

    line 160
  20. Distinctive:

    If multiple matches: List all matches and ask user to be more specific

    line 161
  21. Very specific:

    If working/latest pointed to a deleted run, remove the symlink

    line 175
  22. Distinctive:

    If no old runs found: "No runs older than 30 days found.

    line 178
  23. Distinctive:

    If both runs analyzed the same dataset, also compare:

    line 205
  24. Distinctive:

    If either ID doesn't match: "Cannot find run '{id}'.

    line 210
  25. Distinctive:

    If partial match is ambiguous: List matches and ask user to be more specific

    line 211
  26. Distinctive:

    Partial match ambiguity: If multiple runs match, list them and ask user to be more specific: "Multiple runs match '{id}': [list].

    line 217

≈ “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.

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

Skill: Runs

Purpose

Browse, inspect, compare, and clean up past pipeline runs. Each run is a self-contained directory under working/runs/ with its own working files, outputs, and pipeline state.

Architecture: Understanding the Two-Source System

The AI Analyst tracks analysis work in two independent locations:

  1. Active Pipeline Runs (working/runs/)
    • Contains in-progress, recently completed, or failed pipeline executions
    • Each run is a directory with pipeline_state.json tracking agent progress
    • Used for resuming interrupted work and debugging issues
    • Cleaned up periodically (30-day retention by default)
  2. Archived Analyses (.knowledge/analyses/)
    • Contains completed analyses that have been formally archived
    • Includes validation grades, key findings, and links to outputs
    • Permanent knowledge base for organizational learning
    • Survives even after working/runs/ cleanup

Why this matters: A user asking "what analyses have I run?" expects to see BOTH in-progress work (working/runs/) AND completed archived work (.knowledge/analyses/). Missing either source gives an incomplete picture.

When to Use

  • User says /runs, /runs list, /runs latest, /runs clean, or /runs compare
  • When the user wants to see what analyses have been executed

Invocation

  • /runs or /runs list -- list all past runs
  • /runs latest -- show details of the most recent run
  • /runs {id} -- show details of a specific run (partial match supported)
  • /runs clean -- remove runs older than 30 days (confirmation required)
  • /runs compare {id1} {id2} -- compare two runs side by side

Instructions

Step 1: Determine Command Type

Parse the user's command to understand which operation they want:

  • List: /runs or /runs list → requires dual-source scanning
  • Latest: /runs latest → single source (working/latest symlink)
  • Detail: /runs {id} → single source (working/runs/)
  • Compare: /runs compare {id1} {id2} → single source (working/runs/)
  • Clean: /runs clean → single source (working/runs/)

Step 2: Execute Based on Command Type

List Command (/runs or /runs list)

This command requires scanning BOTH sources. Follow this exact sequence:

  1. Scan Source 1: Active Pipeline Runs (working/runs/)
    • Check if directory exists: ls working/runs/
    • If missing or empty, note "No active pipeline runs found"
    • If present, list subdirectories
    • For each run directory (format: {YYYY-MM-DD}_{DATASET}_{SHORT_TITLE}/):
      • Read pipeline_state.json to extract:
        • pipeline_id, dataset, question, status
        • started_at, completed_at
        • steps (agent status map to compute completed/total counts)
      • If pipeline_state.json is missing/corrupted, infer:
        • Status: unknown
        • Date/dataset from directory name
  2. Scan Source 2: Archived Analyses (.knowledge/analyses/)
    • Check if file exists: ls .knowledge/analyses/index.yaml
    • If missing, note "No archived analyses found"
    • If present, read .knowledge/analyses/index.yaml
    • Extract for each analysis:
      • id, date, dataset, title, status, validation_grade, key_findings
    • Note: Archived analyses may not have agent counts (show "N/A" if unavailable)
  3. Merge and Deduplicate
    • Combine results from both sources
    • If the same analysis appears in both (check by date + dataset + title match), show it once with status from working/runs/ (more current)
  4. Display Merged Table

Display TWO sections sorted by date descending:

## Active Pipeline Runs (working/runs/)

| # | Date       | Dataset   | Title                    | Status    | Agents |
|---|------------|-----------|--------------------------|-----------|--------|
| 1 | 2026-02-23 | acme-analytics | why-revenue-dropped-q3   | completed | 14/14  |
| 2 | 2026-02-21 | acme-analytics | activation-funnel-deep   | failed    | 8/14   |

## Archived Analyses (.knowledge/analyses/)

| # | Date       | Dataset   | Title                    | Grade | Status    |
|---|------------|-----------|--------------------------|-------|-----------|
| 1 | 2026-02-19 | hero      | churn-by-segment         | A     | completed |
| 2 | 2026-02-15 | hero      | feature-impact-nov       | B+    | completed |

Total: {N} runs found. Use `/runs {#}` or `/runs {title}` for details.

The Agents column shows {completed}/{total} from the pipeline_state steps map.

Error handling:

  • If working/runs/ doesn't exist: Show only archived analyses with note "No active runs found. Use /run-pipeline to create one."
  • If .knowledge/analyses/index.yaml doesn't exist: Show only active runs with note "No archived analyses yet."
  • If both are missing: "No analyses found. Use /run-pipeline to start your first analysis."

Latest Command (/runs latest)

Read the working/latest symlink to determine which run is latest:

# Read the symlink target
ls -l working/latest
# Or use readlink if available
readlink working/latest

The symlink points to a run directory (e.g., working/runs/2026-04-03_<dataset>_checkout-feature-impact/). Extract the run directory name from the symlink target and display the detail view for that run (same format as /runs {id} below).

Error handling:

  • If working/latest doesn't exist: "No active pipeline runs found. Use /run-pipeline to start one."
  • If symlink is broken: "Latest run symlink is broken. Use /runs list to see available runs."

Detail Command (/runs {id})

Match {id} against run directory names (supports partial match -- e.g., /runs acme-analytics matches the most recent acme-analytics run). Display:

Run: {directory_name}
Status: {status}
Dataset: {dataset}
Question: {question}
Started: {started_at}
Completed: {completed_at} ({duration})

Agent Status:
  completed: {list}
  failed: {list with errors}
  skipped: {list}
  pending: {list}

Output Files:
  - {RUN_DIR}/outputs/{file1}
  - {RUN_DIR}/outputs/{file2}
  ...

Confidence: {grade from validation if available}

If the run has a validation report in outputs/ or working/, extract and show the confidence grade.

Error handling:

  • If no match found: "No run matching '{id}' found. Use /runs list to see available runs."
  • If multiple matches: List all matches and ask user to be more specific

Clean Command (/runs clean)

  1. Scan working/runs/ for runs older than 30 days (based on directory date prefix)
  2. List them and ask for confirmation:
    Found {N} runs older than 30 days:
      - {dir1} (completed, {date})
      - {dir2} (failed, {date})
    
    Delete these runs? This cannot be undone. [y/N]
  3. On confirmation, remove the directories using rm -rf
  4. If working/latest pointed to a deleted run, remove the symlink

Error handling:

  • If no old runs found: "No runs older than 30 days found. Nothing to clean."

Compare Command (/runs compare {id1} {id2})

  1. Match {id1} and {id2} against run directory names (partial match supported)
  2. Load pipeline_state.json from both runs
  3. Optionally load key output files (analysis reports, validation reports) if available

Display comparison table:

Comparing Runs:
  A: {dir1}
  B: {dir2}

| Dimension          | Run A              | Run B              |
|--------------------|--------------------|--------------------|
| Date               | {date_a}           | {date_b}           |
| Dataset            | {dataset_a}        | {dataset_b}        |
| Status             | {status_a}         | {status_b}         |
| Agents completed   | {count_a}          | {count_b}          |
| Confidence grade   | {grade_a}          | {grade_b}          |
| Charts generated   | {chart_count_a}    | {chart_count_b}    |
| Key findings       | {finding_count_a}  | {finding_count_b}  |
| Duration           | {duration_a}       | {duration_b}       |

If both runs analyzed the same dataset, also compare:

  • Top 3 findings from each (extracted from analysis reports in outputs/)
  • Any metrics that differ significantly

Error handling:

  • If either ID doesn't match: "Cannot find run '{id}'. Use /runs list to see available runs."
  • If partial match is ambiguous: List matches and ask user to be more specific

Edge Cases

  • No runs directory: Report "No pipeline runs found. Use /run-pipeline to start one."
  • Empty runs directory: Same message as above
  • Corrupted pipeline_state.json: Show run with status: unknown, note the error: "Warning: pipeline_state.json is corrupted or unreadable"
  • Partial match ambiguity: If multiple runs match, list them and ask user to be more specific: "Multiple runs match '{id}': [list]. Please specify."
  • Legacy runs (no run directory): Note: "Found legacy working/pipeline_state.json -- not in per-run format. Use /run-pipeline to create a tracked run."

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.