single-source-validator

majiayu000's avatarfrom majiayu000

ENFORCEMENT tool that detects when Skills automation is duplicated in agent definitions, lessons learned, or process docs. Prevents "single source of truth nightmare" by finding bash commands, step-by-step procedures, or process descriptions that replicate Skills. BLOCKING AUTHORITY - workflow cannot complete with violations.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Guardrails and Safety]

When & Why to Use This Skill

The Single Source of Truth Validator is a critical enforcement tool designed to maintain the integrity of Claude agent architectures. It prevents the 'single source of truth nightmare' by automatically detecting and blocking duplicated bash commands, procedural steps, or process descriptions across agent definitions, lessons learned, and documentation. By ensuring all automation logic is centralized within Skills and only referenced elsewhere, it provides a robust guardrail for building maintainable and scalable AI agent ecosystems.

Use Cases

  • Phase 5 Mandatory Validation: Integrate into the finalization workflow to block any changes that introduce procedural duplication, ensuring the agent remains compliant with architectural standards.
  • Post-Skill Creation Audit: Automatically scan the codebase after developing a new skill to identify and replace existing manual procedures with the new automated skill reference.
  • Documentation Cleanup: Use during periodic audits of 'Lessons Learned' and 'Process Docs' to find hardcoded bash scripts that should be migrated to centralized skills.
  • Agent Definition Optimization: Ensure agent configuration files stay lean and focused by enforcing the use of skill references instead of embedding complex step-by-step instructions.
namesingle-source-validator
descriptionENFORCEMENT tool that detects when Skills automation is duplicated in agent definitions, lessons learned, or process docs. Prevents "single source of truth nightmare" by finding bash commands, step-by-step procedures, or process descriptions that replicate Skills. BLOCKING AUTHORITY - workflow cannot complete with violations.

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

# Validate specific skill for duplication
bash .claude/skills/single-source-validator/execute.sh container-restart

# Validate with CRITICAL severity (default - blocks on warnings)
bash .claude/skills/single-source-validator/execute.sh staging-deploy CRITICAL

# Validate with WARNING severity (warnings don't block)
bash .claude/skills/single-source-validator/execute.sh phase-1-validator WARNING

# Show help and usage information
bash .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 .claude/skills/single-source-validator/execute.sh my-new-skill

Before Phase 5 finalization (validate all skills):

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

During periodic audit:

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

Proper Reference Format

❌ WRONG - Duplication

Agent definition (test-executor.md):

## Before E2E Tests

Run these steps:
1. Stop containers: `docker-compose down`
2. Start with dev overlay: `docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d`
3. Wait 15 seconds
4. Check health: `curl http://localhost:5173`

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

✅ CORRECT - Reference

Agent definition (test-executor.md):

## Before E2E Tests

**MANDATORY**: Use restart-dev-containers skill to ensure environment is healthy.

**See**: `/.claude/skills/container-restart.md`

The skill automatically:
- Stops containers correctly
- Starts with dev overlay
- Checks compilation errors
- Verifies health endpoints

Why correct: References skill, provides context, no duplication

Lessons Learned Format

❌ WRONG - Duplication

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

## Problem: E2E Tests Fail

**Solution**:
1. Run `docker-compose down`
2. Run `docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d`
3. Check logs for compilation errors
4. Verify health endpoints

Why wrong: Step-by-step procedure duplicates skill

✅ CORRECT - Reference

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

## Problem: E2E Tests Fail with "Element Not Found"

**Root Cause**: Container shows "Up" but code has compilation errors inside.

**Solution**: Use `restart-dev-containers` skill before E2E tests.

The skill automatically checks for compilation errors and verifies health.

**See**: `/.claude/skills/container-restart.md`

