SuperAPI AI Directory

outfitter-check

General & other

View repository

Updated 10-16 03:13

About this skill

Outfitter Check

Verify Outfitter compliance and produce a structured report.

Goal

Scan a codebase and produce a Compliance Report at .agents/notes/YYYY-MM-DD-outfitter-check.md documenting:

  1. What violations were found (by severity)
  2. Where they are (file:line)
  3. How to fix them (with pattern references)

Constraints

DO:

  • Load outfitter-atlas first for pattern knowledge
  • Scan systematically using the diagnostic commands
  • Rank findings by severity (Critical > High > Medium > Low)
  • Reference fieldguide patterns for fixes
  • Produce a Compliance Report at the end

DON'T:

  • Skip categories during scanning
  • Report issues without actionable guidance
  • Mix severity levels (keep them separate)
  • Forget to check the target scope (file, directory, or full codebase)

Steps

  1. Load outfitter-atlas for pattern expertise
  2. Determine scope — what are we checking?
  3. Run diagnostics — systematic anti-pattern scan
  4. Categorize findings — rank by severity
  5. Produce report — using TEMPLATE.md
  6. Migration guidance — detect version gaps and compose upgrade instructions

Step 1: Determine Scope

Ask or infer the target:

Scope When Command Modifier
Single file "Check this file" rg PATTERN path/to/file.ts
Directory "Check src/handlers" rg PATTERN path/to/dir/
Full codebase "Check compliance" rg PATTERN --type ts

Exclude test files unless specifically requested:

rg PATTERN --type ts -g "!*.test.ts" -g "!__tests__/*"

Step 2: Run Diagnostics

Run each scan and collect results.

Critical: Exception Control Flow

# Thrown exceptions (must convert to Result)
rg "throw new" --type ts -g "!*.test.ts" -n

# try/catch control flow (must convert to Result checking)
rg "try \{" --type ts -g "!*.test.ts" -n

Why critical: Breaks type safety, loses error context, makes control flow unpredictable.

High: Logging and Paths

# Console usage (must use ctx.logger)
rg "console\.(log|error|warn|info|debug)" --type ts -g "!*.test.ts" -n

# Hardcoded home paths (must use XDG via @outfitter/config)
rg "(homedir\(\)|~\/\.)" --type ts -g "!*.test.ts" -n

Why high: Console breaks structured logging; hardcoded paths break portability.

Medium: Type Safety

# Custom error classes (should use taxonomy)
rg "class \w+Error extends Error" --type ts -n

# Handlers without context parameter
rg "Handler<.*> = async \(input\)" --type ts -n

# Missing Result type returns
rg "async.*Handler.*\{" --type ts -A 10 | rg "return [^R]" -B 5

Why medium: Reduces type safety and pattern consistency.

Low: Style and Documentation

# process.exit without exitWithError
rg "process\.exit\(" --type ts -g "!*.test.ts" -n

# Missing .describe() on Zod schemas used with MCP
rg "z\.(string|number|boolean|object)\(\)(?!.*\.describe)" --type ts -n

Why low: Affects agent experience and exit code consistency.

Step 3: Categorize Findings

Count results and assign severity:

Severity Findings Action
Critical throw/try-catch in handlers Must fix before merge
High console.log, hardcoded paths Should fix before merge
Medium Custom errors, missing context Fix when touching file
Low Style issues, missing describe Nice to have

Severity Definitions

Level Impact Examples
Critical Breaks core patterns, causes runtime issues Thrown exceptions, unvalidated paths
High Breaks observability or portability Console logging, hardcoded paths
Medium Reduces type safety or consistency Custom errors, missing context param
Low Affects polish, not correctness Style, documentation gaps

Step 4: Produce Report

Write the Compliance Report to .agents/notes/YYYY-MM-DD-outfitter-check.md using TEMPLATE.md.

# Create directory if needed
mkdir -p .agents/notes

# Report path (replace YYYY-MM-DD with today's date)
# .agents/notes/2024-01-15-outfitter-check.md

Pass Criteria

Status Criteria
PASS 0 critical, 0 high
WARNINGS 0 critical, 1+ high or medium
FAIL 1+ critical

Quick Summary

## Compliance: [scope]

**Status**: PASS | WARNINGS | FAIL
**Issues**: X critical, Y high, Z medium, W low

{ details follow }

Fix References

Point to fieldguide patterns for each issue type:

Issue Fix Pattern
throw new patterns/conversion.md
try/catch patterns/results.md
console.log patterns/logging.md
Hardcoded paths patterns/file-ops.md
Custom errors patterns/errors.md
Missing context patterns/handler.md

Quick Check

For a fast pass/fail without full report:

# Critical count (should be 0)
rg "throw new|try \{" --type ts -g "!*.test.ts" -c | wc -l

# High count (should be 0)
rg "console\.(log|error|warn)|homedir\(\)" --type ts -g "!*.test.ts" -c | wc -l

Step 5: Migration Guidance

After the compliance scan, detect installed @outfitter/* versions and check for available migrations using the outfitter upgrade command.

# Check for available updates (human-readable)
bunx outfitter upgrade --guide --cwd .

For JSON output (version data only, does not include migration docs):

bunx outfitter upgrade --json --cwd .

If updates are found, append a Migration Guidance section to the compliance report. If all packages are up to date, note that in the report.

The command:

  1. Reads package.json for @outfitter/* dependencies
  2. Queries npm for latest versions
  3. When --guide is used, composes migration docs from the kit plugin's shared migrations

Related Skills

  • outfitter-atlas — Patterns and fix guidance (load first)
  • outfitter-start — Full adoption workflow with staged plan
  • debug-outfitter — Deep investigation of specific issues