sova-audit-instructions

Audit this project's AI instruction system for completeness, contradictions, implicit assumptions, and autonomous-agent readiness. the arguments provided when this skill is invoked

Phase 1: Collect All Instruction Sources

Read every instruction file. Do not skip any.

cat CLAUDE.md 2>/dev/null || echo "MISSING: CLAUDE.md"

cat AGENTS.md 2>/dev/null || echo "No AGENTS.md"

for f in .claude/rules/*.md; do [ -f "$f" ] && echo "=== $f ===" && cat "$f"; done 2>/dev/null || echo "No rules"

ls .claude/agent-memory/*.md 2>/dev/null || echo "No agent memory"

ls .claude/skills/*/SKILL.md 2>/dev/null || echo "No skills"

Phase 2: Analyze Project Reality

Understand the actual project to compare against instructions:

find . -maxdepth 3 -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \) | head -50

git log --oneline -20 2>/dev/null || echo "Not a git repo"

ls pyproject.toml package.json Cargo.toml go.mod Makefile Dockerfile 2>/dev/null

ls -d tests/ test/ __tests__/ spec/ 2>/dev/null && find tests/ test/ __tests__/ spec/ -maxdepth 1 -name "*.py" -o -name "*.ts" -o -name "*.js" 2>/dev/null | head -20

Phase 3: Gap Analysis

For each category, assess completeness (0-10) and list specific gaps:

Phase 4: Report

Present findings in this structure:

Instruction Completeness Score: X/100

Critical Gaps (will cause agent failures):

• List each with a specific, actionable recommendation

Contradictions Found:

• List any conflicting instructions with file locations

Implicit Assumptions (undocumented knowledge required to work in this project):

• List things the project assumes but never states

Phase 5: Propose Improvements

For each gap found, propose a specific addition or edit. Group by target file:

• CLAUDE.md additions
• New rule files (.claude/rules/)
• Existing rule file updates

Present the improvements and ask the user if they want them applied.

Rules

• Do NOT invent preferences the project has not demonstrated. Only document what exists
• Preserve the existing voice and style of instructions
• Where unsure about a convention, ask the user rather than guessing
• Focus on what an autonomous agent needs to succeed without human guidance
• Use make test and make lint for project-specific commands in any templates