---
name: step-03-report
description: Generate comprehensive audit report with recommendations
---

# Step 3: Audit Report

## MANDATORY EXECUTION RULES:
- Display COMPLETE report (every component, every issue)
- Group by component type, then by severity
- Include actionable recommendations for each issue
- If --fix mode, apply auto-fixes where safe

## YOUR TASK:
Generate and display the final audit report. Apply auto-fixes if requested.

---

## EXECUTION SEQUENCE:

### 1. Component Inventory Table

Display full inventory:

```markdown
## Component Inventory

### Skills ({count})
| Name | Steps | Templates | Refs | Lines | Status |
|------|-------|-----------|------|-------|--------|
| {name} | {step_count} | {template_count} | {ref_count} | {line_count} | OK/WARN/ERROR |

### Agents ({count})
| Name | Category | Model | Tools | Status |
|------|----------|-------|-------|--------|
| {name} | {category} | {model} | {tool_count} | OK/WARN/ERROR |

### Hooks ({count})
| Event | Matcher | Type | Status |
|-------|---------|------|--------|
| {event} | {matcher} | {type} | OK/WARN/ERROR |
```

### 2. Issues Report

Group by severity, then by component:

```markdown
## Issues Found

### ERRORS ({count}) - Must Fix
| Component | Type | Issue | File | Recommendation |
|-----------|------|-------|------|----------------|
| {name} | {type} | {message} | {file} | {recommendation} |

### WARNINGS ({count}) - Should Fix
| Component | Type | Issue | File | Recommendation |
|-----------|------|-------|------|----------------|
| {name} | {type} | {message} | {file} | {recommendation} |

### INFO ({count}) - Nice to Have
| Component | Type | Issue | File | Recommendation |
|-----------|------|-------|------|----------------|
| {name} | {type} | {message} | {file} | {recommendation} |
```

### 3. Recommendations by Issue Type

Provide common fix patterns:

```markdown
## Common Fix Patterns

### Missing frontmatter fields
Add required fields to YAML frontmatter:
- `name`: lowercase identifier, max 64 chars
- `description`: multi-line, describe when to use

### Broken step chain
Verify `next_step` in each step file points to existing file.
Steps should follow: step-00-init → step-01-xxx → step-02-xxx → ...

### Missing agent reference
Skills with `context: fork` need a valid `agent` field.
Built-in agents: Explore, Plan, general-purpose, Bash

### Oversized SKILL.md
Keep SKILL.md under 500 lines. Move detailed content to:
- references/ for documentation
- templates/ for code templates
- steps/ for progressive step loading
```

### 4. Auto-Fix (if --fix mode)

If {fix_mode} is true, apply safe fixes:

```
Safe auto-fixes:
  ✅ Add missing `name` field (derive from directory name)
  ✅ Fix broken next_step paths (if obvious rename)
  ✅ Add missing description placeholder
  ✅ Fix invalid model values (suggest closest match)

Unsafe (skip, only recommend):
  ❌ Restructure SKILL.md sections
  ❌ Change skill type or architecture
  ❌ Modify hook configurations
  ❌ Delete files
```

For each auto-fix applied:
- Use Edit tool to modify the file
- Record the change
- Display what was changed

### 5. Final Summary

```markdown
## Audit Summary

| Metric | Value |
|--------|-------|
| Scope | {scope} |
| Components scanned | {total_count} |
| Healthy | {ok_count} |
| With warnings | {warn_count} |
| With errors | {error_count} |
| Auto-fixes applied | {fix_count} (if --fix) |

### Health Score: {score}%
(100% = no errors or warnings)
```

---

## SUCCESS METRICS:
- Complete report displayed with all components
- Every issue has an actionable recommendation
- Auto-fixes applied if --fix mode (safe fixes only)
- Health score calculated and displayed
- Report is scannable (tables, not prose)
