skill-validate

# Skill Validator

**Core responsibility:** Verify that a SKILL.md is structurally correct, follows all Lattice tier conventions, and composes correctly with the rest of the framework.

**Input:** One or more of:
- A file path: `skills/atoms/clean-code/SKILL.md`
- A skill name: `clean-code` (resolves to the correct path automatically)
- A tier: `atoms` (validates all skills in that tier)
- No argument: validates all skills across all three tiers (count derived from `skills/` at runtime — never hardcoded)

**Output:** A findings report per skill:
```
## Skill Validator — {skill-name}
Tier: {atom | molecule | refiner}

### Structural          PASS / FAIL — specific findings
### Tier conventions    PASS / FAIL — specific findings
### Cross-references    PASS / FAIL — specific findings
### Three-angle review  PASS / WARN / FAIL per lens

Result: PASS | FAIL (N errors, M warnings)
```

**How to verify this skill did its job:**
- Every finding references a specific file and section (no vague "missing content" — says exactly what is missing and where)
- FAIL findings have an actionable fix, not just a description of the problem
- The report distinguishes errors (must fix) from warnings (judgment calls)
- After "fix mode" is applied, re-running the validator returns PASS

Validates one or more Lattice SKILL.md files against all conventions. Always reads conventions from `CLAUDE.md` — never from memory.

## Step 1: Load conventions

Read `CLAUDE.md` — Skill Conventions section. This is the source of truth. Do not rely on memory.

Read `references/convention-rules.md` for the detailed per-tier checklist.

## Step 2: Run structural checks (all tiers)

For every SKILL.md being validated:

```
[ ] Frontmatter: name field present, lowercase-hyphenated
[ ] Frontmatter: description field present and non-empty
[ ] Frontmatter: description contains trigger phrases (what the user would type)
[ ] Folder name matches name field exactly
[ ] No inline atom content in molecules (no duplicating what framework:{atom} already provides)
```

## Step 3: Run tier-specific checks

Read `references/convention-rules.md` for the full per-tier checklist. Apply the relevant section based on tier (determined from file path: atoms/, molecules/, refiners/).

## Step 4: Run cross-reference checks

For every `framework:{atom-name}` reference in a molecule:
```bash
ls skills/atoms/{atom-name}/SKILL.md 2>/dev/null || echo "BROKEN REF: framework:{atom-name}"
```

For every `paths.{key}` config key referenced in a refiner or atom:
- Check it appears in `docs/configuration.md` paths table

For every `.lattice/{subfolder}/` path referenced in a molecule:
- Check that subfolder is in the known subfolders list in `CLAUDE.md`

## Step 5: Three-angle structural review

These three lenses are fixed — they match the three stakeholder types who depend on Lattice skills working correctly. This is a structural review (does the skill follow conventions?), not a behavioral review (does it work in practice?) — use `skill-review` for the latter.

Each lens asks a different question:

**Product Owner lens** — "Will this produce the right output for its users?"
- If a molecule: does the output document structure (from the SKILL.md template) give a PO a clear picture of what was produced?
- If an atom: are the quality checks grounded in real user need, not just technical form?
- If a refiner: does the produced standards document solve the configuration problem the user has?

**Business Analyst / Practitioner lens** — "Are the rules complete and enforceable?"
- Are checklists specific enough to have a clear pass/fail for each item?
- Are anti-patterns named with a fix, not just a symptom?
- Are ambiguity signals genuinely ambiguous, or are they just gaps in the rules?
- For molecules: are all practical scenarios handled (fresh start, existing material, interrupted session, single-item request)?

**Technical Lead lens** — "Does this compose correctly with the rest of the framework?"
- Do atom references (`framework:{name}`) resolve to real skills?
- Do config keys follow snake_case and match what's in configuration.md?
- Does the molecule write to a named `.lattice/` subfolder (never root)?
- For planning molecules: is the session resume check present at Step 1?
- For generative molecules: are there no confirmation gates?

## Step 6: Report

Format findings as:

```
## Skill Validator — {skill-name}
Tier: {atom | molecule | refiner}

### Structural
PASS — all structural checks clean

### Tier conventions
FAIL — [Atom] Self-Validation Checklist missing STOP language on check 3
FAIL — [Molecule] Planning molecule Step 2 has no confirmation gate

### Cross-references
PASS — all framework: references resolve

### Three-angle review
[PO]   PASS
[BA]   WARN — Scenario: no guidance for interrupted session (resume behavior)
[Tech] FAIL — .lattice/myoutput/ is not in CLAUDE.md known subfolders list

---
Result: FAIL (2 errors, 1 warning)
Fix errors before writing to the repo. Warnings are judgment calls.
```

Distinguish errors (must fix) from warnings (should consider).

## Step 7: Fix mode (optional)

If the user says "fix it" or "apply fixes" — apply all error-level findings directly to the files. Re-run validation after fixes. Do not fix warnings without asking which ones to apply.