---
name: support-skill-validator
description: "Use to validate skills, rules, agents, and commands for consistency — triggered by phrases like '/validate', 'validate the skills', 'check for contradictions', 'run consistency checks', 'audit the skill set', 'verify the I/O graph'. Walks frontmatter conformance, I/O contract gaps, naming conflicts, and drift between commands and the skills they invoke. Default mode is full-set scan; pass a target path or skill name for a focused scan. Skip when the edit is documentation-only (CHANGELOG, README, comments) with no impact on skill/agent/command frontmatter or routing."
---

# Support: Skill Validator

## Overview

As the forge harness grows -- skills added, rules promoted from gotchas, commands modified -- contradictions and gaps can creep in. This skill performs systematic validation to catch inconsistencies before they cause confusion or incorrect behavior.

**Core Principle:** A system that contradicts itself is worse than no system at all. Every directive must be unambiguous, every I/O chain must be connected, and every responsibility must have exactly one owner.

## When to Use

| Trigger | Validation Scope | Performance Target |
|---|---|---|
| `/validate` command | Full scan (all 5 checks) | Under 30 seconds |
| `/forge-evolve` modifies a skill | Pre-apply check (modified skill vs all others) | Under 10 seconds |
| Session start | Lightweight I/O graph check only | Under 3 seconds |
| Manual request | Full scan or targeted check | Depends on scope |
| After gotcha promotion | Promoted rule vs existing rules and skills | Under 10 seconds |

## When to load references

- **`references/validation-checks.md`** — full procedure for each of the 5 checks (directives, I/O graph, overlaps, gates, drift), with examples. Load this when actually running a scan.
- **`references/false-positives.md`** — known false-positive patterns and report-writing guidance. Load before writing a report so noise doesn't drown real findings.

## I/O Contract

| Field | Value |
|---|---|
| **Requires** | All `SKILL.md` files + all `rules/*.md` files + all `commands/*.md` files |
| **Produces** | Validation report (structured, actionable) |
| **Feeds into** | `/forge-evolve` command (fix contradictions before applying changes) |
| **Updates** | Nothing directly -- produces a report for human/AI action |

### Input Files

```
skills/
  */SKILL.md                -> All skill definitions
rules/
  common/*.md               -> Always-on rules
  {language}/*.md           -> Language-specific rules
references/
  common/*.md               -> On-demand references
commands/
  *.md                      -> Command definitions
agents/
  *.md                      -> Agent definitions
```

### Output Format

```
VALIDATION REPORT
=================
Timestamp: {ISO 8601}
Scope: {full | targeted | lightweight}
Files Scanned: {count}

CONFLICTS ({count}):
  {list of conflicts with file references and line context}

OVERLAPS ({count}):
  {list of responsibility overlaps}

I/O GAPS ({count}):
  {list of missing producers, orphaned outputs, circular deps}

GATE COVERAGE ({count of issues}):
  {list of undocumented gate exemptions}

DRIFT ({count}):
  {list of post-modification inconsistencies}

SUMMARY:
  Errors: {count}     (must fix before proceeding)
  Warnings: {count}   (should fix, may cause confusion)
  Info: {count}       (minor, for awareness)
```

## The Five Validation Checks

| # | Check | Catches | Severity range |
|---|---|---|---|
| 1 | **Directive Conflicts** | MUST vs NEVER contradictions across SKILL.md, rules, commands | ERROR – WARNING |
| 2 | **I/O Graph Integrity** | Missing producers, orphaned outputs, cycles in the produces→requires graph | INFO – ERROR |
| 3 | **Responsibility Overlaps** | Multiple skills/rules claiming the same responsibility | WARNING – INFO |
| 4 | **Gate Completeness** | Missing or vague quality gates on command transitions | ERROR – WARNING |
| 5 | **Post-Evolve Drift** | New inconsistencies introduced by a recent skill/rule modification | ERROR – INFO |

