Validate pipeline

Validate Pipeline Skill

Walks the full contract chain of an ICM pipeline and validates that stages connect correctly. Finds broken handoffs, mixed reference/working files, and structural anti-patterns.

Trigger

Use this skill when:

• The user asks to validate, verify, or check a pipeline's structure
• The user says "validate pipeline", "check contracts", "verify handoffs", "are my stages connected?"
• The user just ran /pipeline-scaffold and wants to verify the result
• A /run-stage execution failed because of missing inputs

Procedure

Step 1: Discover Stages

Find all numbered stage folders:

ls -d [0-9][0-9]_*/ 2>/dev/null || ls -d stages/[0-9][0-9]_*/ 2>/dev/null

Sort by numeric prefix. If no stages found, halt: "No pipeline stages found. This skill validates ICM pipelines with numbered stage folders (01_name/, 02_name/, etc.)."

Record:

• Total stage count
• Stage names and paths
• Whether _config/ or shared/ directories exist

Step 2: Read All Contracts

For each stage, read its CONTEXT.md. Parse and record:

• Inputs table — file names, source paths, Layer designations
• Process section — present/absent, instruction count
• Outputs table — file names, destination paths, formats
• Review Checkpoint — present/absent

Flag any stage missing a CONTEXT.md entirely.

Step 3: Validate Contract Chain

For each consecutive pair of stages (N, N+1):

3a: Output-to-Input matching

• For every file in stage N+1's Inputs that sources from stage N's output/: verify that stage N's Outputs table declares that file.
• Flag mismatches as broken handoffs: "Stage {N+1} expects {file} from stage {N}, but stage {N} doesn't declare it as an output."

3b: Name consistency

• Check that file names match exactly between the upstream Output and downstream Input declarations.
• Flag near-misses: "Stage {N} outputs research_notes.md but stage {N+1} expects research-notes.md."

3c: Format compatibility

• If stage N declares an output format (e.g., "JSON") and stage N+1's Process expects a different format (e.g., "markdown"), flag it.

Record results per handoff: Pass (all inputs satisfied), Warning (near-misses), or Fail (missing outputs).

Step 4: Check Factory/Product Separation

4a: Directory structure

• Does each stage have a references/ directory (or equivalent for Layer 3)?
• Does each stage have an output/ directory (for Layer 4)?
• Does _config/ exist at the pipeline root for shared reference material?

4b: Layer labeling

• Do Inputs tables distinguish Layer 3 (reference) from Layer 4 (working)?
• Flag any Inputs table that has no Layer column.

4c: No cross-contamination

• Are reference files (in references/, _config/) free of per-run output?
• Are output files (in output/) free of stable configuration?
• Does any stage write to another stage's references/ folder? (This should never happen.)

Step 5: Check Pipeline Anti-Patterns

#	Anti-Pattern	How to detect
1	Monolithic stage	One stage has 8+ Process instructions or produces 5+ output files
2	Missing output folders	Stage folder has no output/ directory
3	Mixed reference and working	references/ contains dated/versioned files, or output/ contains style guides
4	No Inputs table	Stage CONTEXT.md has Process and Outputs but no Inputs table
5	Forward dependency	Stage N reads from stage N+2 or later (skips the chain)
6	Over-staged	3+ consecutive stages with only 1-2 Process instructions each

Step 6: Generate Validation Report

# Pipeline Validation: {Pipeline Name}
**Date:** {today}
**Path:** {pipeline root}
**Stages:** {count}

## Chain Validation

| Handoff | From | To | Status |
|---------|------|----|--------|
| 1 | 01_{name} | 02_{name} | [Pass/Warning/Fail] |
| 2 | 02_{name} | 03_{name} | [Pass/Warning/Fail] |
| ... | ... | ... | ... |

### Broken Handoffs
{List each with: what's missing, which file, suggested fix}

### Near-Misses
{List each with: the name mismatch and suggested correction}

## Factory/Product Separation

| Check | Status |
|-------|--------|
| Stage `references/` directories | [Present/Missing] |
| Stage `output/` directories | [Present/Missing] |
| Root `_config/` directory | [Present/Missing] |
| Inputs tables have Layer column | [Yes/Partial/No] |
| No cross-contamination | [Clean/Issues found] |

## Anti-Patterns Found

{List each found with a one-line fix, or "None found" if clean}

## Contract Completeness

| Stage | CONTEXT.md | Inputs | Process | Outputs | Checkpoint |
|-------|-----------|--------|---------|---------|------------|
| 01_{name} | [Yes/No] | [Yes/No] | [Yes/No] | [Yes/No] | [Yes/No] |
| ... | ... | ... | ... | ... | ... |

## Suggested Fixes

1. {Most critical fix — what to change and in which file}
2. {Second fix}
3. {Third fix}

Step 7: Offer to Fix

For each broken handoff or missing contract section, offer to apply the fix directly:

• Missing Output declaration → add the file to stage N's Outputs table
• Name mismatch → rename in the downstream Inputs table to match upstream
• Missing Layer column → add Layer designations to the Inputs table
• Missing CONTEXT.md section → generate a template section

Always ask before modifying any CONTEXT.md file.