Cross Validate Artifacts
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
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Cross Validate Artifacts when an AI agent needs a reusable SKILL.md workflow for this job: 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
When not to use it
Skip Cross Validate Artifacts when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/cross-validate-artifacts # Save SKILL.md to ~/.claude/skills/cross-validate-artifacts/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/cross-validate-artifacts/SKILL.md. For a shared project, commit the folder at .claude/skills/cross-validate-artifacts/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Cross Validate Artifacts skill for this task: Use Cross Validate Artifacts when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 62/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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:
```markdown ## 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 (class names vs function names) - State schema fields match across docs - Tool names consistent (snake_case tool names, camelCase variables) - Workflow stages match
### Tech Stack Checks
- Framework versions specified consistently - Library names match (Next.js, Vite, Vitest, etc.) - Package manager consistent (pnpm everywhere) - Database technology consistent (SQLite, LanceDB)
### Architecture Checks
- Layer names and hierarchy consistent - Folder structure matches across docs - Dependency rules documented consistently - Use case names match (PascalCase vs kebab-case)
### CLI Commands Checks
- pnpm script names consistent - Command descriptions match - Data paths consistent (~/.shep/repos/...) - Config file paths consistent - Port numbers consistent (3030)
## Example Output
```markdown ## Documentation Cross-Validation Results
### Critical Violations (4 issues)
| # | Category | Issue | Files | Details | | --- | ------------- | ------------------- | ------------------ | --------------------------------------------------- | | 1 | agent-system | CrewAI vs LangGraph | CLAUDE.md:59,106 | Uses "CrewAI-style" but implementation is LangGraph | | 2 | cli-commands | npm vs pnpm | building.md:20-358 | Uses `npm run` instead of `pnpm` | | 3 | domain-models | Missing entity | CLAUDE.md | Requirement entity not documented | | 4 | agent-system | Wrong naming | CLAUDE.md:110-113 | Uses class names instead of node functions |
### Consistent Items
| Category | Status | | ----------------- | ---------- | | Database (SQLite) | Consistent | | Build tool (Vite) | Consistent | | Data paths | Consistent |
---
Would you like me to fix these violations? ```
## Notes
- Always use subagents for both validation and fixing to maximize efficiency - Present results in clean markdown tables for readability - Prioritize fixes by severity (Critical > High > Medium > Low) - After fixing, optionally re-run validation to confirm all issues resolved
Intended uses
- Use Cross Validate Artifacts when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.