Single Source of Truth Validator Skill

Purpose: ENFORCE single source of truth for Skills - prevent duplication nightmare.

When to Use:

• After creating any new Skill
• Before Phase 5 finalization (MANDATORY)
• When updating agent definitions
• When updating lessons learned
• During periodic audits (monthly)

🚨 CRITICAL: ENFORCEMENT MECHANISM

This skill has BLOCKING AUTHORITY.

If violations found:

• ❌ Phase 5 validation FAILS
• ❌ Workflow CANNOT complete
• ❌ Changes MUST NOT be committed

Why this matters:

• Skills = ONLY source of automation
• All other docs REFERENCE skills, never duplicate
• Agents ignore guides when procedures are scattered
• User feedback: "SUPER CRITICAL" - duplication causes nightmare

Single Source of Truth Architecture

SKILLS (/.claude/skills/*.md)
    Automation ONLY
    Executable bash scripts
    Zero duplication
         ↑
         |
    Referenced by
         |
         ↓
AGENT DEFINITIONS (/.claude/agents/*.md)
    Role + Tools + Skill References
    "Use skill X for Y"
    NEVER duplicate procedures

LESSONS LEARNED (/docs/lessons-learned/*.md)
    Problem → Solution → Example
    "See: /.claude/skills/X.md"
    NEVER duplicate procedures

PROCESS DOCS (/docs/standards-processes/*.md)
    Workflow + References
    "Automation: /.claude/skills/X.md"
    NEVER duplicate procedures

What This Validates

This skill checks for 8 types of single-source violations:

1. Bash Command Duplication - Exact bash commands from skills appearing in agent definitions, lessons learned, or process docs
2. Step-by-Step Procedures - Numbered or bulleted procedure steps duplicating skill automation
3. Hardcoded Skill Paths - Direct file path references (/.claude/skills/X.md) instead of skill name references
4. Detailed Agent Skill Sections - Agent definitions with When:/What:/Location: patterns (should be reference-only)
5. Procedural Keyword Duplication - Skill-specific procedures duplicated in other documents
6. Missing Proper References - Documents should say "Use X skill" or "See SKILLS-REGISTRY.md"
7. Bash Scripts in Non-Skill Docs - Bash code blocks in guides without skill references (NEW)
8. Procedure Sections Without Skill References - "How to", "Steps to", "Procedure" sections not referencing skills (NEW)

Detection Levels:

• ❌ VIOLATIONS (CRITICAL) - Exact duplications, blocks Phase 5
• ⚠️ WARNINGS - Potential issues, manual review recommended

How to Use This Skill

From Command Line

bash
1# Validate specific skill for duplication
2bash .claude/skills/single-source-validator/execute.sh container-restart
3
4# Validate with CRITICAL severity (default - blocks on warnings)
5bash .claude/skills/single-source-validator/execute.sh staging-deploy CRITICAL
6
7# Validate with WARNING severity (warnings don't block)
8bash .claude/skills/single-source-validator/execute.sh phase-1-validator WARNING
9
10# Show help and usage information
11bash .claude/skills/single-source-validator/execute.sh --help

From Claude Code

Use the single-source-validator skill to check if [skill-name] has any duplication violations

Common Usage Patterns

After creating new skill:

bash
1bash .claude/skills/single-source-validator/execute.sh my-new-skill

Before Phase 5 finalization (validate all skills):

bash
1for skill_dir in .claude/skills/*/; do
2    skill_name=$(basename "$skill_dir")
3    if [ -f "$skill_dir/SKILL.md" ]; then
4        bash .claude/skills/single-source-validator/execute.sh "$skill_name"
5    fi
6done

During periodic audit:

bash
1bash .claude/skills/single-source-validator/execute.sh container-restart WARNING

Proper Reference Format

❌ WRONG - Duplication

Agent definition (test-executor.md):

markdown
1## Before E2E Tests
2
3Run these steps:
41. Stop containers: `docker-compose down`
52. Start with dev overlay: `docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d`
63. Wait 15 seconds
74. Check health: `curl http://localhost:5173`

Why wrong: Duplicates bash commands from restart-dev-containers skill

✅ CORRECT - Reference

Agent definition (test-executor.md):

markdown
1## Before E2E Tests
2
3**MANDATORY**: Use restart-dev-containers skill to ensure environment is healthy.
4
5**See**: `/.claude/skills/container-restart.md`
6
7The skill automatically:
8- Stops containers correctly
9- Starts with dev overlay
10- Checks compilation errors
11- Verifies health endpoints

Why correct: References skill, provides context, no duplication

Lessons Learned Format

❌ WRONG - Duplication

Lesson (test-executor-lessons-learned.md):

markdown
1## Problem: E2E Tests Fail
2
3**Solution**:
41. Run `docker-compose down`
52. Run `docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d`
63. Check logs for compilation errors
74. Verify health endpoints

Why wrong: Step-by-step procedure duplicates skill

✅ CORRECT - Reference

Lesson (test-executor-lessons-learned.md):

markdown
1## Problem: E2E Tests Fail with "Element Not Found"
2
3**Root Cause**: Container shows "Up" but code has compilation errors inside.
4
5**Solution**: Use `restart-dev-containers` skill before E2E tests.
6
7The skill automatically checks for compilation errors and verifies health.
8
9**See**: `/.claude/skills/container-restart.md`
10
11**Example**:
12```bash
13# In test-executor workflow
14bash .claude/skills/container-restart.md
15# Then run E2E tests
16npm run test:e2e

**Why correct**: Explains problem/solution, references skill, shows usage example

---

## Process Documentation Format

### ❌ WRONG - Duplication

**Process doc** (docker-operations-guide.md):
```markdown
## Container Restart Procedure

Steps:
1. Stop: `docker-compose -f docker-compose.yml -f docker-compose.dev.yml down`
2. Start: `docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d`
3. Verify: Check container logs for errors
4. Health: Test all endpoints

Why wrong: Detailed procedure duplicates skill automation

✅ CORRECT - Reference

Process doc (docker-operations-guide.md):

markdown
1## Container Restart Procedure
2
3**Automation**: `/.claude/skills/container-restart.md`
4
5The skill provides automated container restart with:
6- Correct docker-compose commands (dev overlay)
7- Compilation error checking (critical for E2E tests)
8- Health endpoint verification
9- Database seed data validation
10
11**When to use**: Before E2E tests, after code changes, when containers unhealthy
12
13**Manual procedure**: See skill file for troubleshooting steps if automation fails

Why correct: References skill as automation, provides context, no duplication

Integration with Phase 5 Validator

Update to phase-5-validator.md:

bash
1# Step: Check for single source of truth violations
2echo "Checking single source of truth compliance..."
3
4# Get list of all skills
5SKILLS=$(ls /.claude/skills/*.md 2>/dev/null | grep -v "README.md" || true)
6
7for SKILL_FILE in $SKILLS; do
8    SKILL_NAME=$(basename "$SKILL_FILE" .md)
9
10    echo "Validating skill: $SKILL_NAME"
11
12    # Run validator
13    bash /.claude/skills/single-source-validator.md "$SKILL_NAME" CRITICAL
14
15    if [ $? -ne 0 ]; then
16        echo "❌ VIOLATION: Duplication detected for skill: $SKILL_NAME"
17        echo "Phase 5 validation BLOCKED"
18        exit 1
19    fi
20done
21
22echo "✅ All skills maintain single source of truth"

Validation Workflow

For New Skills

bash
1# 1. Create new skill
2vim /.claude/skills/my-new-skill.md
3
4# 2. Validate immediately
5bash /.claude/skills/single-source-validator.md my-new-skill
6
7# 3. Fix any violations before committing

For Existing Skills

bash
1# Run validator on specific skill
2bash /.claude/skills/single-source-validator.md container-restart
3
4# Or validate all skills
5for skill in /.claude/skills/*.md; do
6    name=$(basename "$skill" .md)
7    if [ "$name" != "README" ]; then
8        bash /.claude/skills/single-source-validator.md "$name"
9    fi
10done

Before Phase 5 Completion

bash
1# MANDATORY: Validate all skills
2# Integrated into phase-5-validator.md
3# Blocks workflow if violations found

Common Violations & Fixes

Violation 1: Agent Definition Has Bash Commands

Violation:

❌ VIOLATION: Agent 'test-executor' duplicates bash command
   File: /.claude/agents/test-executor.md
   Command: docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

Fix:

bash
1# 1. Open agent file
2vim /.claude/agents/test-executor.md
3
4# 2. Remove bash command section
5
6# 3. Replace with reference
7# Before E2E Tests
8# Use restart-dev-containers skill: /.claude/skills/container-restart.md
9
10# 4. Validate
11bash /.claude/skills/single-source-validator.md container-restart

Violation 2: Lessons Learned Has Procedure Steps

Violation:

❌ VIOLATION: Lesson 'test-executor-lessons-learned' duplicates bash command
   File: /docs/lessons-learned/test-executor-lessons-learned.md
   Command: docker logs witchcity-web --tail 50 | grep -i error

Fix:

bash
1# 1. Open lesson file
2vim /docs/lessons-learned/test-executor-lessons-learned.md
3
4# 2. Remove step-by-step procedure
5
6# 3. Replace with Problem→Solution→Example format
7## Problem: Containers start but tests fail
8**Root Cause**: Compilation errors inside container
9**Solution**: Use restart-dev-containers skill (checks compilation)
10**See**: /.claude/skills/container-restart.md
11
12# 4. Validate
13bash /.claude/skills/single-source-validator.md container-restart

Violation 3: Process Doc Duplicates Automation

Violation:

❌ VIOLATION: Process doc 'staging-deployment-guide' duplicates bash command
   File: /docs/functional-areas/deployment/staging-deployment-guide.md
   Command: docker build -f apps/api/Dockerfile -t registry.digitalocean.com/...

Fix:

bash
1# 1. Open process doc
2vim /docs/functional-areas/deployment/staging-deployment-guide.md
3
4# 2. Remove bash script section
5
6# 3. Replace with reference to automation
7**Automation**: /.claude/skills/staging-deploy.md
8The skill handles: build, registry push, deployment, health checks
9
10**Manual procedure**: This guide covers context and troubleshooting
11
12# 4. Validate
13bash /.claude/skills/single-source-validator.md staging-deploy

Severity Levels

CRITICAL (Default)

• Exact bash command matches: Always blocked
• Step-by-step procedures: Always blocked
• Warnings treated as failures: Yes
• Use for: Phase 5 validation, skill creation

WARNING

• Exact bash command matches: Blocked
• Step-by-step procedures: Blocked
• Warnings treated as failures: No (manual review)
• Use for: Periodic audits, exploratory checks

INFO

• Exact bash command matches: Reported only
• Step-by-step procedures: Reported only
• Warnings treated as failures: No
• Use for: Documentation reviews, planning

Agent Instructions

All Agents (Mandatory)

Before modifying agent definitions, lessons learned, or process docs:

bash
1# Check if skill exists for this procedure
2ls /.claude/skills/ | grep -i "relevant-keyword"
3
4# If skill exists, REFERENCE it, don't duplicate
5echo "See: /.claude/skills/[skill-name].md" >> file.md
6
7# If no skill exists and procedure is complex, CREATE SKILL FIRST
8vim /.claude/skills/new-procedure.md
9
10# Then reference from other docs

Orchestrator (Phase 5)

MANDATORY validation before finalization:

bash
1# Run validator on ALL skills
2echo "Validating single source of truth..."
3
4for skill in /.claude/skills/*.md; do
5    name=$(basename "$skill" .md)
6    if [ "$name" != "README" ] && [ "$name" != "single-source-validator" ]; then
7        bash /.claude/skills/single-source-validator.md "$name" CRITICAL
8        if [ $? -ne 0 ]; then
9            echo "❌ Phase 5 validation BLOCKED due to violations in: $name"
10            exit 1
11        fi
12    fi
13done
14
15echo "✅ Single source of truth maintained across all skills"

Librarian (File Organization)

When creating/moving documentation:

bash
1# Before creating new procedure doc
2# 1. Check if skill exists
3bash /.claude/skills/single-source-validator.md [relevant-skill] INFO
4
5# 2. If skill exists, reference it
6# 3. If no skill, consider if automation needed
7# 4. If automation needed, create skill FIRST

Metrics & Monitoring

Success Metrics

• Zero violations in Phase 5 validation (target: 100%)
• Skills referenced vs procedures duplicated ratio (target: >95%)
• Agent compliance - agents using skills vs. duplicating (target: 100%)

Monitoring Commands

bash
1# Count total skills
2SKILL_COUNT=$(ls /.claude/skills/*.md | wc -l)
3
4# Count references to skills
5REF_COUNT=$(grep -r "\.claude/skills/" /.claude/agents /docs/lessons-learned /docs/standards-processes | wc -l)
6
7# Count violations (should be 0)
8VIOLATION_COUNT=0
9for skill in /.claude/skills/*.md; do
10    name=$(basename "$skill" .md)
11    if [ "$name" != "README" ] && [ "$name" != "single-source-validator" ]; then
12        bash /.claude/skills/single-source-validator.md "$name" CRITICAL > /dev/null 2>&1
13        if [ $? -ne 0 ]; then
14            ((VIOLATION_COUNT++))
15        fi
16    fi
17done
18
19echo "Skills: $SKILL_COUNT"
20echo "References: $REF_COUNT"
21echo "Violations: $VIOLATION_COUNT"

Troubleshooting

Issue: Validator reports false positive

Cause: Skill and doc have similar bash command for different purpose

Solution:

1. Review context around command in both files
2. If different purpose, add comment in doc: # Different from skill: [explanation]
3. Run validator with WARNING severity for manual review

Issue: Too many warnings, hard to review

Cause: Keyword-based detection is overly broad

Solution:

1. Focus on VIOLATIONS first (exact bash commands)
2. Review warnings manually during periodic audits
3. Refine keyword extraction logic if needed

Issue: Validator missed duplication

Cause: Procedure rewritten in different style (paraphrased)

Solution:

1. Manual code review remains important
2. Validator catches exact duplicates, not paraphrases
3. Educate agents on spirit of single source of truth

Version History

• 2025-11-04: Created as ENFORCEMENT mechanism for single source of truth
• Addresses user feedback: "SUPER CRITICAL" - agents ignore guides when procedures scattered
• Provides BLOCKING AUTHORITY - workflow cannot complete with violations
• Integrated with phase-5-validator for mandatory validation

Remember: This skill has blocking authority. Zero tolerance for duplication. Skills are the ONLY source of automation.