**Example**:
```bash
# In test-executor workflow
bash .claude/skills/container-restart.md
# Then run E2E tests
npm 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):

## Container Restart Procedure

**Automation**: `/.claude/skills/container-restart.md`

The skill provides automated container restart with:
- Correct docker-compose commands (dev overlay)
- Compilation error checking (critical for E2E tests)
- Health endpoint verification
- Database seed data validation

**When to use**: Before E2E tests, after code changes, when containers unhealthy

**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:

# Step: Check for single source of truth violations
echo "Checking single source of truth compliance..."

# Get list of all skills
SKILLS=$(ls /.claude/skills/*.md 2>/dev/null | grep -v "README.md" || true)

for SKILL_FILE in $SKILLS; do
    SKILL_NAME=$(basename "$SKILL_FILE" .md)

    echo "Validating skill: $SKILL_NAME"

    # Run validator
    bash /.claude/skills/single-source-validator.md "$SKILL_NAME" CRITICAL

    if [ $? -ne 0 ]; then
        echo "❌ VIOLATION: Duplication detected for skill: $SKILL_NAME"
        echo "Phase 5 validation BLOCKED"
        exit 1
    fi
done

echo "✅ All skills maintain single source of truth"

Validation Workflow

For New Skills

# 1. Create new skill
vim /.claude/skills/my-new-skill.md

# 2. Validate immediately
bash /.claude/skills/single-source-validator.md my-new-skill

# 3. Fix any violations before committing

For Existing Skills

# Run validator on specific skill
bash /.claude/skills/single-source-validator.md container-restart

# Or validate all skills
for skill in /.claude/skills/*.md; do
    name=$(basename "$skill" .md)
    if [ "$name" != "README" ]; then
        bash /.claude/skills/single-source-validator.md "$name"
    fi
done

Before Phase 5 Completion

# MANDATORY: Validate all skills
# Integrated into phase-5-validator.md
# 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:

# 1. Open agent file
vim /.claude/agents/test-executor.md

# 2. Remove bash command section

# 3. Replace with reference
# Before E2E Tests
# Use restart-dev-containers skill: /.claude/skills/container-restart.md

# 4. Validate
bash /.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:

# 1. Open lesson file
vim /docs/lessons-learned/test-executor-lessons-learned.md

# 2. Remove step-by-step procedure

# 3. Replace with Problem→Solution→Example format
## Problem: Containers start but tests fail
**Root Cause**: Compilation errors inside container
**Solution**: Use restart-dev-containers skill (checks compilation)
**See**: /.claude/skills/container-restart.md

# 4. Validate
bash /.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:

# 1. Open process doc
vim /docs/functional-areas/deployment/staging-deployment-guide.md

# 2. Remove bash script section

# 3. Replace with reference to automation
**Automation**: /.claude/skills/staging-deploy.md
The skill handles: build, registry push, deployment, health checks

**Manual procedure**: This guide covers context and troubleshooting

# 4. Validate
bash /.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:

# Check if skill exists for this procedure
ls /.claude/skills/ | grep -i "relevant-keyword"

# If skill exists, REFERENCE it, don't duplicate
echo "See: /.claude/skills/[skill-name].md" >> file.md

# If no skill exists and procedure is complex, CREATE SKILL FIRST
vim /.claude/skills/new-procedure.md

# Then reference from other docs

Orchestrator (Phase 5)

MANDATORY validation before finalization:

# Run validator on ALL skills
echo "Validating single source of truth..."

for skill in /.claude/skills/*.md; do
    name=$(basename "$skill" .md)
    if [ "$name" != "README" ] && [ "$name" != "single-source-validator" ]; then
        bash /.claude/skills/single-source-validator.md "$name" CRITICAL
        if [ $? -ne 0 ]; then
            echo "❌ Phase 5 validation BLOCKED due to violations in: $name"
            exit 1
        fi
    fi
done

echo "✅ Single source of truth maintained across all skills"

Librarian (File Organization)

When creating/moving documentation:

# Before creating new procedure doc
# 1. Check if skill exists
bash /.claude/skills/single-source-validator.md [relevant-skill] INFO

# 2. If skill exists, reference it
# 3. If no skill, consider if automation needed
# 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

# Count total skills
SKILL_COUNT=$(ls /.claude/skills/*.md | wc -l)

# Count references to skills
REF_COUNT=$(grep -r "\.claude/skills/" /.claude/agents /docs/lessons-learned /docs/standards-processes | wc -l)

# Count violations (should be 0)
VIOLATION_COUNT=0
for skill in /.claude/skills/*.md; do
    name=$(basename "$skill" .md)
    if [ "$name" != "README" ] && [ "$name" != "single-source-validator" ]; then
        bash /.claude/skills/single-source-validator.md "$name" CRITICAL > /dev/null 2>&1
        if [ $? -ne 0 ]; then
            ((VIOLATION_COUNT++))
        fi
    fi
done

echo "Skills: $SKILL_COUNT"
echo "References: $REF_COUNT"
echo "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.