DEV Community: kai belmo

Debugging with AI: Stop Feeding It Files, Start Feeding It Snapshots

kai belmo — Mon, 08 Jun 2026 20:17:10 +0000

AI coding agents are great at reading and understanding code. But debugging? That’s rarely just a code reading problem.

Most bugs surface because something at runtime didn’t behave: a request payload arrived in an unexpected shape, a condition took the wrong branch, a store dropped a field, or a queue handler mangled the data.

When that happens, the AI defaults to what it knows best (scanning files, Handlers, services, types, tests, helpers) It builds a theory from static text. Sometimes that works, but it’s slow, token-heavy, and noisy. The model is forced to infer runtime truth from source code alone, and it often gets it wrong.

What if you could give the AI a clean, structured snapshot of the exact values that mattered?

The AI agent skill that makes debugging less guessy

That’s exactly why I built the snaplog skill.
Instead of asking your assistant to guess where the bug lives, the skill teaches it a tiny, repeatable workflow:

Describe the bug: “Actor, trigger, expected state, observed state.”
The AI identifies the likely boundary: For example, request input, branch decision, state transition, persistence write, or error path.
The AI adds one or two temporary snaplog.injectLog() calls: Only the variables that matter.
You reproduce the bug.
snaplog writes local structured logs: Usually under .debug/debug.log for Node.
The AI reads the snapshots and reasons from runtime facts: It no longer has to infer everything from static source code.
The temporary instrumentation gets removed.

This saves tokens because the AI gets a compact runtime artifact instead of repeatedly searching broad code paths.

Under the hood: the library that makes it work

The skill itself is small on purpose. It works through a focused npm package: @kaibelmo/snaplog.

It’s a local-first TypeScript runtime snapshot debugger that runs in Node.js, browsers, and browser extensions. Think of it as the sweet spot between messy console.log spam and a full-blown observability platform.

Here’s what using it looks like:

import { createSnaplogClient } from "@kaibelmo/snaplog";
import { createNodeSnaplogTransport } from "@kaibelmo/snaplog/node";

const snaplog = createSnaplogClient({
  runtime: "node",
  source: "checkout/applyDiscount",
  transport: createNodeSnaplogTransport(),
  serialize: {
    redactKeys: ["token", "password"]
  }
});

snaplog.injectLog({
  cart,
  discount,
  finalTotal,
  user
});

Run your reproduction steps, and you get clean, structured logs (default path .debug/debug.log):

{
  "event": "snapshot",
  "variable": "finalTotal",
  "value": 89.99,
  "source": "checkout/applyDiscount",
  "timestamp": "..."
}

The library handles safe serialization, automatic redaction of sensitive keys, simple flow tracking, and multiple storage backends (file logs for Node, extension storage for browsers). It’s deliberately minimal, zero-dependency where possible, and gets out of your way once the bug is fixed.

Why the skill and library work better together

With the snaplog skill, the AI isn’t adding random logs. It’s placing temporary snapshots at the exact points that matter, then reading the captured values directly.

Less code scanning. Fewer guesses. Faster debugging.

Instead of making the model imagine runtime state, you give it the facts.

npx skills add KaiBelmo/snaplog

Github repo: github.com/KaiBelmo/snaplog

TypeScript: Not Always the Answer

kai belmo — Thu, 27 Jul 2023 21:03:28 +0000

JavaScript is a versatile and dynamic programming language that allows developers to build a wide range of applications. However, its dynamic nature can sometimes lead to errors and bugs that are challenging to detect during development. To address this, developers often turn to type annotations to provide clarity and ensure code correctness. Two popular approaches for adding type annotations to JavaScript code are JSDoc and TypeScript.

Understanding JSDoc

JSDoc is a comment syntax that can be used to annotate JavaScript code with type information. JSDoc annotations are not enforced by the JavaScript compiler, but they can be used by linters and IDEs to provide static type checking.
JSDoc annotations are written in the form of @tag, where the tag specifies the type or purpose of the annotated element. For example:

/**
 * @type {string}
 */
const randomestring = "42";

JSDoc also supports more complex type annotations, such as custom objects, arrays, and function signatures.

/**
 * @typedef {Object} Foo
 * @property {string} bar
 * @property {number} nda
 */

/**
 * @type {Foo[]}
 */
const randomObj = [
  { bar: "the answer to life, universe and everything", nda: 42 },
  { bar: "random string", nda: 25 }
];

/**
 * @param {Foo} obj
 * @returns {string}
 */
function randomFunction(obj) {
  return `${obj[0].bar} is ${obj[0].nda}.`;
}

Understanding TypeScript

TypeScript is JavaScript on steroids, adding optional static typing and other powerful features to the language. It allows developers to write a more strict form of JavaScript that helps write less error-prone code.

TypeScript needs to be compiled before it can be executed.

interface Foo {
  bar: string;
  nda: number;
}

const randomObj: Foo[] = [
  { bar: "the answer to life, universe and everything", nda: 42 },
  { bar: "random string", nda: 25 }
];

function randomFunction(obj: Foo): string {
  return `${obj[0].bar} is ${obj[0].nda}.`;
}

JSDoc vs. TypeScript: Choosing the Right Approach

Scenario #1 If you are using a framework like Next.js or Vue, there is always a build step. Therefore, you can ignore JSDoc and use TypeScript.
JSDoc is a favorable option over TypeScript in scenarios where faster shipping is crucial due to the absence of compilation steps. Additionally, it proves beneficial when working with third-party JavaScript libraries without TypeScript support, handling small projects or scripts, and when incrementally adding type annotations to existing JavaScript codebases instead of rewriting them in TypeScript.

useful links

Rich Harris (creator of Svelte) talks about Typescript and JSdoc.

learn recursion: the hard way

kai belmo — Wed, 10 Nov 2021 18:50:24 +0000

"To understand recursion, you must first understand recursion."
this joke is completely wrong because if you want to understand recursion you need to check this blog post.