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

7. 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