Observability First Debugging

Systematic debugging methodology that eliminates guessing and speculation. Add instrumentation to gather specific data that fully explains the problem. Evidence before hypothesis. Observation before solution. Triggers on: debugging, error investigation, 'why is this failing', unexpected behavior, test failures, non-zero exit codes, stack traces.

365 stars 47 forksSoftware Development Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add NTCoding/claude-skillz

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add NTCoding/claude-skillz --skill observability-first-debugging
Manual install
git clone --depth 1 https://github.com/NTCoding/claude-skillz.git /tmp/claude-skillz
mkdir -p ~/.claude/skills
cp -r /tmp/claude-skillz/observability-first-debugging ~/.claude/skills/observability-first-debugging

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Observability-First Debugging

Stop guessing. Add observability. Understand what's actually happening.

## Core Principle

**Measure before you act.** When something isn't working, the solution is almost never to guess and try random fixes. The solution is to add instrumentation that produces the specific information needed to fully explain the issue.

## The Problem

Agents (and developers) fall into a guess-and-check trap:
- Try something → doesn't work
- Guess what might fix it → doesn't work
- Try another random thing → doesn't work
- User gets frusrtrated as the flailing continues

**Why this happens:** Insufficient data. You don't know what's actually happening, so you're shooting in the dark.

## The Solution

**Make the invisible visible.** Add logging, print statements, assertions, or debugging output that shows you:
- What values variables actually contain
- Which code paths are executing
- What external systems are returning
- Where expectations diverge from reality

## Debugging Protocol

### 1. Reproduce & Document Symptoms

**What exactly is failing?**
- Exact error message (copy-paste, don't paraphrase)
- Expected behavior vs actual behavior
- Minimal reproduction steps

**Don't:**
- Guess at what the error "probably means"
- Assume you know the cause from the symptom

### 2. Add Observability FIRST

**Before forming hypotheses, instrument the system:**

Add logging/print statements to show:
- Input values at function entry
- Intermediate computation results
Read the full skill on GitHub

Details

Skill name
observability-first-debugging
Path
observability-first-debugging/SKILL.md
Repo updated
24 March 2026

FAQ

What does the Observability First Debugging skill do?

Systematic debugging methodology that eliminates guessing and speculation. Add instrumentation to gather specific data that fully explains the problem. Evidence before hypothesis. Observation before solution. Triggers on: debugging, error investigation, 'why is this failing', unexpected behavior, test failures, non-zero exit codes, stack traces.

How do I install the Observability First Debugging skill?

Claude Code plugin: /plugin marketplace add NTCoding/claude-skillz. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Observability First Debugging popular?

It lives in NTCoding/claude-skillz, which has 365 GitHub stars and 47 forks.

Related skills

Architect Refine Critique

365

NTCoding/claude-skillz

Three-phase design review. Chain architect → refiner → critique subagents. Triggers on: 'design review', 'architecture review', '/arc', system design proposals, significant refactoring decisions, new service or module design.

Software Development47

Challenge That

365

NTCoding/claude-skillz

Force critical evaluation of proposals, requirements, or decisions by analyzing from multiple adversarial perspectives. Triggers on: accepting a proposal without pushback, 'sounds good', 'let's go with', design decisions with unstated tradeoffs, unchallenged assumptions, premature consensus. Invoke with /challenge-that.

Software Development47

Concise Output

365

NTCoding/claude-skillz

Enforces brevity and signal-over-noise in all outputs. Eliminates verbose explanations, filler phrases, and unnecessary elaboration. Triggers on: every response (governs output length and density when loaded).

Other47

Separation of Concerns

365

NTCoding/claude-skillz

Enforces code organization using features/ (verticals), platform/ (horizontals), and shell/ (thin wiring). Triggers on: code organization, file structure, where does this belong, new file creation, refactoring.

Software Development47

Lightweight Implementation Analysis Protocol

365

NTCoding/claude-skillz

This skill should be used when fixing bugs, implementing features, debugging issues, or making code changes. Ensures understanding of code flow before implementation by: (1) Tracing execution path with specific file:line references, (2) Creating lightweight text diagrams showing class.method() flows, (3) Verifying understanding with user. Prevents wasted effort from assumptions or guessing. Triggers when users request: bug fixes, feature implementations, refactoring, TDD cycles, debugging, code analysis.

Software Development47

Software Design Principles

365

NTCoding/claude-skillz

Object-oriented design principles including object calisthenics, dependency inversion, fail-fast error handling, feature envy detection, and intention-revealing naming. Triggers on: writing new classes or functions, refactoring, code review, 'clean up', method longer than 10 lines, feature envy, primitive obsession, deep nesting.

Software Development47

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.