Project Vision Audit

Project Vision Audit

When to Use

Trigger when the user says any of:

• "Audit", "Review", "Inventory check", "Where do we actually stand?"
• "Is the project still aligned with the vision/spec?"
• "Before deploy/merge/release, check everything"
• "There's drift between spec and code"
• "Code review — but not just technical, also did we build what we planned?"

Do NOT use this skill when:

• The user just wants a quick code review on a diff → use superpowers:requesting-code-review
• The user wants to plan a new feature → use superpowers:brainstorming + superpowers:writing-plans
• The user reports a single bug → use systematic-debugging

Hard Rules (apply to main + all sub-agents)

These three rules exist because the audit only delivers value when claims are grounded in reality, not speculation. Skip them and you get a polished-looking report that confidently states things which aren't true — the worst possible outcome for an audit.

1. Karpathy-style code discipline — see references/karpathy-discipline.md. State assumptions explicitly, simplicity first, surgical changes, verifiable success criteria.
2. Verify-don't-assume — see references/verify-not-assume.md. Reality (code, DB, git, API) wins over docs (specs, daily notes, memory). On conflict: reality wins. The reason: docs lag, memory grows stale, and history is full of "I'll do X tomorrow" that never got done. Only what's in the codebase right now is the status.
3. Vision-vs-Implementation match — every finding gets classified as ✅ Done / ⚠️ Partial / ❌ Missing / 🚫 Vision-Gap (spec ambiguous) / 📭 Data-Gap (code OK but data/DB/API empty). Five categories because gaps have different fix-shapes: a "Missing" needs new code, a "Vision-Gap" needs a scope decision first, a "Data-Gap" needs migrations or backfills, not new code. Mixing them up wastes the user's time.

Quick Walkthrough (what running an audit looks like)

User says: "Audit the project — does the implementation still match the spec we wrote 6 weeks ago?"

The agent then:

1. Runs scripts/find-foundation-docs.sh to discover the spec, mockups, diagrams, and history sources
2. Reads them, plus the git log of the last 30 days
3. Drafts a 30-50 row strand-checklist (A Vision-Match through I Mobile-Parity, dropping irrelevant strands)
4. Spawns 4-6 sub-agents in parallel, each handling a strand-group, each enforcing the verify-rule
5. Aggregates their findings into a gap-matrix sorted by impact
6. Saves the report to docs/audits/YYYY-MM-DD-audit.md
7. Tells the user "Here's what you actually have vs what you planned. Three ❌ Missing, one 🚫 Vision-Gap needs your decision, two ⚠️ Partials are quick wins. Want me to hand off to writing-plans?"

That's it — the audit doesn't fix anything itself. It produces a structured truth-check that the user can act on.

Workflow

Step 1 — Find Foundation Docs

Identify what the project SHOULD be. Sources to check, in priority order:

Always check (project-local):

• <project>/docs/**/*spec*.md, *vision*.md, *design*.md, *plan*.md, *architecture*.md
• README.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md
• Diagrams: *.excalidraw, *.png, *.svg, *.figma showing architecture or page flow
• Mockups: *.html, *.fig, *.sketch (often in mockups/, designs/, or _design-mockups/)
• Git: git log --all --oneline | head -50

Optional knowledge bases (only if the user has and references them):

• Obsidian Vault — pass via --obsidian-vault <path> (project notes typically under 02 Projekte/<project>/ or similar)
• Notion workspace — invoke find-skills "notion" for current integration
• Linear / Jira / GitHub Projects — invoke find-skills "<platform>"
• Custom docs directory — set AUDIT_DOCS_DIR=<path> env var

Helper script: scripts/find-foundation-docs.sh does an automated discovery sweep across project-local sources. Optional knowledge-base flags documented in the script header.

Step 2 — Read History

Reconstruct what was claimed done, what was claimed open. Sources, in priority order:

Always check:

• Git log with date filter (git log --all --since="30 days ago")
• CHANGELOG.md, HISTORY.md, NEWS.md if present
• GitHub PR / issue history if gh CLI configured

Tool-specific (if the user uses them):

• Claude Code memory files — ~/.claude/projects/-*/memory/
• Obsidian Daily Notes — typically in a Daily Notes/ or Journal/ folder inside the vault (only if --obsidian-vault flag set)
• Custom history directory — AUDIT_HISTORY_DIR=<path> env var

WARNING: History gives signals, NOT truth. Step 4 verifies every history-claim against actual current state (Hard Rule 2).

Step 3 — Build Strand Checklist

Adapt the generic A-I template (references/audit-checklist-template.md) to the project. Typical strands:

• A Vision-Match (does the product fulfill its primary goal?)
• B Backend / Pipeline / Worker
• C Database / Schema
• D API Endpoints
• E Frontend Pages (one row per page)
• F Design / Layout / UX consistency
• G Data Plausibility (are the numbers in the UI sensible?)
• H Operational Gaps (deploy, commit, push, branch hygiene)
• I Other Platform Parity (mobile, desktop, etc.)

