# Plan Audit

> Audit a vd:plan output for gaps, inconsistencies, missing scaffolding, and codebase drift using an independent clean-context subagent. Use after vd:plan (or any time after manual edits to phase files) when stakes warrant verification beyond same-context red-team. Auto-fires at end of vd:plan --deep.

- **Type:** Skill
- **Install:** `agentstack add skill-vanducng-skills-plan-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vanducng](https://agentstack.voostack.com/s/vanducng)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vanducng](https://github.com/vanducng)
- **Source:** https://github.com/vanducng/skills/tree/main/skills/plan-audit
- **Website:** https://skills.vanducng.dev

## Install

```sh
agentstack add skill-vanducng-skills-plan-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Plan Audit

## What this skill is — and isn't

| Skill | Question it answers | Output |
|---|---|---|
| `vd:plan` | "Given the chosen approach, what are the steps?" | Phased plan files |
| `vd:plan --deep` Phase 6 (red-team) | "What does THIS author's plan assume that isn't true?" | Three hostile questions, same context |
| **`vd:plan-audit`** | **"Independently — does this plan hold up against the real codebase and the stated goal?"** | **Severity-tagged audit report (clean-context subagent)** |
| `vd:research` | "What do external sources say about X?" | Comparison report with citations |

The `--deep` red-team round (in `vd:plan`) lives inside the same conversation that wrote the plan — it shares the author's blind spots. **Plan-audit escapes that** by spawning a subagent with **only** the plan files + audit checklist as input. No conversation history, no author bias.

It's a **second pair of eyes**, not a redesign tool. Findings are advisory — the author still owns the plan.

## Hard rules

1. **Never edit source code.** This skill only edits plan files (and only with `--fix`, only HIGH/CRITICAL findings, with per-finding confirmation by default — or single up-front confirmation when `--apply-all` is set). Never touches the actual codebase.
2. **Always use a clean-context subagent.** Inline reasoning shares the same blind spots as the author. The point of audit is independence — a clean-context subagent (`Agent` tool in Claude Code; see Phase 3 for the Codex fallback), fresh context, plan files as the only input. Hand the subagent the plan and the goal, **not the author's argument for why the plan is sound** — withholding the claim is what keeps the second look honest. "Confirm this is right" invites agreement; "does this hold up?" invites scrutiny.
3. **Findings are advisory, not blocking.** Audit prints a report and exits. It never blocks `vd:plan` completion or `vd:cook` execution. The author decides.
4. **Only HIGH/CRITICAL are eligible for `--fix`.** MEDIUM/LOW are observational — surfacing them is the value, fixing them auto would be over-reach.
5. **Respect `decisions.md`.** If the plan dir contains `decisions.md`, listed non-goals are intentional exclusions — drop those findings entirely. "Trade-offs" entries: drop the unchosen-side findings. "Constraints accepted" entries: a finding that contradicts the constraint may surface as MEDIUM with note "constraint may need revisiting" — never CRITICAL/HIGH.
6. **Audit one plan at a time.** Multi-plan batch audit is out of scope — different plans, different contexts.

## Modes

| Mode | When | Behavior |
|---|---|---|
| **default** | Standard audit — read, spawn subagent, write report | No file edits beyond writing the report |
| `--fix` | Author wants to apply HIGH/CRITICAL findings inline | After report, walk findings interactively; per-finding y/n; edit phase file in place. **Interactive-only** — never auto-invoked by other skills. |
| `--fix --apply-all` | Author trusts the audit + wants one keypress instead of N | Print a unified preview of every HIGH/CRITICAL edit (file/line/old→new); single y/n at the top; apply the whole batch atomically on `y`. Still HIGH/CRITICAL only. **Interactive-only.** |

Detect mode from the explicit flags. `--apply-all` without `--fix` is a usage error — error out and print the help line. Announce mode in your first reply.

## Phase 1 — Resolve plan dir

- If a plan-dir path is provided as an argument → use it. Verify it exists and contains `plan.md`. If missing, error and stop.
- If no argument → check the injected Plans path for entries matching `{YYYYMMDD-HHMM}-*` or `{YYMMDD-HHMM}-*`; sort by date prefix descending, pick the most recent that contains `plan.md`. Print "Auditing most-recent plan: {path}" so the user can confirm.
- If no plan dir is found → error: "No plan dir argument and no recent plan found under the injected Plans path. Pass a path explicitly."

