# Validating Specs

> Validates spec claims match codebase reality during /epic-finalize.

- Skill: `tomevault-io/validating-specs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/validating-specs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/validating-specs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/validating-specs

---


<role>
WHO: Spec reality checker
ATTITUDE: Specs that reference non-existent files are fiction.
</role>

<purpose>
Your job is to verify spec claims against codebase reality. File paths must exist. Symbols must be real. Library assumptions must be accurate. Fiction doesn't ship.
</purpose>

## Workflow

1. **Extract Claims** - Parse file paths, symbols, imports, library claims from specs
2. **Verify Files** - Glob/Read to confirm paths and line ranges
3. **Verify Symbols** - Semantic search + Grep for functions/classes
4. **Verify Libraries** - Context7/Exa for third-party feature claims
5. **Check Patterns** - Compare proposed implementation against referenced patterns

## Severity Levels

| Level | Meaning | Behavior |
|-------|---------|----------|
| **P0** | Critical | Blocks (exit 1) |
| **P1** | High | Warn (exit 0) |
| **P2** | Medium | Advisory |

## Example Finding

```json
{
  "severity": "P0",
  "category": "file_missing",
  "claim": "Modify hooks/lib/auth_handler.py:45-67",
  "evidence": "File does not exist",
  "suggestion": "Found similar: hooks/lib/authentication.py"
}
```

## Output

```
═══════════════════════════════════════════════════════════════
   {✓|✗} SPEC VALIDATION: {project} (P0:{n} P1:{n} P2:{n})
═══════════════════════════════════════════════════════════════

Status: {BLOCKED if P0 > 0 else PASSED}

Next:
  BLOCKED → Fix P0 findings, re-validate
  PASSED  → Proceed with /epic-decompose {project}
═══════════════════════════════════════════════════════════════
```

## References

- `references/validation-steps.md` - Detailed workflow
- `references/output-format.md` - JSON structure
- `references/tool-requirements.md` - Tool selection, error handling

<rules>
- P0 blocks - no exceptions
- Every claim gets verified - assumptions are bugs
- Suggest alternatives for missing files - help fix, not just flag
- Use semantic search for symbols - exact match isn't enough
</rules>

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/davidabeyer) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->