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:
source/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
source/ 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
Step 1: Load conventions
Read PROJECT.md — Skill Conventions section. This is the source of truth. STOP: 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:
ls source/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 <!-- include: {name} --> line:
ls source/shared/{name}.md 2>/dev/null || echo "BROKEN INCLUDE: {name}"
For every .lattice/{subfolder}/ path referenced in a molecule:
- Check that subfolder is in the known subfolders list in
PROJECT.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
STOP: a passing category gets the bare word PASS — no restated commentary; findings text only on FAIL/WARN. Format findings as:
## Skill Validator — {skill-name}
Tier: {atom | molecule | refiner}
### Structural
PASS
### 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
### Three-angle review
[PO] PASS
[BA] WARN — no guidance for interrupted session (resume behavior)
[Tech] FAIL — .lattice/myoutput/ not in known subfolders list
---
Result: FAIL (2 errors, 1 warning)
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. STOP: do not fix warnings without asking which ones to apply.