Agent skill

stack-debug

Troubleshoots Outfitter Stack issues including Result handling, MCP problems, CLI output, exit codes, and logging. Use when debugging stack-specific issues, unexpected errors, wrong output modes, or when "debug Result", "MCP not working", "wrong exit code", or "logging issue" are mentioned.

View SKILL.md on GitHub Repository
Stars 26
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/outfitter-dev/agents/tree/main/plugins/outfitter-stack/skills/stack-debug

SKILL.md

Stack Debugging

Troubleshoot @outfitter/* package issues.

Result Issues

Always Getting Error

Symptom: Result is err when it should be ok.

Check validation:

typescript
const inputResult = validateInput(rawInput);
if (inputResult.isErr()) {
  console.log("Validation failed:", inputResult.error.details);
  return inputResult;
}

Check async:

typescript
// BAD: Missing await
const result = getUser(id);  // Promise, not Result!

// GOOD
const result = await getUser(id);

Type Narrowing Broken

Symptom: TypeScript doesn't know type after isOk().

typescript
// BAD: Reassigning breaks narrowing
let result = await getUser(id);
if (result.isOk()) {
  result = await updateUser(result.value);  // Breaks!
}

// GOOD: Separate variables
const getResult = await getUser(id);
if (getResult.isErr()) return getResult;
const updateResult = await updateUser(getResult.value);

Error Type Lost

Use _tag for narrowing:

typescript
if (result.isErr()) {
  switch (result.error._tag) {
    case "ValidationError":
      console.log(result.error.details);
      break;
    case "NotFoundError":
      console.log(result.error.resourceId);
      break;
  }
}

MCP Issues

Tool Not Appearing

  1. Register before start():

    typescript
    server.registerTool(myTool);
server.start();  // After registration!

  2. Check schema is valid Zod with .describe():

    typescript
    const schema = z.object({
  query: z.string().describe("Required for AI"),
});

Tool Invocation Failing

  1. Verify handler is async:

    typescript
    handler: async (input) => {  // Not sync!
  return Result.ok(data);
}

  2. Return Result, not raw value:

    typescript
    // BAD
return { data: "value" };

// GOOD
return Result.ok({ data: "value" });

CLI Output Issues

JSON Not Printing

  1. Force mode:

    typescript
    await output(data, { mode: "json" });

  2. Check environment:

    bash
    OUTFITTER_JSON=1 myapp list
OUTFITTER_JSON=0 myapp list --json  # Forces human!

  3. Await output:

    typescript
    // BAD
output(data);
process.exit(0);  // May exit before output!

// GOOD
await output(data);

Wrong Exit Code

  1. Use exitWithError:

    typescript
    // BAD
process.exit(1);

// GOOD
exitWithError(result.error);

  2. Exit code table:

    Category Exit
    validation 1
    not_found 2
    conflict 3
    permission 4
    timeout 5
    rate_limit 6
    network 7
    internal 8
    auth 9
    cancelled 130

Logging Issues

Redaction Not Working

typescript
const logger = createLogger({
  redaction: { enabled: true },  // Must be true!
});

// Custom patterns
const logger = createLogger({
  redaction: {
    enabled: true,
    patterns: ["password", "apiKey", "myCustomSecret"],
  },
});

Missing Context

typescript
import { createChildLogger } from "@outfitter/logging";

const requestLogger = createChildLogger(ctx.logger, {
  requestId: ctx.requestId,
  handler: "myHandler",
});

requestLogger.info("Processing", { data });  // Includes requestId

Wrong Level

typescript
const logger = createLogger({
  level: process.env.LOG_LEVEL || "info",
});

// Hierarchy: trace < debug < info < warn < error < fatal
// "info" hides trace and debug

Debugging Tools

Trace Result Chain

typescript
function traceResult<T, E>(name: string, result: Result<T, E>): Result<T, E> {
  console.log(`[${name}]`, result.isOk() ? "OK:" : "ERR:",
    result.isOk() ? result.value : result.error);
  return result;
}

const result = traceResult("getUser", await getUser(id));

Inspect Context

typescript
console.log("Context:", {
  requestId: ctx.requestId,
  hasLogger: !!ctx.logger,
  hasConfig: !!ctx.config,
  hasSignal: !!ctx.signal,
  cwd: ctx.cwd,
});

Validate Zod Schema

typescript
const parseResult = schema.safeParse(rawInput);
if (!parseResult.success) {
  console.log("Zod errors:", parseResult.error.issues);
}

Related Skills

  • outfitter-stack:stack-patterns — Correct patterns
  • outfitter-stack:stack-review — Systematic audit

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

outfitter-dev/agents

stack-feedback

Creates GitHub issues for problems discovered while using @outfitter/* packages. Use when finding bugs, missing features, unclear documentation, or improvement opportunities.

26 0
Explore
outfitter-dev/agents

stack-architecture

Design stack-based systems using @outfitter/* packages. Use when planning new projects, choosing packages, designing handler architecture, or when "architecture", "design", "structure", "plan handlers", or "error taxonomy" are mentioned.

26 0
Explore
outfitter-dev/agents

stack-templates

Templates for creating handlers, CLI commands, MCP tools, and daemon services following Outfitter Stack conventions. Use when scaffolding new components, creating handlers, adding commands, or when "create handler", "new command", "add tool", "scaffold", "template", or "daemon service" are mentioned.

26 0
Explore
outfitter-dev/agents

stack-audit

Scan codebase for Outfitter Stack adoption candidates. Identifies throw statements, console usage, hardcoded paths, and custom errors. Use when assessing adoption scope or checking readiness.

26 0
Explore
outfitter-dev/agents

stack-review

Audits code for Outfitter Stack compliance including Result types, error handling, logging patterns, and path safety. Use for pre-commit reviews, code quality checks, migration validation, or when "audit", "check compliance", "review stack", or "stack patterns" are mentioned.

26 0
Explore
outfitter-dev/agents

stack-patterns

Reference for Outfitter Stack patterns including Result types, Handler contract, Error taxonomy, and @outfitter/* package conventions. Use when learning the stack, looking up patterns, understanding packages, or when "Result", "Handler", "error taxonomy", "OutfitterError", "CLI output", "pagination", "MCP server", "MCP tool", "structured logging", "redaction", "test handler", "daemon", "IPC", or "@outfitter/*" are mentioned.

26 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results