Debug Outfitter

Debug Outfitter

Systematic debugging process for @outfitter/* package issues.

Goal

Investigate issues methodically and produce a structured report documenting:

1. What was observed (symptoms)
2. What was investigated (evidence)
3. What was found (root cause)
4. What to do about it (fix or escalation)

Constraints

DO:

• Gather evidence before forming hypotheses
• Use the diagnostic patterns in this skill
• Reference outfitter-atlas for correct patterns
• Assign a confidence level to your diagnosis
• Produce a Debug Report at the end

DON'T:

• Apply random fixes hoping something works
• Skip the evidence collection phase
• Leave issues undiagnosed
• Forget to document findings

Steps

1. Load the outfitter-atlas skill to gain expertise in the Outfitter packages.
2. Collect evidence — gather symptoms before hypothesizing
3. Categorize the issue — identify which area is affected
4. Investigate — use category-specific diagnostics
5. Produce a Debug Report using TEMPLATE.md
6. If the issue is in Outfitter's packages themselves, escalate via outfitter-issue

Stage 1: Evidence Collection

Gather symptoms before forming hypotheses.

What to Collect

• Error messages and stack traces
• Unexpected output vs expected output
• Exit codes (actual vs expected)
• Relevant code snippets
• Environment details (Bun version, package versions)

Quick Diagnostic Commands

# Check package versions
bun pm ls | grep @outfitter

# Find Result usage patterns
rg "Result\.(ok|err)" --type ts -A 2

# Find error handling
rg "isErr\(\)|isOk\(\)" --type ts -A 3

# Check for thrown exceptions (anti-pattern)
rg "throw new" --type ts

Stage 2: Categorize the Issue

Based on symptoms, identify the issue category:

Stage 3: Targeted Investigation

Result Handling Issues

Always getting error:

// Check: Missing await?
const result = getUser(id); // ❌ Promise, not Result!
const result = await getUser(id); // ✅

// Check: Validation failing?
const validated = validate(input);
if (validated.isErr()) {
  console.log("Validation failed:", validated.error.context);
}

Type narrowing broken:

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

// ✅ 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
if (result.isErr()) {
  switch (result.error._tag) {
    case "ValidationError":
      console.log(result.error.context);
      break;
    case "NotFoundError":
      console.log(result.error.resourceId);
      break;
  }
}

MCP Issues

Tool not appearing:

1. Verify registration happens before start():

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

2. Check schema has .describe() on all fields:

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

Tool invocation failing:

1. Handler must be async:

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

2. Must return Result:

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

CLI Output Issues

JSON not printing:

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

// Check environment
// OUTFITTER_JSON=1 forces JSON
// OUTFITTER_JSON=0 forces human when no explicit mode is set

// Await output before exit
await output(data); // ✅
// process.exit(0);  // May exit before output completes

Wrong exit code:

// ❌ process.exit(1);
// ✅ exitWithError(result.error);

Exit code reference:

Logging Issues

Redaction not working:

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

Missing context:

const requestLogger = createChildLogger(ctx.logger, {
  requestId: ctx.requestId,
  handler: "myHandler",
});
requestLogger.info("Processing", { data }); // Includes requestId

Wrong level:

// Hierarchy: trace < debug < info < warn < error < fatal
// "info" hides trace and debug
const logger = createLogger({
  level: process.env.LOG_LEVEL || "info",
});

Stage 4: Document Findings

Assess confidence in your diagnosis:

Based on diagnosis, recommend:

• Code fix — Provide specific fix with before/after
• Pattern guidance — Reference correct pattern from fieldguide
• Escalation — If issue is in Outfitter itself, use outfitter-issue

Produce a Debug Report using TEMPLATE.md.

When to Escalate

If investigation reveals an issue in @outfitter/* packages themselves (not user code):

1. Document the issue clearly in the Debug Report
2. Recommend using outfitter-issue skill to file an issue
3. Include reproduction steps and expected vs actual behavior

Related Skills

• outfitter-atlas — Correct patterns reference
• outfitter-check — Compliance verification
• outfitter-issue — Report issues to Outfitter team