name: skill-verifier
description: "Verifies that skills were applied correctly. Self-audit mechanism that checks process compliance and outcome quality. Ensures required deliverables exist, checklists were completed, and reference documents were consulted. Produces verification report with gaps and remediation actions."
phase: VERIFY
category: meta
version: "1.0.0"
depends_on: []
tags: [meta, verification, quality, audit]

Skill Verifier

Verify skills were applied correctly.

When to Use

• After applying any skill — Verify before proceeding
• At stage gates — Verify all skills in stage
• During retrospective — Audit full journey
• On suspicion of gaps — When something feels incomplete

Reference Requirements

MUST read before applying this skill:

Read if applicable:

Verification: Produce verification record with PASS/PARTIAL/FAIL status.

Hook Integration

Verification hooks automate deliverable checking and phase gate validation:

Note: Hooks provide quick automated warnings. This skill performs comprehensive verification with full checklists.

See .claude/hooks/deliverable-checker.sh, .claude/hooks/phase-gate-check.sh, and HOOKS.md for details.

Core Concept

Skill Verifier answers: "Was this skill applied correctly?"

Correctness has two dimensions:

┌─────────────────────────────────────────────────────────────────────────────┐
│                         CORRECTNESS DIMENSIONS                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  PROCESS COMPLIANCE                    OUTCOME QUALITY                      │
│  ──────────────────                    ───────────────                      │
│  • Did I follow all steps?             • Did the output achieve its goal?   │
│  • Did I read required references?     • Is the output complete?            │
│  • Did I produce required deliverable? • Is the output high quality?        │
│  • Did I complete the checklist?       • Would a senior approve this?       │
│                                                                             │
│  Verification checks BOTH dimensions                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

The Verification Process

┌─────────────────────────────────────────────────────────────────────────────┐
│                      SKILL VERIFICATION PROCESS                              │
│                                                                             │
│  1. IDENTIFY SKILL                                                          │
│     └─→ Which skill was applied?                                            │
│     └─→ Load skill requirements                                             │
│                                                                             │
│  2. CHECK PROCESS COMPLIANCE                                                │
│     └─→ Were all steps followed?                                            │
│     └─→ Were required references read?                                      │
│     └─→ Was required deliverable produced?                                  │
│     └─→ Was checklist completed?                                            │
│                                                                             │
│  3. CHECK OUTCOME QUALITY                                                   │
│     └─→ Does deliverable meet minimum requirements?                         │
│     └─→ Is it complete (no TODOs, no gaps)?                                 │
│     └─→ Would it pass review?                                               │
│                                                                             │
│  4. IDENTIFY GAPS                                                           │
│     └─→ What was missed?                                                    │
│     └─→ What was incomplete?                                                │
│     └─→ What needs remediation?                                             │
│                                                                             │
│  5. PRODUCE REPORT                                                          │
│     └─→ Verification status (PASS/PARTIAL/FAIL)                             │
│     └─→ Gaps identified                                                     │
│     └─→ Remediation actions                                                 │
│                                                                             │
│  6. REMEDIATE (if needed)                                                   │
│     └─→ Address gaps                                                        │
│     └─→ Re-verify                                                           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Required Deliverables Registry

Every skill MUST produce a named deliverable. This registry defines what each skill produces:

Required References by Skill

Each skill has references that MUST be consulted for proper application:

entry-portal

spec

architect

architecture-review

implement

test-generation

security-audit

code-review

Verification Checklist Template

# Skill Verification: [Skill Name]

**Date:** [Date]
**System:** [System Name]
**Verifier:** [Self/Peer]

## Process Compliance

### Steps Completed
- [ ] Step 1: [Description]
- [ ] Step 2: [Description]
- [ ] Step 3: [Description]
...

### References Consulted
- [ ] [reference-1.md] — [What I learned/applied]
- [ ] [reference-2.md] — [What I learned/applied]
...

### Deliverable Produced
- [ ] [Deliverable name] exists at [location]
- [ ] Deliverable is complete (no TODOs)
- [ ] Deliverable follows template/format

## Outcome Quality

### Completeness
- [ ] All required sections present
- [ ] No placeholder content
- [ ] All edge cases addressed

### Quality
- [ ] Would pass senior review
- [ ] Follows best practices from references
- [ ] No obvious gaps or issues

## Verification Result

| Dimension | Status | Notes |
|-----------|--------|-------|
| Process Compliance | ✅/⚠️/❌ | |
| Outcome Quality | ✅/⚠️/❌ | |
| **Overall** | **PASS/PARTIAL/FAIL** | |

## Gaps Identified

| Gap | Severity | Remediation |
|-----|----------|-------------|
| | | |

## Remediation Actions

1. [ ] [Action 1]
2. [ ] [Action 2]

Verification Triggers

Gate Verification Integration

Skill Verifier is mandatory at phase transitions and gates. Verification BLOCKS progress if it fails.

Automatic Verification Points

┌─────────────────────────────────────────────────────────────────────────────┐
│                    VERIFICATION ENFORCEMENT                                  │
│                                                                             │
│  1. AFTER EACH SKILL                                                        │
│     Run: verify [skill]                                                     │
│     Check: Deliverable exists and is non-empty                              │
│     Action: Log to journey-log.jsonl                                        │
│                                                                             │
│  2. AT PHASE BOUNDARIES                                                     │
│     Run: verify --phase [current-phase]                                     │
│     Check: All required skills completed or skipped                         │
│     Check: All deliverables exist                                           │
│     Action: Block if any verification fails                                 │
│                                                                             │
│  3. AT GATES (spec, architecture, deploy)                                   │
│     Run: verify --gate [gate-name]                                          │
│     Check: Phase verification passes                                        │
│     Check: Gate-specific quality checks                                     │
│     Action: Block transition until all checks pass                          │
│                                                                             │
│  4. AT SYSTEM COMPLETION                                                    │
│     Run: verify --full                                                      │
│     Check: All phases verified                                              │
│     Check: All deliverables present                                         │
│     Check: Journey-log complete                                             │
│     Action: Block completion if gaps found                                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Blocking Behavior

