Skip to main content
Agent skill

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 started

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?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/cross-validate-artifacts
# Save SKILL.md to ~/.claude/skills/cross-validate-artifacts/SKILL.md
  1. 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.
  2. 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.
  3. 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.

Starter prompt
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.