Stack Audit Skill | Agent Skills

Stack Audit

Scan a codebase to identify Outfitter Stack adoption candidates and generate an audit report.

Quick Start

Option 1: Run the scanner (recommended for large projects)

bun run plugins/outfitter-stack/skills/stack-audit/scripts/init-audit.ts [project-root]

Generates .outfitter/adopt/ with:

audit-report.md - Scan results and scope
plan/ - Stage-by-stage task files

Option 2: Manual scan (smaller projects)

Run the audit commands below to understand scope.

Audit Commands

Critical Issues - Exceptions

# Count throw statements
rg "throw (new |[a-zA-Z])" --type ts -c

# List throw locations
rg "throw (new |[a-zA-Z])" --type ts -n

# Count try-catch blocks
rg "(try \{|catch \()" --type ts -c

Console Usage

# Count console statements
rg "console\.(log|error|warn|debug|info)" --type ts -c

# List console locations
rg "console\.(log|error|warn|debug|info)" --type ts -n

Hardcoded Paths

# Homedir usage
rg "(homedir\(\)|os\.homedir)" --type ts -c

# Tilde paths
rg "~/\." --type ts -c

# Combined path issues
rg "(homedir|~\/\.)" --type ts -n

Custom Error Classes

# Find custom error classes
rg "class \w+Error extends Error" --type ts -n

# Count usage of custom errors
rg "new MyCustomError\(" --type ts -c

Generated Structure

.outfitter/adopt/
├── audit-report.md           # Scan results, scope, recommendations
└── plan/
    ├── 00-overview.md        # Status dashboard, dependencies
    ├── 01-foundation.md      # Dependencies, context, logger
    ├── 02-handlers.md        # Handler conversions
    ├── 03-errors.md          # Error taxonomy mappings
    ├── 04-paths.md           # XDG path migrations
    ├── 05-adapters.md        # CLI/MCP transport layers
    ├── 06-documents.md       # Documentation updates
    └── 99-unknowns.md        # Items requiring review

Migration Stages

| Stage | Blocked By | Focus | |-------|------------|-------| | 1. Foundation | - | Install packages, create context/logger | | 2. Handlers | Foundation | Convert throw to Result | | 3. Errors | Handlers | Map to error taxonomy | | 4. Paths | - | XDG paths, securePath | | 5. Adapters | Handlers | CLI/MCP wrappers | | 6. Documents | All | Update docs to reflect patterns | | 99. Unknowns | - | Review anytime |

Audit Report Fields

| Field | Description | |-------|-------------| | Exceptions | throw statements to convert to Result | | Try/Catch | Error handling blocks to restructure | | Console | Logging to convert to structured logging | | Paths | Hardcoded paths to convert to XDG | | Error Classes | Custom errors to map to taxonomy | | Handlers | Functions with throws to convert | | Unknowns | Complex patterns requiring review |

Error Taxonomy Reference

When mapping errors, use this reference:

| Original | Outfitter | Category | |----------|-----------|----------| | NotFoundError | NotFoundError | not_found | | InvalidInputError | ValidationError | validation | | DuplicateError | ConflictError | conflict | | UnauthorizedError | AuthError | auth | | ForbiddenError | PermissionError | permission | | Generic Error | InternalError | internal |

Effort Estimation

| Count | Effort Level | |-------|--------------| | 0 | None | | 1-5 | Low | | 6-15 | Medium | | 16+ | High |

Interpreting Results

High-Priority Items

Functions with 3+ throw statements (complex error handling)
Files with 3+ try-catch blocks (may need restructuring)
Custom error classes with high usage counts

Medium-Priority Items

Isolated throw statements (simple conversions)
Console logging (straightforward migration)
Hardcoded paths (mechanical replacement)

Low-Priority Items

Documentation updates (can happen last)
Test file updates (follow handler changes)

Next Steps After Audit

Review audit-report.md for accuracy
Adjust priorities in plan/00-overview.md
Begin with Stage 1 (Foundation)
Load outfitter-stack:stack-patterns for conversion guidance
Load outfitter-stack:stack-templates for scaffolding

Constraints

Always:

Run audit before planning adoption
Review unknowns for complex patterns
Estimate effort before committing

Never:

Skip the audit phase
Underestimate try-catch complexity
Ignore custom error classes

Related Skills

outfitter-stack:stack-patterns - Target patterns reference
outfitter-stack:stack-templates - Component templates
outfitter-stack:stack-review - Verify compliance

Agent Skills: Stack Audit

Install this agent skill to your local

Skill Files