# Project Vision Audit

> Use when the user asks to audit, review, or assess whether a project's implementation actually matches its spec, vision, plan, or design — especially after weeks of work, before a major deploy, or when drift is suspected. Reads foundation docs (vision, spec, plans, diagrams, optional Obsidian / Notion / Linear), dispatches parallel verification agents per strand, enforces verify-don't-assume on every claim, outputs a gap-matrix report (Done / Partial / Missing / Vision-Gap / Data-Gap), and hands off to writing-plans for fixes. Make sure to use this skill whenever the user mentions audit, review, drift, "wo stehen wir wirklich", "is the project still on track", "before we deploy let's check", or asks for a code review that goes beyond technical correctness — even if they don't explicitly say "audit". Also use it when the user has been building for weeks and starts wondering what's actually done vs claimed done.

- Skill: `metkelhansen/project-vision-audit` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add metkelhansen/project-vision-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/metkelhansen/project-vision-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: metkelhansen (https://skillmd.com/u/metkelhansen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/metkelhansen/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:

| User decision | Next skill |
|---|---|
| "Fix the findings" | See `references/handoff-flow.md` — full superpowers pipeline |
| "Spec is unclear on Finding X" | `superpowers:brainstorming` for scope decision, then `superpowers:writing-plans` |
| "Defer / park findings" | Save report, mark status `parked` |
| "Re-audit in N days" | Schedule a follow-up |

## 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:

| Finding domain | Recommended skills |
|---|---|
| Frontend / UI build | `frontend-design`, `web-design-guidelines`, `ui-ux-pro-max`, `distill` |
| Frontend architecture / IA | `agency-ux-architect` |
| Performance | `optimize`, `audit-website` |
| React / Next.js | `vercel-react-best-practices` |
| DB / SQL / Postgres | `supabase-postgres-best-practices` |
| Android (Kotlin/Compose) | `android-kotlin`, `android-jetpack-compose`, `mobile-android-design` |
| YouTube / video / channel | `youtube-channel-analyst`, `youtube-seo`, `video-marketing` |
| Domain not listed above | Invoke `find-skills` with the finding's domain keyword |

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.