home / skills / ntcoding / claude-skillz / lightweight-implementation-analysis-protocol

lightweight-implementation-analysis-protocol skill

safe

/lightweight-implementation-analysis-protocol

This skill helps you rapidly understand code flow before implementation, using lightweight traces and diagrams to guide testing and TDD.

npx playbooks add skill ntcoding/claude-skillz --skill lightweight-implementation-analysis-protocol

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.1 KB

---
name: lightweight-implementation-analysis-protocol
description: "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."
version: 1.0.0
---

# Lightweight Implementation Analysis Protocol

Quick understanding before implementation - **just enough to guide TDD, no more**.

## When This Activates

Before creating implementation plans, fix plans, or TDD cycles for bugs/features.

## The Protocol (3 Quick Steps)

### 1. Trace the Flow

Answer these:
- Which event/request triggers this?
- Which file:line handles it?
- Where does the error occur (file:line)?

### 2. Quick Diagram

Simple class.method() flow with relevant data:

```
Event: EventName
  ↓ (contains: relevant fields)
Class.method() [file:line]
  ↓ (what it does)
Class.method() [file:line] ← 💥 Error here
  ↓
Result: What happens
```

**Keep it short** - 5-10 lines max.

### 3. Verify

Ask: "Here's the flow: [diagram]. Correct?"

Wait for confirmation, then proceed.

## Example

```
Problem: Email validation failing

Event: user.email.updated
  ↓ (email: "invalid@")
UpdateUserEmailHandler.execute() [line 281]
  ↓ (validates email format)
EmailValidator.parse() [line 289] ← 💥 Throws ValidationError
  ↓
Result: Error response

Current: Throws
Should: Use safeParse(), return validation error
```

## Rules

- **Keep it lightweight** - This isn't detailed planning, just enough to know what to test
- **Be specific** - File:line, not abstractions
- **Get confirmation** - Don't proceed without it
- **Skip for trivial changes** - Typos, formatting, docs

## Anti-Pattern

❌ **WRONG**: "I'll fix the validation. Here's my plan..."
✅ **RIGHT**: "Let me trace where the error occurs... [diagram]. Correct?"

Overview

This skill enforces a lightweight implementation analysis protocol to clarify code flow before making changes. It is designed for bug fixes, feature work, refactors, and TDD cycles to avoid assumptions that waste time. The goal is a minimal trace-and-verify process that guides testing and implementation decisions.

How this skill works

When triggered, the skill traces the execution path to specific file:line locations, constructs a short class.method() text diagram showing the flow and where errors occur, and asks the user to verify the diagram before proceeding. It deliberately keeps the analysis minimal — just enough to guide test design and the next implementation step. After confirmation, it proceeds with implementation plans or tests.

When to use it

Investigating a bug where the failure point is unclear
Planning a new feature that touches multiple modules
Preparing a TDD cycle to ensure tests cover the right flow
Refactoring code that may change call paths
Debugging runtime errors and tracing exceptions to source

Best practices

Trace from the triggering event to the exact file:line handlers
Keep diagrams short (5–10 lines) and focused on relevant methods
Include relevant data fields in the diagram arrows when helpful
Ask for explicit user confirmation before implementing changes
Skip the protocol for trivial edits (typos, docs, formatting)

Example use cases

A failing API endpoint: trace request -> controller.method() [file:line] -> service.method() [file:line] -> error location
A feature that updates user state across services: map event -> handler -> repository calls with file:line references
A flaky test: find the code path exercised by the test and show the short call flow to verify assumptions
Refactor that touches shared utilities: diagram who calls util.method() and where behavior must be preserved

FAQ

How detailed should file:line references be?

Be specific: mention the exact file and approximate line number where the relevant logic runs. Precision reduces guesswork.

What counts as 'trivial' and can skip the protocol?

Typos, formatting, documentation updates, and single-line comment fixes are trivial and can skip this process.

What if I don't know the exact line?

Provide the closest identifiable line or function name and indicate it as approximate; still produce the short diagram and ask for confirmation.