Full procedure, examples, and the I/O graph severity baseline for each check live in **`references/validation-checks.md`** — load that before running any check. Always pair with **`references/false-positives.md`** before writing the report.

## Validation Severity Levels

| Level | Meaning | Action Required |
|---|---|---|
| **ERROR** | Definite contradiction, broken pipeline, or missing producer that demonstrably blocks a downstream consumer (named skill, named artifact, observed failure path) | Must fix before the system can be relied upon |
| **WARNING** | Potential issue, ambiguity, or undocumented exception that a reasonable reader would misinterpret | Should fix to prevent confusion |
| **INFO** | Asymmetric metadata, intentional omission, layered enforcement, or correct-but-could-be-clearer | Fix when convenient, or document as intentional |

**Key rule:** Optional-by-rule fields (per `references/common/skill-authoring.md` — `Requires`/`Produces`/`Feeds into` are "Usually" not "Always") cannot generate ERROR or WARNING by their absence alone. They generate ERROR/WARNING only when their absence breaks a *named* downstream consumer.

## Integration Points

### /validate Command (Full Scan)

Run all 5 checks. Output the full VALIDATION REPORT (above). Target: under 30 seconds.

```
User: /validate
Running full validation...
Scanning: {N} skills, {N} common rules, {N} references, {N} language rule sets, {N} commands, {N} agents

VALIDATION REPORT
=================
[...]

SUMMARY:
  Errors: 0
  Warnings: 3
  Info: 1

No blocking errors. System is consistent.
Warnings should be reviewed when convenient.
```

### /forge-evolve Command (Pre-Apply Check)

Before `/forge-evolve` applies any skill modification:

1. Receive the proposed change
2. Apply the change to a temporary copy
3. Run targeted validation (Check 1 + Check 5)
4. If errors found: BLOCK the change, present the conflicts
5. If only warnings: WARN but allow (with user confirmation)
6. If clean: ALLOW the change

```
/forge-evolve proposes modifying build-tdd...

Pre-apply validation:
  [PASS] No directive conflicts
  [PASS] I/O graph intact
  [PASS] No new overlaps
  [PASS] Gate coverage maintained
  [PASS] No drift issues

Change is safe to apply.
```

### Session Start (Lightweight Check)

On session start, run only Check 2 (I/O Graph Integrity):

- Fast (reads I/O contracts only, not full file content)
- Catches broken connections from manual edits
- Reports only errors, suppresses warnings/info
- Target: under 3 seconds

```
Session start I/O check: All clear ({N} skills, 0 gaps)
```

### After Gotcha Promotion

When `support-gotcha` promotes a gotcha to a rule:

1. Receive the new rule text
2. Run Check 1 (does new rule contradict existing rules?)
3. Run Check 3 (does new rule overlap with existing skill responsibilities?)
4. Report results before the promotion is finalized

## Red Flags -- The Validator Itself Needs Validation

| Situation | Action |
|---|---|
| Validator reports 0 issues on a known-inconsistent system | Validator has a bug -- manual review needed |
| Validator reports 50+ errors | Likely false positives -- calibrate severity thresholds |
| Same finding appears in every report | Either a real systemic issue or a false positive pattern |
| Validator conflicts with itself | Meta-problem -- review validator logic |
| Report is longer than 100 lines | Too verbose -- summarize and link to details |

## Quick Reference

| Check | What It Catches | Severity Range |
|---|---|---|
| **1. Directives** | MUST vs NEVER contradictions | ERROR - WARNING |
| **2. I/O Graph** | Missing producers, orphaned outputs, cycles | INFO - ERROR (see Severity Baseline in `references/validation-checks.md`) |
| **3. Overlaps** | Multiple owners for same responsibility | WARNING - INFO |
| **4. Gates** | Missing or vague transition gates | ERROR - WARNING |
| **5. Drift** | Post-modification inconsistencies | ERROR - INFO |