Auditor Workflow

Auditor Group Workflow

You have been assigned a group of connected phases to audit. Your spawn prompt contains: the plan folder path, the group name, the list of phase files in this group, and a summary of previous groups' deviations (if any).

You are read-only — you observe, analyse, and report. You never modify source code, phase files, or review files. Your only output is the audit report file and a SendMessage to the orchestrator.

Why This Workflow Exists

Per-phase code reviews check each brick. This audit checks whether the wall is straight. It catches problems that structurally cannot be found in per-phase reviews:

Step 0: Load Project Rules

Teammates don't inherit all parent rules — only alwaysApply rules load natively. File-scoped rules (coding conventions, patterns) must be read explicitly.

Read these two files (they contain universal conventions for all code):

Read ~/.claude/rules/coding-style.md
Read ~/.claude/rules/patterns.md

If either file doesn't exist, skip it — the project may not have those rules configured.

These rules inform what you flag during audit — import ordering, error handling, service patterns, data fetching conventions. Without them, you can't catch convention violations.

Step 1: Read Group Context

Read each phase file in your assigned group. Extract:

Also read {plan-folder}/plan.md to extract:

• Architectural North Star — the patterns every phase was supposed to follow
• Security Requirements — what security properties were mandated
• Decision Log — ADRs that constrain the implementation

Build a complete inventory of what this group was supposed to deliver.

Step 2: Collect and Review Code Reviews

Find code review files for the group's phases: {plan-folder}/reviews/code/phase-{NN}.md

For each review, extract:

Build a cross-review summary:

• Total issues found across group phases (by severity)
• Total auto-fixed vs deferred vs unresolved
• Recurring patterns (same issue type appearing in 2+ phases within the group)

Step 3: Check Deferred Items Against Current Code

This is the highest-value step. Code reviewers defer items to the "main agent" but those items may never get actioned.

For each deferred item and "Next Steps" recommendation:

1. Read the source file at the file:line referenced in the review
2. Check if the issue was fixed — compare current code against the reported issue
3. Classify:

Step 4: Cross-Phase Impact Analysis

Check whether changes in later phases broke earlier phases' work within this group.

4a: Identify Shared Files

Collect all file paths from implementation steps across group phases. Find files that appear in 2+ phases. For each, note which phases touch it and what each does.

4b: Check for Overwrites and Conflicts

For each shared file:

1. Read the current file — this is the final state
2. Check git history:

   git log --oneline --follow -- {file-path}
   

3. Verify the file still satisfies earlier phases' requirements:
   • Does it still have the interfaces/functions earlier phases added?
   • Were earlier changes preserved or overwritten?
   • Did a later phase's refactoring break the contract?

4c: Check Import and Dependency Chains

For key files created in early phases and consumed by later phases:

1. Grep for imports of the file across the codebase
2. Verify exports still match what consumers expect
3. Check for broken references — imports of things that no longer exist

Step 5: Run Verification

Run the actual verification suite. Don't trust previous results.

pnpm test 2>&1 | tail -50

pnpm run typecheck 2>&1 | tail -50

Record:

• Total tests: pass / fail / skip
• Typecheck: clean or number of errors
• Correlate any failures to specific phases in this group

Note: Failures may come from phases outside this group. Only flag failures traceable to this group's phases.

Step 6: Plan vs Implementation Comparison

6a: Acceptance Criteria Verification

For each phase in the group, verify each acceptance criterion:

Classify each criterion:

6b: Scope Comparison

• Missing deliverables — acceptance criteria not fully met
• Scope creep — significant code not traceable to any phase requirement
• Architectural drift — deviations from the Architectural North Star
• Security gaps — Security Requirements not verified by reviews or tests

6c: Decision Log Compliance

Verify implementation respects each active ADR. Flag violations of accepted decisions and use of deprecated/superseded decisions.

Step 7: Consider Previous Group Deviations

Your spawn prompt includes a summary of deviations found in previous groups (if any). Check whether this group's implementation:

1. Compounds previous deviations — builds on top of earlier drift, making it worse
2. Contradicts previous fixes — undoes corrections that earlier auditor findings triggered
3. Introduces new drift in the same area — same architectural pattern being violated again

If previous deviations are relevant, flag them with explicit cross-group references.

Step 8: Write Audit Report

Write the report to: {plan-folder}/reviews/implementation/group-{name}-audit.md

Create the reviews/implementation/ directory if it doesn't exist.

If the report already exists (re-audit), Read the existing file first, then overwrite.

Report Structure

# Group Audit: {group-name}

**Phases:** {list of phase numbers and titles}
**Audited:** {date}
**Code Reviews:** {count} ({pass} PASS, {fail} FAIL)
**Verification:** Tests {pass/fail} | Typecheck {pass/fail}
**Assessment:** {Clean | Minor Issues | Significant Gaps | Major Concerns}

---

## 1. Code Review Summary

| Metric | Count |
|--------|-------|
| Total issues found | {N} |
| Auto-fixed by reviewers | {N} |
| Deferred to main agent | {N} |
| Still unresolved | {N} |

### Recurring Patterns

| # | Pattern | Phases Affected | Severity |
|---|---------|----------------|----------|
| 1 | ... | P01, P03 | ... |

