Menu
Comprehensive content audit — link integrity, registry alignment, cross-references, and freshness
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | audit |
| description | Comprehensive content audit — link integrity, registry alignment, cross-references, and freshness |
| allowed-tools | Shell Read Glob Grep |
This command is read-only. It reports findings organized by severity and asks what to fix.
- Repo structure conventions: `.cursor/rules/repo-structure.mdc` - Project description: `.cursorrules` (Project Contents section) - Root README: `README.md` (Directory Structure section) - Docs index: `docs/README.md` - Research index: `research/README.md` - Backlog: `BACKLOG.md` - Planning: scan .planning/ for active projectsScan all committed markdown files for internal links. For each link:
Skip external URLs (http/https) — those are not part of this audit.
Skip these paths entirely — known false-positive sources:
research/*/sources/ — scraped web content; relative paths (e.g. /en/products, /@user) are internal site links from the original HTML, not repo paths```) — example skill structures and documentation snippets contain links to hypothetical files that are not meant to resolveUse a correct extraction pattern that captures only the path inside (), not the surrounding link text:
# Extract link paths only (not link text) — uses PCRE lookbehind
# Skip research sources dirs and external URLs
git ls-files '*.md' \
| grep -v "^research/.*/sources/" \
| grep -v "^\.planning/" \
| while IFS= read -r file; do
# Strip fenced code blocks before extracting links
perl -0777 -pe 's/```.*?```//gs' "$file" \
| grep -oP '\]\(\K[^)]+(?=\))' \
| grep -v '^https\?://' \
| grep -v '^http' \
| while IFS= read -r link; do
dir=$(dirname "$file")
target="${link%%#*}"
[ -z "$target" ] && continue
resolved=$(python3 -c "import os,sys; print(os.path.normpath(os.path.join(sys.argv[1], sys.argv[2])))" "$dir" "$target" 2>/dev/null)
[ ! -e "$resolved" ] && echo "BROKEN: $file -> $link"
done
done
Resolve each extracted path relative to the containing file's directory before checking existence.
Compare documented inventories against what actually exists on disk.
.cursorrulesREADME.md.agents/skills/, .cursor/skills/, .cursor/agents/Run both directions:
Orphaned files — two tiers:
# Extract .md paths from docs/README.md (sort -u avoids false positives from files linked twice)
grep -oP '\(\K[^)]+\.md(?=\))' docs/README.md | sort -u > /tmp/master_indexed.txt
# Extract .md paths from each track README
grep -oP '\(\K[^)]+\.md(?=\))' docs/ai-engineering/README.md | sed 's|^|ai-engineering/|' | sort -u > /tmp/track_indexed.txt
grep -oP '\(\K[^)]+\.md(?=\))' docs/philosophy/README.md | sed 's|^|philosophy/|' | sort -u >> /tmp/track_indexed.txt
grep -oP '\(\K[^)]+\.md(?=\))' docs/case-studies/README.md | sed 's|^|case-studies/|' | sort -u >> /tmp/track_indexed.txt
sort -u /tmp/track_indexed.txt -o /tmp/track_indexed.txt
# All .md files in doc tracks (not READMEs)
find docs/ai-engineering docs/philosophy docs/case-studies -name "*.md" ! -name "README.md" | sed 's|^docs/||' | sort -u > /tmp/ondisk.txt
comm -23 /tmp/ondisk.txt /tmp/track_indexed.txt — fix these, they're invisiblecomm -13 /tmp/ondisk.txt <(sort -u /tmp/master_indexed.txt) — fix these, they're broken linksresearch/ (excluding README.md)Identify content that exists but isn't linked from its natural parent or peers.
research/ not linked from research/README.md.agents/skills/ (auto-discovered; no registry needed).cursor/skills/ not documented in .cursorrules.cursor/rules/ (informational only)docs/ai-engineering/session-framework.md (Zanshin behavioral map)docs/ai-engineering/framework-bootstrap.md (Zanshin portable entry point)docs/ai-engineering/sparring-and-shoshin.md (most-shared entry point)docs/ai-engineering/the-shift.md (foundational essay)/cross-link [file]sources/, findings/, completed/, phases/, hidden directories.cursor/skills/*/SKILL.md references files that don't exist (broken skill references).agents/skills/*/SKILL.md references files via @ syntax that don't exist.cursor/rules/*.md references files that don't existScan all committed markdown files for review: frontmatter blocks. Categorize files by content type and report validation status.
Reference: .cursor/rules/review-tracking.md for the frontmatter convention and AI-DISCLOSURE.md for validation type definitions.
For each content category, count:
status: reviewedstatus: unreviewed (explicit — new files generated after the convention change)status: direction-reviewedreview: frontmatter (legacy — assumed direction-reviewed; created before unreviewed-by-default was adopted)read, tested, fact-checked, etc.)Surface status: unreviewed files prominently — these are the active review queue, distinct from legacy files that may never have been intended for deep review.
Categories:
docs/**/*.md (excluding README.md files)devops/ansible/**/*.md, devops/ocp/**/*.md, devops/argo/**/*.md, devops/coreos/**/*.md, devops/rhacm/**/*.md, devops/vault/**/*.md.agents/skills/**/*.md, .cursor/skills/**/*.md, .cursor/rules/*.mdresearch/**/*.md, library/**/*.mdvoice-approvedScan all docs/**/*.md files for biographical patterns — first-person experience claims, professional identity statements, personal opinions, training history. For each file with biographical content, check if the file has voice-approved validation in its frontmatter. Files with biographical content but no voice-approved are the highest-priority review items.
Patterns to detect:
Present as:
### Biographical Content — Needs voice-approved
- docs/philosophy/ego-ai-and-the-zen-antidote.md — biographical claims on lines N, M (no voice-approved)
- docs/ai-engineering/the-shift.md — biographical claims on lines N, M (voice-approved: 2026-04-18 ✓)
Find markdown files committed in the last 14 days that have no review: frontmatter. These are candidates for the next review pass.
Find files where the most recent validation date is older than the file's last git modification date. This means the file was changed after the last review — the review may no longer be current.
If the file has an at: SHA in its review frontmatter, include the diff command so the author can see exactly what changed since their last review.
Present as:
### Review Coverage
- Essays: 3/16 reviewed (19%) — 2 read, 1 fact-checked
- DevOps: 12/248 reviewed (5%) — 8 read, 4 tested
- Meta-system: 15/237 reviewed (6%) — 10 read, 5 used-in-practice
- Research: 0/100 reviewed (0%)
- **Total: 30/601 reviewed (5%)**
### Needs Review (recently added)
- docs/case-studies/new-essay.md (committed 2026-04-17)
### Stale Reviews (modified after last review)
- docs/ai-engineering/the-shift.md — reviewed 2026-04-10, modified 2026-04-15
→ `git diff abc1234..HEAD -- docs/ai-engineering/the-shift.md`
Present findings organized by severity:
## Content Audit Report
### Broken Links (fix these)
- [ ] `file.md` line N: link to `path/that/does/not/exist`
### Registry Drift (update these)
- [ ] `.cursorrules` missing: [description of what's missing]
- [ ] `README.md` directory tree missing: `.planning/`
- [ ] Meta-system count: says N commands, actually M
### Cross-Reference Gaps (consider adding)
- [ ] `docs/new-essay.md` not linked from docs/README.md
- [ ] Skills in `.agents/skills/` not discoverable by clients
### Missing READMEs
- [ ] `directory/` has no README.md
### Freshness Flags (review these)
- [ ] BACKLOG.md last updated N days ago
- [ ] .planning/project/ ROADMAP shows Phase 1 in progress but SUMMARY exists
### Clean Areas
- Link integrity: N files checked, M links validated
- Research index: up to date
- [etc.]
After reporting, ask: "Want me to fix any of these? Reply with numbers, categories, or 'all'."
<success_criteria>
Review all pending changes against repo conventions before committing
Mark files as human-reviewed with specific validation types
Harvest and locally merge changes from a paude container session. Use when pulling agent work from paude, running paude harvest, merging session commits, importing submodule changes from a container, or fixing failed harvest/submodule fetch.
Start a paude container session for fire-and-forget agent work. Use when creating a paude session, delegating a task to paude, running work in an isolated container, setting up a paude worktree, or launching pi/claude/gemini in podman.
Write a task spec file for a paude container agent. Use when delegating work to paude, preparing a paude prompt-file, writing fire-and-forget agent tasks, or scoping submodule work for harvest.
Diagnose a running or stalled paude container session. Use when paude seems stuck, harvest returned empty, checking paude status, debugging 403 proxy blocks, or deciding wait vs harvest vs reset.