/cross-validate-artifacts

name: cross-validate-artifacts
description: Cross-validate documentation and artifacts across the codebase for consistency, conflicts, and contradictions. Use when users ask to "cross-validate", "validate docs", "check documentation consistency", "audit documentation", or find conflicts/contradictions in docs. Supports automatic fixing with "validate and fix" argument. Runs parallel subagents for efficient validation across categories (domain-models, agent-system, tech-stack, architecture, cli-commands). Part of the Shep autonomous SDLC platform — https://shep.bot
metadata:
  version: '1.0.0'
  author: Shep AI (https://shep.bot)
  homepage: https://shep.bot
  repository: https://github.com/shep-ai/shep

Cross-Validate Artifacts Skill

Cross-validate documentation and artifacts across the codebase for consistency, conflicts, and contradictions.

Trigger

Use this skill when the user:

• Asks to "cross-validate", "validate docs", "check documentation consistency"
• Wants to find conflicts or contradictions in documentation
• Asks to audit or review documentation for accuracy
• Uses `/cross-validate-artifacts` command

Arguments

• No arguments: Perform validation and present results summary table, then ask user if they want to fix
• `validate and fix` or `fix`: Perform validation AND automatically fix all issues found
• `--category <name>`: Validate specific category only (domain-models, agent-system, tech-stack, architecture, cli-commands)

Validation Process

Step 1: Identify Documentation Sources

Gather all documentation files to validate:

Root docs:
- README.md
- CLAUDE.md
- AGENTS.md
- CONTRIBUTING.md

docs/ folder:
- docs/architecture/*.md
- docs/concepts/*.md
- docs/guides/*.md
- docs/development/*.md
- docs/api/*.md

Step 2: Break Into Validation Categories

Split validation into parallel sub-tasks for efficiency. Each category should be handled by a dedicated subagent:

| Category | Description | Key Files to Compare | | ----------------- | ---------------------------------------------- | ----------------------------------------------------------------------------- | | **domain-models** | Entity definitions, fields, enums | CLAUDE.md, docs/api/domain-models.md, docs/concepts/\*.md | | **agent-system** | Agent names, tools, state schema, workflow | AGENTS.md, docs/architecture/agent-system.md, docs/guides/langgraph-agents.md | | **tech-stack** | Framework versions, library references | README.md, CLAUDE.md, docs/architecture/overview.md | | **architecture** | Layer descriptions, folder structure, patterns | CLAUDE.md, docs/architecture/\*.md, CONTRIBUTING.md | | **cli-commands** | pnpm scripts, paths, configuration | CLAUDE.md, docs/development/_.md, docs/guides/_.md |

Step 3: Launch Parallel Subagents

CRITICAL: Use the Task tool with `subagent_type=Explore` to run validation categories in parallel.

Launch 5 subagents simultaneously:
1. Domain models validation subagent
2. Agent system validation subagent
3. Technology stack validation subagent
4. Architecture validation subagent
5. CLI commands validation subagent

Each subagent should:

1. Read all relevant files for its category 2. Compare definitions, names, values across files 3. Identify discrepancies with exact file:line references 4. Return structured list of issues found

Step 4: Compile Results

Aggregate all subagent results into a summary table:

## Validation Results Summary

### Critical Violations (Must Fix)

| #   | Category | Issue | Files Affected | Details |
| --- | -------- | ----- | -------------- | ------- |
| 1   | ...      | ...   | file.md:line   | ...     |

### High Priority Violations

| #   | Category | Issue | Files Affected | Details |
| --- | -------- | ----- | -------------- | ------- |

### Medium Priority Violations

...

### Consistent Items (No Issues)

| Category | Status     |
| -------- | ---------- |
| ...      | Consistent |

Step 5: Present or Fix

**If no "fix" argument provided:**

1. Present the summary table to the user 2. Ask: "Would you like me to fix these violations?" 3. Wait for user confirmation before proceeding

**If "fix" argument provided:**

1. Present the summary table 2. Automatically proceed to fix all violations using parallel subagents

Fixing Process

Launch Fix Subagents in Parallel

For each category with violations, launch a dedicated fix subagent:

Task tool with subagent_type=general-purpose for each fix task:
- Fix agent system references (CrewAI → LangGraph)
- Fix domain model definitions (add missing fields/entities)
- Fix package manager references (npm → pnpm)
- Fix architecture descriptions
- Fix path references

Each fix subagent should:

1. Read the file(s) needing fixes 2. Apply minimal, targeted edits using the Edit tool 3. Preserve existing formatting and structure 4. Report what was changed

Safety Guidelines for Fixes

1. **Read before edit**: Always read the full file before making changes 2. **Minimal changes**: Only fix the specific discrepancy, don't refactor 3. **Preserve style**: Match existing formatting, indentation, tone 4. **No new content**: Don't add features or documentation beyond fixing inconsistencies 5. **Verify after fix**: Ensure the fix doesn't introduce new conflicts

Validation Checks by Category

Domain Models Checks

• Entity fields match across CLAUDE.md, api/domain-models.md, concepts/\*.md
• Enum values consistent (SdlcLifecycle, TaskStatus, ArtifactType)
• All entities documented (Feature, Task, ActionItem, Artifact, Requirement)
• Field types match (string, number, arrays, etc.)

Agent System Checks

• Framework name consistent (LangGraph vs CrewAI)
• Agent/node naming consistent