stack-debug_skill

Overview

This skill troubleshoots Outfitter Stack issues across Result handling, MCP (tool) problems, CLI output and exit codes, and logging. It focuses on concrete checks and fixes to quickly surface root causes and restore expected behavior. Use it when Result values are wrong, tools don't register or invoke, CLI output is missing or exit codes are incorrect, or logging/redaction behaves unexpectedly.

How this skill works

The skill inspects common failure points and suggests code-level corrections: verifying Result usage and async/await, preserving TypeScript narrowing, and using error tags for precise handling. It checks MCP registration, Zod schema descriptions, and async handlers that must return Result objects. For CLI it enforces awaiting output, forcing JSON mode, and mapping errors to standard exit codes. For logging it validates redaction settings, context propagation, and log level configuration.

When to use it

• You see Result values consistently return err when ok was expected
• A registered MCP tool is missing from the server or never invoked
• CLI commands produce no JSON or exit with the wrong code
• Sensitive fields are not being redacted or logs lack request context
• TypeScript narrowing stops working after result reassignment

Best practices

• Always await Promises that return Result<T, E> to avoid returning Promises instead of Results
• Avoid reassigning a Result variable after an isOk/isErr check; use separate variables to preserve narrowing
• Use error discriminators (_tag) to switch on specific error shapes for safe handling
• Register MCP tools before calling server.start() and validate Zod schemas with .describe()
• Await output(...) before calling process.exit and use exitWithError for proper exit codes
• Enable logger redaction and use createChildLogger to propagate request context

Example use cases

• A command prints nothing because output(data) was not awaited and process exited early
• An MCP tool's handler never runs because it was registered after server.start()
• Validation errors are losing details; inspect validateInput usage and Zod safeParse results
• Exit codes are generic; map Result error categories to the documented exit table
• Secrets like passwords remain in logs; enable redaction and add custom patterns