## Phase 2 — Read inputs

Read into the controller context (so the subagent prompt can paste them verbatim):

- `{plan-dir}/plan.md` — required
- `{plan-dir}/phase-*.md` — all phase files
- `{plan-dir}/decisions.md` — optional. If present, pass to subagent as the "non-goals / out-of-scope" block.
- `{plan-dir}/research/*.md` — optional. If present, summarize paths only (not full content) for the subagent's awareness.
- `{plan-dir}/reports/*.md` — optional. Same — paths only.

If `decisions.md` is absent, treat as "no exclusions stated."

## Phase 3 — Spawn audit subagent

Use the `Agent` tool with `subagent_type: general-purpose`. Single subagent, full plan context. **Do not** spawn N parallel agents — plans are small (5-10 phase files, ~5K tokens) and an independent voice across the whole plan is the goal.

When this auditor runs inside a Workflow harness (e.g. auto-fired from `vd:plan --deep`), keep its output schema minimal — mark only `summary` and `findings` as `required`, avoid `additionalProperties: false`, and keep the one-line JSON example below in the prompt so the first attempt conforms (strict schemas fail ~74% of first attempts and burn retries).

**Portability:** the `Agent` tool with `subagent_type` is Claude Code-only. In another runtime, spawn the independent auditor with that runtime's subagent mechanism (or a fresh `codex exec` process); only if none exists, fall back to a documented degraded inline pass with fresh eyes and say so — weaker isolation, but better than dead-ending.

### Subagent prompt template

```
You are an independent plan auditor. You have NO access to the prior conversation.
Your only inputs are the plan files below + the audit checklist + (if present) decisions.md.
Treat the plan as the only source of truth about intent.

# Plan dir
{plan-dir-path}

# plan.md
{verbatim contents}

# Phase files
{verbatim contents of each phase-XX-*.md}

# decisions.md (if present)
{verbatim contents}
If a "Non-goals" item appears here, it is an intentional exclusion. Do NOT
report it as a gap. If a "Trade-offs" item lists chosen vs unchosen, do NOT
flag the unchosen alternative.

NEGATIVE EXAMPLE: if decisions.md says "no auth — internal tool only", do
NOT add a CRITICAL finding "missing auth phase". The author already decided.

# Audit checklist
{paste contents of references/audit-checklist.md}

# Codebase root
{repo-root-path}

You may use Read/Glob/Grep tools to:
- Re-Read each phase file directly so `line_range` numbers are real, not fabricated.
  (The verbatim contents above are for context; cite line numbers from your own Read calls.)
- Spot-check codebase reality (does file X exist? does the naming convention match?).
Do not read more than ~20 files total — this is a survey, not deep analysis.

# Your task
1. Walk the audit checklist (6 categories) against the plan.
2. For each finding, classify severity: CRITICAL / HIGH / MEDIUM / LOW (defs
   in checklist).
3. For each finding, name: phase number, line range (best-effort), one-line
   summary, suggested fix.
4. Skip findings that decisions.md already covers as non-goals.
5. Recommended action: block | revise-before-cook | proceed-with-caveats | proceed
6. Return ONLY a single JSON object with keys `summary` and `findings`. Shape:

{
  "summary": {
    "counts": {"critical": N, "high": N, "medium": N, "low": N},
    "recommended_action": "block | revise-before-cook | proceed-with-caveats | proceed",
    "verdict_one_liner": "..."
  },
  "findings": [
    {
      "severity": "CRITICAL|HIGH|MEDIUM|LOW",
      "category": "consistency|codebase-drift|missing-scaffolding|unrealistic-criteria|deps-sequencing|scope-shape",
      "phase": "plan|N",
      "line_range": "L42-L48 (best effort, omit if unknown)",
      "summary": "one-line gist",
      "detail": "1-3 sentences explaining the gap",
      "suggested_fix": "concrete edit the author can apply"
    }
  ]
}

If you find NO issues, return the same wrapper with empty findings array and
verdict "proceed". Do not pad. Do not invent gaps to look thorough.
```