Each row = one verifiable question. Aim for 30-50 rows total. Drop strands that don't apply, add project-specific ones.

Step 4 — Dispatch Parallel Audit Agents

REQUIRED SUB-SKILL: superpowers:dispatching-parallel-agents

Group strands into 4-6 independent agent tasks. Each agent gets:

1. The audit-checklist rows assigned to them
2. The Hard Rules (Karpathy + Verify) hardcoded into the prompt
3. Concrete verify-don't-assume examples per claim type:
   • "Endpoint exists" → grep route file, show file:line
   • "Table has X rows" → run SELECT COUNT(*), show output
   • "Buttons wired up" → code-read, show onClick handler + HTTP call
   • "Tests green" → run test command, show output
   • "Commit status clean" → git status + git log -5
   • "Migration applied" → prisma migrate status / alembic current
   • "Deploy live" → curl <url> + show HTTP status + body snippet
4. Word-budget for output (default: under 800 words per agent)
5. Required output format per row: ✅/⚠️/❌/🚫/📭 + 1-line evidence + file:line or command output

Step 5 — Aggregate Findings

Pull agent reports into one matrix using references/report-template.md. Sort by:

1. ❌ Missing (highest impact gaps first)
2. 🚫 Vision-Gap (scope ambiguity needing decision)
3. ⚠️ Partial (close to done — quick wins)
4. 📭 Data-Gap (code OK, data missing)
5. ✅ Done (sanity-confirm only)
6. 🟡 Unverified (could not verify, document why)

Step 6 — Save Report

Default: <project>/docs/audits/YYYY-MM-DD-audit.md

If user has Obsidian and --obsidian-vault flag was used: also mirror to the vault (path convention adapts to the user's structure, e.g. <vault>/02 Projekte/<project>/01 Active/YYYY-MM-DD <project> Audit.md).

Step 7 — Hand Off (User Decides)

Present findings. Possible next steps:

After-Audit Handoff Pipeline

The audit produces findings. Fixing them follows the full superpowers pipeline:

1. superpowers:brainstorming — only if Scope-Gap (spec ambiguous)
2. superpowers:writing-plans — implementation plan from findings
3. superpowers:using-git-worktrees — isolated fix branch
4. superpowers:test-driven-development — TDD before fix-code
5. superpowers:subagent-driven-development OR superpowers:executing-plans — execute plan
6. superpowers:verification-before-completion — before claiming done
7. superpowers:requesting-code-review — second-pair-of-eyes
8. superpowers:receiving-code-review — handle review feedback
9. superpowers:finishing-a-development-branch — merge + cleanup

See references/handoff-flow.md for the full pipeline diagram and decision points.

Domain-Specific Handoff Skills

When findings touch a specific domain, the fix-implementation invokes domain skills:

See references/domain-handoff-mapping.md for the full mapping.

Output Format Contract

Every audit produces a report with these six sections — the structure is fixed because each section answers a different question the user has, and missing one leaves them with an incomplete picture:

1. Executive Summary (3-5 sentences) — does the project fulfill its primary goal? Yes / No / Partially-Why. Why fixed: the user often only reads this part. It has to stand alone.
2. Findings Matrix (the table) — sorted by priority. Why fixed: gives a scannable status across all strands without burying important findings in prose.
3. Vision-Gap Decisions Needed — bullet list of scope questions for the user. Why fixed: these block all downstream work; calling them out separately keeps them from getting lost in the matrix.
4. Quick Wins — ⚠️ Partials closeable in < 1 hour. Why fixed: low-effort/high-impact items deserve their own list so they actually get done.
5. Data-Plausibility Anomalies — numbers in UI that look wrong. Why fixed: code can be perfect and data can still be lying; surfaces this distinct failure mode.
6. Recommended Next Action — one sentence: "Hand off X to skill Y with priority Z". Why fixed: removes ambiguity about what to do next.

See references/report-template.md for the exact markdown skeleton.

Anti-Patterns That Defeat the Audit

The audit is worthless if these happen — guard against them at every step:

• Finding without file:line reference → the agent is guessing. Reject and ask for verification. The whole point is grounding in reality.
• Daily-note or changelog quoted as evidence → that's "what someone claimed" not "what is". Reject and demand code/DB/git proof.
• Aggregation skips the verification step → produces a report that confidently states things which aren't true. Fail loudly, do not silently degrade.
• Report missing one of the six sections → rebuild. A truncated report is worse than no report because it misleads.

Why This Skill Exists

Specs drift. Daily notes lag. Memory becomes stale. Implementation diverges from vision over weeks. Without a structured audit, you build on assumptions and ship the wrong thing.

This skill enforces: read source-of-truth, verify against reality, categorize the gap, propose the fix-handoff. Nothing more.