Agent Skills: Audit Skill

Audit Skill

Quality gate that validates a research document or plan before the next phase begins.

Agent Compatibility

• OUTPUT_DIR: .claude/output for Claude Code, .codex/output for Codex CLI.
• If an assumption needs user confirmation, ask directly — don't auto-fail.

Audit Types

• /audit research — Validates research output before planning.
• /audit plan — Validates plan output before implementation.

How to Run an Audit

1. Load Context

Required:
├── Artifact to audit (research-{feature}.md or plan-{feature}.md)
├── Original requirements (Jira description, PRD, or original prompt)
└── AGENTS.md (project conventions)

2. Run the Three Checks

For each check: list findings, then give a verdict.

Check 1: Hallucination — Is anything invented?

Hallucination = a claim, requirement, or decision that is not traceable to the original requirements and is not a reasonable technical necessity.

How to Check

For each requirement, decision, or task in the artifact:

• Can it be traced to the PRD / Jira / prompt? → Traceable
• Is it a reasonable inference from context or technical necessity? → Justified
• Is it invented with no basis? → Hallucination

Important: If something looks like an assumption, ask the user first before marking it as a hallucination. If the user confirms it → "User-confirmed assumption" (not a hallucination).

Verdicts

| Finding | Verdict | |---------|---------| | No hallucinations found | ✅ PASS | | Minor assumptions (user-confirmed or clearly justified) | ⚠️ WARN | | Invented requirements with no basis | ❌ FAIL |

Check 2: Scope Balance — Is it the right amount of work?

Overengineering = adding things not required (abstractions, configs, future-proofing). Underengineering = missing requirements, missing error handling, missing edge cases.

How to Check

Overengineering signals:

• Abstractions or layers that serve no current requirement
• Configuration options not asked for
• "Future-proofing" without specification
• New patterns when existing patterns suffice

Underengineering signals:

• PRD requirements with no corresponding task or coverage
• Happy-path-only implementation (missing error/empty/loading states)
• Missing input validation or auth checks
• Acceptance criteria with no task addressing them

Verdicts

| Finding | Verdict | |---------|---------| | Nothing extraneous, nothing missing | ✅ PASS | | Minor scope issues that don't block | ⚠️ WARN | | Significant scope creep or requirement gaps | ❌ FAIL |

Check 3: Traceability — Does every requirement have coverage?

Build a simple matrix: each requirement → covered by task(s) or explained why not.

| Requirement | Covered by | Status | |-------------|------------|--------| | R1: {desc} | T1, T3 | ✅ Full | | R2: {desc} | T2 | ✅ Full | | R3: {desc} | — | ❌ Missing |

Verdicts

| Finding | Verdict | |---------|---------| | All requirements covered | ✅ PASS | | Some partial coverage with clear reason | ⚠️ WARN | | Requirements with no coverage | ❌ FAIL |

Overall Verdict

| Result | Meaning | Action | |--------|---------|--------| | PASS | All checks green or warn-level | Proceed to next phase | | WARN | Minor issues noted, nothing blocking | Proceed with caution; note items for review | | FAIL | At least one check failed | Stop; fix issues; re-audit |

Output Template

Save to OUTPUT_DIR/audit-{type}-{feature}.md:

# Audit Report: {Feature} ({Research / Plan})

## Check 1: Hallucination
**Verdict: {PASS / WARN / FAIL}**

Findings:
- {item}: {Traceable / Justified / Hallucination — reason}

{If hallucination: List what must be removed or confirmed}

---

## Check 2: Scope Balance
**Verdict: {PASS / WARN / FAIL}**

Overengineering findings:
- {item or "None"}

Underengineering findings:
- {item or "None"}

{Recommended additions or removals}

---

## Check 3: Traceability

| Requirement | Covered by | Status |
|-------------|------------|--------|
| R1: {desc} | {tasks} | ✅ / ⚠️ / ❌ |

**Verdict: {PASS / WARN / FAIL}**

---

## Pattern Compliance (Plan Audit Only)

| Pattern | Status | Notes |
|---------|--------|-------|
| {pattern from AGENTS.md} | ✅ / ❌ | {notes} |

---

## Overall: {PASS / WARN / FAIL}

### Blocking Issues (must fix before proceeding)
{List or "None"}

### Non-Blocking Issues (noted for awareness)
{List or "None"}

### Next Steps
1. {action}

Quick Commands

/audit research  — Audit the research output
/audit plan      — Audit the plan output