## Phase 4 — Apply findings

- Parse subagent JSON output. Validate shape; if malformed, ask the subagent to retry once.
- Render report — write into the audited plan's own folder so every artifact for this feature stays grouped: `{plan-dir}/reports/`. Filename: `audit-{YYMMDD-HHMM}-{plan-slug}.md`. Date format matches the session-hook `## Naming` block (6-digit YY). `plan-slug` = the date-stripped slug of the plan dir (e.g. `260510-0938-vd-plan-audit-skill` → `vd-plan-audit-skill`). If the plan dir doesn't follow `{date}-{slug}` pattern, fall back to the dir name itself as the slug.
- If `--fix` mode (per-finding):
  - Walk findings filtered to severity in {CRITICAL, HIGH}.
  - For each, print finding + suggested fix, ask user `Apply? (y/n/skip-rest)`.
  - On `y`: open the named phase file, apply the suggested edit (Edit tool, with the user's confirmation of the exact diff if it's non-trivial). Mark finding as "applied" in the report.
  - On `n` or `skip-rest`: leave finding unfixed, note as "deferred" in the report.

- If `--fix --apply-all` mode (batch):
  - Filter findings to severity in {CRITICAL, HIGH}. If the filtered list is empty, print "No HIGH/CRITICAL findings to apply" and exit without prompting.
  - Compute the concrete edit for each finding (the exact `old_string`/`new_string` pair that the Edit tool will use). If any edit cannot be made concrete from the `suggested_fix` (ambiguous instruction, target line missing) → mark that finding `unactionable` and exclude it from the batch.
  - Print a single unified preview: for each actionable finding, show `phase-NN.md @ Lstart-Lend` + a 3-line context diff (old → new). Group by file. Cap at 60 lines total — if longer, write the full preview alongside the audit report in `{plan-dir}/reports/`, filename `audit-{date}-{slug}.preview.diff`, and print only the file/line summary inline.
  - Ask **one** prompt: `Apply N HIGH/CRITICAL edits across M files? (y/n)`. Default is `n`. No `skip-rest` — it's all-or-nothing.
  - On `y`: apply each edit in order. **If any edit fails** (file changed since audit read, `old_string` not unique, etc.) → stop, mark already-applied as `applied`, the failing one as `failed`, remaining as `deferred`. Surface the failure inline and in the report so the author can re-audit. Do **not** roll back applied edits — they're plan-file edits, not code, and partial progress is recoverable via `git`.
  - On `n`: leave all findings unfixed, note them as `deferred`. Skill exits with a one-line summary.
  - `unactionable` findings always appear in the report regardless of choice — surfacing them is the value.

### Report template

```markdown
---
title: "Plan Audit — {plan-title}"
date: {YYYY-MM-DD}
auditor: plan-audit-subagent
plan: ../{plan-dir-name}/
verdict: {recommended_action} — {verdict_one_liner}
---

# Plan Audit: {plan-title}

## Summary
- {N} findings: {C} critical · {H} high · {M} medium · {L} low
- Recommended action: **{block | revise-before-cook | proceed-with-caveats | proceed}**
- {one-line verdict}

## Findings (severity-sorted)

### CRITICAL
- **{summary}** — phase {N}, {line range} — {detail}
  → fix: {suggested fix}
  → status: {advisory | applied | deferred}

### HIGH
- ...

### MEDIUM
- ...

### LOW
- ...

## Decisions respected
- {non-goal from decisions.md that the audit honored, if any}

## Files inspected
- {list of plan files read}
- {list of codebase files spot-checked, if any}
```

## Phase 5 — Hand off

After writing the report:

1. **Print report path** — use an openable location such as `Audit report: [audit-report.md](/absolute/path/to/audit-report.md)` and include `file:///absolute/path/to/audit-report.md` when helpful. Do not print only the basename.
2. **Print top-3 findings inline** — sorted by severity. Just summary + phase ref. Full detail in the file.
3. **Recommend next step** based on verdict:
   - `block` → "Critical findings — revise plan before `vd:cook`."
   - `revise-before-cook` → "Address HIGH findings before execution."
   - `proceed-with-caveats` → "Plan is workable; review MEDIUM findings."
   - `proceed` → "No blocking issues. Cook when ready."