When verification fails:

⚠️ Verification Failed: [skill/phase/gate]

Status: BLOCKED
Reason: [specific failure reason]

Gaps Found:
  - [gap 1]
  - [gap 2]

Remediation Required:
  1. [action to fix gap 1]
  2. [action to fix gap 2]

Commands:
  - Fix issues, then run: verify
  - To override (not recommended): skip-verify --reason "..."

Phase-Specific Verification

Infrastructure Verification (SCAFFOLD Phase)

For backend/fullstack/api systems, SCAFFOLD phase also verifies:

Run verify-infra or .claude/hooks/verify-infrastructure.sh for comprehensive check.

Gate-Specific Verification

Verification Commands

# Verify single skill
verify [skill-name]

# Verify current phase
verify --phase

# Verify specific gate
verify --gate [spec|architecture|infrastructure|deploy]

# Verify infrastructure specifically
verify-infra
.claude/hooks/verify-infrastructure.sh [system-dir] [--verbose]

# Full system verification
verify --full

# Show verification status
check-phase

# Skip verification with reason (use sparingly)
skip-verify [skill] --reason "explanation"
skip-infra --reason "explanation"

Verification Report Format

{
  "timestamp": "2026-01-18T12:00:00Z",
  "type": "phase",
  "phase": "INIT",
  "status": "pass|partial|fail",
  "skills": {
    "entry-portal": { "status": "pass", "deliverable": "dream-state.md" },
    "requirements": { "status": "pass", "deliverable": "FEATURESPEC.md" },
    "spec": { "status": "pass", "deliverable": "FEATURESPEC.md" },
    "estimation": { "status": "fail", "reason": "ESTIMATE.md not found" },
    "triage": { "status": "skipped", "reason": "Single system, no prioritization needed" },
    "memory-manager": { "status": "pass", "deliverable": "loop-state.json loaded" }
  },
  "gaps": [
    { "skill": "estimation", "gap": "Missing ESTIMATE.md", "severity": "medium" }
  ],
  "blocking": true,
  "message": "Cannot proceed to SCAFFOLD: estimation skill not completed"
}

Integration with Journey Tracer

Skill Verifier produces verification records that feed into the journey tracer:

{
  "skill": "architect",
  "timestamp": "2025-01-17T10:30:00Z",
  "verification": {
    "processCompliance": "pass",
    "outcomeQuality": "partial",
    "overall": "partial"
  },
  "referencesRead": [
    "architecture-patterns.md",
    "adr-template.md"
  ],
  "deliverableProduced": "ARCHITECTURE.md",
  "gaps": [
    {
      "description": "No formal ADR created",
      "severity": "medium",
      "remediated": true
    }
  ]
}

Self-Audit Questions

When verifying your own skill application, ask:

Process Questions

1. Did I read the SKILL.md completely before starting?
2. Did I consult the required references?
3. Did I follow all steps in order?
4. Did I produce the required deliverable?
5. Did I complete any checklists in the skill?

Outcome Questions

1. Is the deliverable complete?
2. Would a senior engineer approve this?
3. Does it match the quality of examples in references?
4. Are there any obvious gaps?
5. Would I be confident defending this in review?

Honesty Check

1. Did I skip anything to save time/tokens?
2. Am I claiming completion without verification?
3. Are there parts I'm uncertain about?

Reference Emphasis Mechanism

To ensure references are consulted:

Before Starting a Skill

┌─────────────────────────────────────────────────────────────────────────────┐
│  🔍 REFERENCE CHECK                                                          │
│                                                                             │
│  Before applying [skill], you MUST read:                                    │
│                                                                             │
│  □ [reference-1.md] — [Why it's essential]                                  │
│  □ [reference-2.md] — [Why it's essential]                                  │
│                                                                             │
│  Skipping references leads to:                                              │
│  • Incomplete application                                                   │
│  • Missing best practices                                                   │
│  • Rework during verification                                               │
│                                                                             │
│  Time investment: ~2-5 minutes reading                                      │
│  Value: Correct application, no rework                                      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Reference Reading Protocol

1. Scan first — Read headers and key points (30 seconds)
2. Deep read relevant sections — Based on current context (1-2 minutes)
3. Extract actionable guidance — Note what applies to current task
4. Apply during skill execution — Reference while working
5. Verify against reference — Check output matches guidance

Common Verification Failures

Verification Cadence

Mode-Specific Behavior

Verification requirements differ by orchestrator mode:

Greenfield Mode

Greenfield verification:
- Full process compliance check
- Full outcome quality check
- All deliverables required
- Block stage transitions on failure

Brownfield-Polish Mode

Polish verification:
- Verify gap remediation complete
- Check new deliverables only
- Verify compatibility with existing
- Focus on "did we make it better?"

Polish considerations:

- [ ] Gaps identified in triage addressed
- [ ] New deliverables follow existing patterns
- [ ] Existing functionality not broken
- [ ] Tests pass (existing + new)

Brownfield-Enterprise Mode

Enterprise verification:
- Verify specific change implemented
- Verify no regressions
- Verify CI/CD pipeline passes
- Verify documentation updated

Enterprise verification checklist:

- [ ] Change implemented as specified
- [ ] Existing tests still pass
- [ ] New tests for changed code
- [ ] CI/CD pipeline green
- [ ] No regressions in affected areas
- [ ] Documentation reflects change

Verification Strictness by Mode

→ See references/verification-checklists.md for skill-specific checklists