audit-workflow

# /audit-workflow — Workflow Effectiveness Analysis

**Purpose**: Analyze completed epic workflow to identify bottlenecks, quality issues, and improvement opportunities. Auto-runs after /implement and /finalize phases.

**Command**: `/audit-workflow [epic-slug | auto]`

**When to use**:

- Auto-triggered after `/implement` completes
- Auto-triggered during `/optimize` phase
- Auto-triggered after `/finalize` for post-mortem
- Manual invocation to analyze current epic

---

<instructions>

## Workflow Audit Process

### Step 1: Locate Epic Workspace

**If epic-slug provided:**

```bash
EPIC_DIR="epics/$ARGUMENTS"
```

**If "auto" or no argument:**

```bash
# Find most recent epic
EPIC_DIR=$(ls -td epics/*/ | head -1)
```

**Validate workspace exists:**

```bash
test -d "$EPIC_DIR" && echo "found" || echo "not found"
```

If not found, error: "No epic workspace found. Run /epic first."

### Step 2: Read Epic Artifacts

**Load all epic data for analysis:**

```bash
# Core artifacts
- epic-spec.md (requirements)
- state.yaml (phase tracking)
- sprint-plan.md (dependencies, execution plan)
- tasks.md (task breakdown)
- research.md (research findings)
- plan.md (architecture plan)

# Execution artifacts
- NOTES.md (implementation notes)
- sprints/*/implementation logs
- optimization-report.xml (quality gates)
```

**Extract key metrics:**

- Total phases completed
- Time spent per phase
- Tasks completed vs total
- Quality gate pass/fail rates
- Sprint execution times
- Parallel execution efficiency

### Step 3: Analyze Workflow Effectiveness

**Analysis focus areas** (execute inline - no agent delegation):

1. **Phase efficiency** - time vs value delivered per phase
2. **Bottleneck detection** - which phases took longest
3. **Quality gate effectiveness** - caught issues early?
4. **Sprint parallelization** - actual vs potential speedup
5. **Documentation quality** - XML artifacts complete?
6. **Process adherence** - skipped phases, manual overrides

**Output target:** `audit-report.xml` with findings and recommendations

### Step 4: Bottleneck Detection

**Analyze phase timing:**

```yaml
# From state.yaml
phases:
  specification:
    duration: 2h
    value_score: high
  clarification:
    duration: 1.5h
    value_score: high
  planning:
    duration: 3h
    value_score: high
  tasks:
    duration: 0.5h
    value_score: medium
  implementation:
    duration: 24h # BOTTLENECK: 70% of total time
    value_score: high
  optimization:
    duration: 2h
    value_score: medium
```

**Calculate bottleneck score:**

```
Bottleneck = (phase_duration / total_duration) * (1 / value_score)

If bottleneck_score > 0.5: Flag as major bottleneck
If bottleneck_score > 0.3: Flag as moderate bottleneck
```

**Example findings:**

- "Implementation phase is 70% of total time but high value - acceptable"
- "Clarification phase is 10% of time but low value - consider better upfront spec"
- "Optimization phase caught 0 critical issues - gate may be redundant"

### Step 5: Sprint Parallelization Analysis

**Compare actual vs potential:**

```xml
<sprint_analysis>
  <potential_speedup>
    <sequential_hours>48</sequential_hours>
    <parallel_hours>16</parallel_hours>
    <max_speedup>3.0x</max_speedup>
  </potential_speedup>

  <actual_speedup>
    <sequential_hours>48</sequential_hours>
    <parallel_hours>12</parallel_hours>
    <actual_speedup>4.0x</actual_speedup>
  </actual_speedup>

  <efficiency>
    <percentage>133%</percentage> <!-- exceeded expectations -->
    <reason>S02 and S03 had fewer dependencies than estimated</reason>
  </efficiency>

  <missed_opportunities>
    <!-- Were there sprints that could have run parallel but didn't? -->
    <opportunity sprint_a="S04" sprint_b="S05">
      <reason>Dependency analysis missed that these are independent</reason>
      <potential_time_saved_hours>6</potential_time_saved_hours>
    </opportunity>
  </missed_opportunities>
</sprint_analysis>
```

### Step 6: Quality Gate Effectiveness

**Analyze which gates caught issues:**

```xml
<quality_gate_analysis>
  <gate name="tests" phase="implementation">
    <issues_caught>12</issues_caught>
    <severity_critical>0</severity_critical>
    <severity_high>3</severity_high>
    <severity_medium>9</severity_medium>
    <effectiveness>high</effectiveness>
    <recommendation>Continue - catching issues early</recommendation>
  </gate>

  <gate name="security" phase="optimize">
    <issues_caught>2</issues_caught>
    <severity_critical>0</severity_critical>
    <severity_high>0</severity_high>
    <severity_medium>2</severity_medium>
    <effectiveness>medium</effectiveness>
    <recommendation>Continue - provides safety net</recommendation>
  </gate>

  <gate name="preview" phase="preview">
    <issues_caught>0</issues_caught>
    <manual_time_hours>1.5</manual_time_hours>
    <effectiveness>low</effectiveness>
    <recommendation>Consider auto-skip for non-UI epics</recommendation>
  </gate>
</quality_gate_analysis>
```

### Step 7: Documentation Quality Assessment

**Check XML artifact completeness:**

```javascript
const artifacts = [
  'epic-spec.md',
  'research.md',
  'plan.md',
  'sprint-plan.md',
  'tasks.md'
];

for (const artifact of artifacts) {
  checkCompleteness(artifact, {
    required_tags: [...],
    metadata_present: true,
    references_valid: true
  });
}
```

**Score documentation:**

- Complete (all tags present): 10 pts
- Missing optional tags: -1 pt each
- Missing required tags: -5 pts each
- Broken references: -2 pts each
- Total score: /10

### Step 8: Pattern Detection

**Identify recurring patterns across epics:**

```javascript
// If this is 2nd or 3rd epic, analyze patterns
if (completed_epics >= 2) {
  detectPatterns({
    code_patterns: [
      "Service class structure",
      "Repository pattern usage",
      "Error handling approach",
      "Validation logic",
    ],
    workflow_patterns: [
      "Always clarify authentication approaches",
      "Always research database options",