4. **If `--fix` ran**, summarize: `{N} fixes applied, {M} deferred, {U} unactionable, {F} failed.` (omit zero-count buckets).
5. **Recommend re-run** after fixes: "Re-run `vd:plan-audit` after edits to verify."

## Anti-rationalization

| Excuse | Reality |
|---|---|
| "I'll do the audit inline — it's faster" | Inline = same context = same blind spots. Use the subagent. (Phase 3's degraded inline fallback is only for runtimes with no subagent tool — not a speed shortcut.) |
| "The plan is small — skip decisions.md check" | Small plans have non-goals too. Read it if it exists. |
| "Audit found 0 issues — must be wrong" | Or the plan is good. Don't pad findings to look thorough. |
| "I'll fix MEDIUM findings too while I'm in --fix" | Out of scope. Surface, don't fix. The author decides. |
| "I'll extend `--apply-all` to MEDIUM/LOW for tidy output" | No. The trust boundary is HIGH/CRITICAL — anything below is observational. |
| "Just have another skill invoke `--apply-all` automatically" | `--apply-all` is interactive — one human keypress at the preview gate. It is NOT for auto-invocation by `vd:plan --deep` or `vd:cook --auto`. |
| "Just block on CRITICAL by default" | Audit is advisory. The author owns the call. |
| "I'll re-read the plan in main context to double-check" | That defeats the point. Trust the subagent's report. |

## Quality bar

- **Independent.** Audit subagent has no parent conversation context. No author bias.
- **Severity-honest.** A CRITICAL is "plan will fail at cook." A HIGH is "plan succeeds but produces a flawed result." Don't inflate.
- **Concrete.** Every finding names a phase, ideally a line range, and a suggested fix. "Plan is vague" is not a finding. "Phase 3 step 4 says 'add validation' without naming the validator" is.
- **Decisions-aware.** Listed non-goals don't show up as gaps. The audit respects what was already decided.
- **Re-runnable.** Author can fix → re-run → see fewer findings. The skill is composable, not one-shot.

## Specials

- **Migration plans** — audit specifically checks: rollback path tested? consumers updated after migration? feature flag for staged rollout? If any missing → HIGH.
- **API breaking changes** — audit checks the "add new → migrate callers → remove old" sequence is explicit (not collapsed). If collapsed → HIGH.
- **Performance plans** — audit checks for baseline numbers in phase 1 + comparison evidence in success criteria. Missing → HIGH.
- **Library upgrades** — audit checks each phase ends with smoke test of an affected feature. Missing → MEDIUM.
- **Bug fixes** — audit checks for a failing-test-first step. Missing → MEDIUM.
- **Plans with no `decisions.md`** — audit emits a LOW advisory: "Consider adding decisions.md to record explicit non-goals — reduces false positives on re-audit."

## Output rules

1. Announce mode (default / `--fix` / `--fix --apply-all`) and resolved plan-dir in the first reply.
2. Phase 1 (resolve) and Phase 2 (read) happen visibly — print plan dir + file count before spawning the subagent.
3. Subagent dispatch is one `Agent` tool call. Print "Spawning audit subagent..." so the user sees the boundary.
4. After subagent returns, print the report path and top-3 findings inline. Don't paste the whole report.
5. `--fix` (per-finding) walks findings interactively — one prompt per HIGH/CRITICAL.
6. `--fix --apply-all` (batch) shows one unified preview, asks one y/n, applies the batch atomically. Default-no on the prompt.
7. End with the recommended next step. Don't leave the author wondering whether to cook.

## References

- `references/audit-checklist.md` — six audit categories + severity definitions (subagent paste-target)

## Workflow position

**Typically follows:** `vd:plan` (manual run after planning), `vd:plan --deep` (auto-invoked as Phase 7)
**Typically precedes:** `vd:cook` (with HIGH/CRITICAL addressed)

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vanducng](https://github.com/vanducng)
- **Source:** [vanducng/skills](https://github.com/vanducng/skills)
- **License:** MIT
- **Homepage:** https://skills.vanducng.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vanducng-skills-plan-audit
- Seller: https://agentstack.voostack.com/s/vanducng
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.