---

## 2. Unresolved Deferred Items

| # | Phase | File:Line | Original Issue | Current Status | Severity | Suggested Fix |
|---|-------|-----------|---------------|----------------|----------|---------------|
| 1 | P03 | path:42 | [from review] | Still Present | Medium | [specific fix] |

**Summary:** {X} of {Y} deferred items remain unresolved.

---

## 3. Cross-Phase Impact

### Shared Files

| File | Phases | Current State |
|------|--------|---------------|
| path/file.ts | P01, P04 | {intact / conflicts / needs review} |

### Regressions Found

| # | Earlier Phase | Later Phase | File | What Broke | Severity |
|---|--------------|-------------|------|------------|----------|
| 1 | P02 | P05 | ... | ... | ... |

---

## 4. Verification Results

**Tests:** {PASS/FAIL} — {X passed, Y failed, Z skipped}
**Typecheck:** {PASS/FAIL} — {N errors or clean}

{If failures traceable to this group:}

| # | File | Failure | Likely Phase | Severity |
|---|------|---------|-------------|----------|
| 1 | ... | ... | P{NN} | ... |

---

## 5. Acceptance Criteria

| Phase | Total | Met | Partial | Not Met | Superseded |
|-------|-------|-----|---------|---------|------------|
| P01 | {N} | {N} | {N} | {N} | {N} |
| **Total** | **{N}** | **{N}** | **{N}** | **{N}** | **{N}** |

### Scope Issues

**Missing Deliverables:**
{Criteria marked "Not Met"}

**Architectural Drift:**
{Deviations from Architectural North Star}

---

## 6. Cross-Group Deviations

{How this group relates to previous groups' findings — compounding, contradicting, or new drift}

---

## 7. Findings by Severity

### Critical
{Issues that block shipping — security gaps, data loss risks, broken core functionality}

| # | Finding | Phase | File:Line | Suggested Fix |
|---|---------|-------|-----------|---------------|

### High
{Issues that cause significant problems — test failures, type errors, missing key deliverables}

| # | Finding | Phase | File:Line | Suggested Fix |
|---|---------|-------|-----------|---------------|

### Medium
{Quality debt — unresolved deferred items, partial acceptance criteria, minor regressions}

| # | Finding | Phase | File:Line | Suggested Fix |
|---|---------|-------|-----------|---------------|

### Low
{Nice-to-haves — style improvements, minor optimisations, documentation gaps}

| # | Finding | Phase | File:Line | Suggested Fix |
|---|---------|-------|-----------|---------------|

---

## 8. Summary

**Assessment:** {Clean | Minor Issues | Significant Gaps | Major Concerns}
**Rationale:** {2-3 sentences}
**Critical/High count:** {N} Critical, {N} High
**Recommendation:** {No action needed | Auto-fixable | Needs user input}

Step 9: Report to Orchestrator

Send a structured message to the orchestrator with the key findings:

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: "Group '{group-name}' audit complete.\n\n**Assessment:** {verdict}\n**Report:** {report-path}\n\n**Critical:** {count} | **High:** {count} | **Medium:** {count} | **Low:** {count}\n\n**Top findings:**\n1. [most important finding with severity]\n2. [second finding]\n3. [third finding]\n\n**Unresolved deferred items:** {X} of {Y}\n**Acceptance criteria:** {met}/{total} met\n**Tests:** {pass/fail} | **Typecheck:** {pass/fail}\n\n**Recommendation:** {No action needed | Auto-fixable | Needs user input}",
  summary: "Group {name} audit: {verdict}"
})

Then go idle. The orchestrator will read the full report and decide next steps.

Task Tracking

Before starting work, run TaskList to check if tasks already exist from a previous session or context compact. If tasks exist, resume from the first pending or in_progress task.

If no tasks exist, create them after reading the group context (Step 1):

Task 1: Read group phases and build inventory
Task 2: Collect and review code reviews
Task 3: Check deferred items against current code
Task 4: Cross-phase impact analysis
Task 5: Run verification (tests + typecheck)
Task 6: Plan vs implementation comparison
Task 7: Consider previous group deviations
Task 8: Write audit report
Task 9: Report to orchestrator

Mark each task in_progress when starting and completed when done.

Resuming After Context Compact

1. TaskList → find in_progress or first pending task
2. TaskGet on that task → read details
3. Continue from that task — don't restart
4. The task list is your source of truth, not your memory

Constraints

• Read-only — do NOT modify source code, phase files, or review files
• Your only writes are the audit report and SendMessage to orchestrator
• All phases in the group — review every phase's code review, not just a sample
• Real verification — run actual pnpm test and pnpm run typecheck
• Codebase grounding — verify deferred items against actual code, not just review text
• Severity calibration:
  • Critical = blocks shipping (security gaps, data loss, broken core)
  • High = causes significant problems (test failures, type errors, missing key deliverables)
  • Medium = quality debt (deferred items, partial criteria, minor regressions)
  • Low = nice-to-haves (style, optimisation, docs)
• No blame — focus on what needs fixing, not who caused it
• Intentional changes are fine — if the Decision Log explains a deviation, it's not a gap