Multi-phase audit pipeline with independent review agents. Use when finishing tickets, validating work against acceptance criteria, checking architecture compliance, or reviewing code against skill standards. Use /audit to run the full pipeline, /audit ac for acceptance criteria only, /audit arch for architecture only, /audit skill for skill compliance only.
Multi-phase audit pipeline with independent review agents. Use when finishing tickets, validating work against acceptance criteria, checking architecture compliance, or reviewing code against skill standards. Use /audit to run the full pipeline, /audit ac for acceptance criteria only, /audit arch for architecture only, /audit skill for skill compliance only.
Audit Orchestrator
Validate completed work through independent review agents, fix issues, and loop until green.
Three sequential phases: acceptance criteria, architecture compliance, skill compliance.
ReadCLAUDE.md (if exists) - Project conventions and audit config
Read.claude/audits/overrides.yaml (if exists) - Standing overrides for agent prompts
Read.claude/audits/warns/agent-context/*.md (if exists) - Past decisions for agent context
using the resolution rules below
Locate audit inputs
Resolving Audit Inputs
The audit needs three categories of input. Each has smart defaults that can be
overridden in CLAUDE.md under a ## Audit Configuration section.
1. Acceptance Criteria (Phase 1)
Resolution Order
Source
Default
docs/roadmap/jira/*.jira.md (if exists) — extract **Acceptance Criteria:** sections from stories matching the ticket IDs being audited. This is the path convention from the /jira skill.
Fallback
JIRA API via mcp__atlassian__getJiraIssue (if Atlassian MCP available) — fetch ticket descriptions and AC fields directly
Last resort
Ask user to provide acceptance criteria inline or point to a file
Ticket identification: Accept ticket IDs as arguments (e.g., /audit PROJ-370 PROJ-371),
or infer from the current branch (match PROJ-\d+ pattern where PROJ comes from CLAUDE.md
JIRA config), or use all to audit every ticket with status "In Progress" or "Done" in the
current sprint. If all is used and JIRA API is unavailable, scan local *.jira.md files
for stories with **Status:** In Progress or **Status:** Done.
2. Architecture Rules (Phase 2)
Resolution Order
Source
Default
docs/architecture/*.md (if exists) — all architecture documentation
Fallback
CLAUDE.md architecture sections (Technology Stack, Architecture Principles, Service Boundaries, etc.)
Match changed files to skills by pattern (see Skill Mapping below)
Fallback
.claude/skills/*/SKILL.md — scan all skills for applicable review guidance
Override
CLAUDE.md → Audit Configuration → skill_mappings
Skill Mapping (Default)
Map changed files to the skill that should review them. The orchestrator spawns
one agent per applicable skill per ticket (full matrix).
Auto-detect by scanning .claude/skills/*/SKILL.md for skills that mention relevant
file types in their description or review checklists. Then load that skill's references/
directory files. Only include reference files that actually exist.
Common mappings (auto-detected from skill descriptions):
File Pattern
Likely Skill
How Detected
*.cs, *.razor
dotnet-api (if exists)
Skill description mentions ".NET"
*.tsx, *.ts
Frontend skill (if exists)
Skill description mentions "React" or "component"
*.py
Python skill (if exists)
Skill description mentions "Python"
*.test.*, *.spec.*
Same skill as source file
Match source extension
For each matched skill: Identify the path to its SKILL.md and references/ directory (if exists).
Skip skills whose reference directories are missing.
# Find commits for each ticket by searching commit messages
git log --all --grep="PROJ-370" --name-only --pretty=format:"" | sort -u
This returns the files that were touched by commits mentioning the ticket ID.
The orchestrator identifies the current paths of those files for review (since
the code has been merged, HEAD has the latest state).
Important: In historical mode, the orchestrator can still make fixes (the code
exists on the current branch at HEAD). Fixes are applied as new changes, and
subsequent re-runs use active mode detection automatically.
1d. Show audit plan
Audit Plan
==========
Mode: Active (uncommitted changes on feature/PROJ-370-registration)
Tickets: PROJ-370, PROJ-371
Phase 1 - Acceptance Criteria:
PROJ-370: 4 criteria from docs/roadmap/jira/phase-3-implementation.jira.md
PROJ-371: 3 criteria from docs/roadmap/jira/phase-3-implementation.jira.md
Phase 2 - Architecture Compliance:
5 architecture docs loaded
12 files to review
Phase 3 - Skill Compliance:
dotnet-api: 10 .cs files (PROJ-370: 6, PROJ-371: 4)
Proceed? [Yes / Modify scope]
Step 2: Run Phase 1 — Acceptance Criteria
For each ticket, spawn an independent Opus subagent:
Spawn independent Opus subagents (one per architecture doc file — e.g., if
docs/architecture/ has 4 .md files, spawn 4 agents, each reviewing against one doc):
Agent receives: Path to one architecture doc + file paths to review
Agent does NOT receive: Acceptance criteria, skill paths, or other architecture areas
Agent task: Read the architecture doc and source files, evaluate compliance per rule as PASS or FAIL
Step 5: Run Phase 4 — WARN Resolution & Documentation
After all FAILs are fixed and all three phases are green, enter WARN Resolution to categorize, document, and persist all WARN dispositions.
Purpose: Create a traceable record of all WARNs, decisions, and rationale. Enable future audits to reference past decisions and avoid re-flagging accepted patterns.
4a. Collect All WARNs
Aggregate WARNs from all three phases:
Phase 1 WARNs (acceptance criteria)
Phase 2 WARNs (architecture compliance)
Phase 3 WARNs (skill compliance)
Deduplicate if the same issue was flagged by multiple agents (same rule + same files).
"Which ticket will address this?" (e.g., PROJ-380)
Improvement
"Update architecture docs?" [Now / Queue / No]
Divergence
"Add as standing override?" [Yes / No]
Doc Drift
"Priority?" [High / Medium / Low]
4d. Assign WARN IDs
Read.claude/audits/warns/by-status.yaml (if exists) to find highest existing ID (or start at W-001).
Assign sequential IDs to new WARNs: W-{NNN}.
4e. Write Resolution Files
Readreferences/warn-resolution-tracking.md § Write Patterns for the full write sequence and data formats. Create/update all tracking files listed there.
4f. Update CLAUDE.md (Optional)
If any standing overrides were added, offer to update CLAUDE.md:
## Audit Configuration### Standing Overrides
See `.claude/audits/overrides.yaml` for the canonical list.
This section summarizes key overrides for human reference.
| Override | Rationale |
|----------|-----------|
| Exception-based error handling | ADR-007, ExceptionHandlingMiddleware |
4g. Create JIRA Tickets (for Gaps)
For each gap WARN where user selected "create ticket now":
Use /jira create to create the ticket
Record ticket ID in by-status.yaml and detail file
Key limits: 3 fix cycles per phase, 7 total cycles, STOP on contradictory feedback or churn (same file modified 3+ times). When a loop is detected, compile a conflict report and ask the user for direction.
