Location	Type	Priority
`./*.md`	Root documentation	Primary (can edit)
`docs/*.md`	Reference documentation	Primary (can edit)
`playbooks/*.md`	Procedures	Primary (can edit)
`SKILLS.md`	Skills reference	Primary (can edit)
`skills/*/SKILL.md`	Skill definitions	Secondary (source of truth for skills)
`commands/*.md`	Command definitions	Secondary (source of truth for commands)
`speckit/*/.md`	Spec-kit templates	Contributed (prefer not to edit)
`mcp/*/.md`	MCP server docs	Secondary

Third-Party / Contributed Content

These directories may contain content from external repositories. When conflicts arise, prefer fixing local documentation rather than modifying contributed files:

speckit/ — from spec-kit
skills/architecture-*, skills/specialist-*, skills/create-adr, skills/list-members, skills/pragmatic-guard, skills/setup-architect — from ai-software-architect
commands/project/ — from claude-workflow

Consistency Checks

1. Cross-Reference Validity

Check that references between files are valid:

# Find all internal references
grep -rE "\`~?/?\.?claude/[^'\"]+\`" *.md docs/*.md playbooks/*.md

# Find all skill references
grep -rE "/[a-z-]+" *.md docs/*.md playbooks/*.md | grep -v "http"

Check:

File paths exist (e.g., ~/.claude/docs/worktree-setup.md)
Skill names exist (e.g., /repo-security-scan)
Command names exist (e.g., /dotfiles-setup)

Report invalid references:

[BROKEN] README.md:42 references `~/.claude/docs/old-guide.md` (file not found)
[BROKEN] SKILLS.md:87 references `/old-skill` (skill not found)

2. Skills Documentation Sync

Compare SKILLS.md against actual skills:

# List documented skills in SKILLS.md
grep -E "^### \`/" SKILLS.md | sed 's/.*`\/\([^`]*\)`.*/\1/'

# List actual skills
ls -d skills/*/SKILL.md | xargs -I{} dirname {} | xargs -n1 basename

Check:

All skills in skills/*/SKILL.md are documented in SKILLS.md
No skills documented in SKILLS.md that don't exist
Descriptions match between SKILLS.md and individual SKILL.md files
Allowed tools listed correctly

Report discrepancies:

[MISSING] Skill /repo-consistency exists but not documented in SKILLS.md
[STALE] Skill /old-skill documented in SKILLS.md but directory not found
[MISMATCH] /worktree description differs between SKILLS.md and SKILL.md

3. Commands Documentation Sync

Check commands are properly documented:

# List actual commands
find commands -name "*.md" -type f | sed 's|commands/||;s|\.md$||'

Check:

Commands have consistent naming
README or SKILLS.md mentions available commands

4. Setup Documentation Accuracy

Verify SETUP.md accurately reflects repo contents:

# What SETUP.md says gets installed
grep -A 20 "What gets installed" SETUP.md

# What actually exists
ls -la *.md
ls -d */ 2>/dev/null

Check:

All items listed in "What gets installed" exist
No major items missing from the list
.gitignore entries match "What gets preserved"

5. README Accuracy

Verify README.md is current:

Check:

Directory structure matches description
Setup instructions point to correct files
Links are valid

6. Naming Conventions

Check consistent naming across documentation:

Check:

Skill names use kebab-case (repo-security-scan not repoSecurityScan)
File names follow conventions
British English spelling where applicable (behaviour, colour, organisation)

7. Duplicate Information

Identify content that's duplicated and might drift:

Check:

Same procedure documented in multiple places
Configuration examples duplicated
Potential for one to be updated without the other

8. Orphaned Files

Find documentation that isn't referenced anywhere:

# List all .md files
find . -name "*.md" -type f | grep -v node_modules

# Check which are referenced
for f in $(find docs -name "*.md"); do
  basename=$(basename "$f")
  grep -r "$basename" --include="*.md" . | grep -v "^$f:" || echo "[ORPHAN] $f"
done

Workflow

Step 1: Gather All Documentation

# Collect all markdown files
find . -name "*.md" -type f | grep -v node_modules | grep -v .git

# Build inventory
- Root: CLAUDE.md, README.md, SETUP.md, SKILLS.md, CONTRIBUTING.md, etc.
- docs/: spotlight.md, worktree-setup.md, etc.
- playbooks/: workflow-guide.md, etc.
- skills/: SKILL.md files
- commands/: command definitions

Step 2: Run Consistency Checks

Execute each check category and collect findings.

Step 3: Categorise Findings

Severity	Meaning
Error	Broken reference, missing required content
Warning	Outdated info, mismatch between files
Info	Suggestion for improvement, minor inconsistency

Step 4: Generate Report

Write findings to console (and optionally consistency-report.md):

# Repository Consistency Report

**Date:** YYYY-MM-DD
**Files scanned:** 42

## Summary

| Severity | Count |
|----------|-------|
| Errors   | 2     |
| Warnings | 5     |
| Info     | 3     |

## Findings

### Errors

#### [E1] Broken reference in README.md
- **File:** README.md:42
- **Issue:** References `~/.claude/docs/old-guide.md` which doesn't exist
- **Fix:** Update reference or create the file

#### [E2] Missing skill documentation
- **File:** SKILLS.md
- **Issue:** Skill `/repo-consistency` exists but not documented
- **Fix:** Add section to SKILLS.md

### Warnings

#### [W1] Description mismatch
- **Files:** SKILLS.md:15, skills/worktree/SKILL.md:3
- **Issue:** Skill descriptions don't match
- **SKILLS.md says:** "Creates git worktrees for parallel development"
- **SKILL.md says:** "Creates a git worktree for parallel development"
- **Fix:** Align descriptions (update SKILLS.md to match SKILL.md)

### Info

#### [I1] Potential duplicate content
- **Files:** SETUP.md, README.md
- **Issue:** Setup instructions appear in both files
- **Suggestion:** Consider single source of truth with cross-reference

## Recommendations

1. Fix all Errors immediately
2. Address Warnings to prevent drift
3. Consider Info items for future cleanup

Step 5: Offer Fixes

For issues that can be auto-fixed:

Found 2 errors and 5 warnings.

Auto-fixable issues:
  [E2] Add /repo-consistency to SKILLS.md
  [W1] Align description in SKILLS.md

Would you like me to fix these automatically?
  - Fix all
  - Fix errors only
  - Review each
  - Skip (just report)

Step 6: Apply Fixes (if requested)

When fixing, follow the priority:

Update local docs (README.md, SKILLS.md, SETUP.md, docs/*.md)
Leave contributed files unchanged (speckit/, ai-software-architect skills)
Update skill/command source only if it's clearly wrong

Examples

Missing Skill Documentation

Found: skills/repo-consistency/SKILL.md exists but not in SKILLS.md

Fix: Add to SKILLS.md:

### `/repo-consistency`

Checks documentation consistency across the repository.

**Usage:**
...

Broken File Reference

Found: playbooks/development-workflow.md references docs/git-workflow.md which doesn't exist

Fix options:

Create the missing file
Update the reference to correct path
Remove the reference if obsolete

Stale Setup Instructions

Found: SETUP.md lists specs/ in "What gets installed" but specs/ is now gitignored

Fix: Remove specs/ from the "What gets installed" table

Notes

Run after making significant documentation changes
Run before committing documentation updates
Helps maintain documentation quality over time
Does not modify files without explicit permission

repo-consistency

Repository Consistency Check

Invocation

Scope

Files to Check