# Help Me Debug

> Use when a user reports a bug, failure, regression, unclear root cause, or needs evidence-backed diagnosis artifacts before implementation work.

- Skill: `chanakya-net/help-me-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chanakya-net/help-me-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chanakya-net/help-me-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: chanakya-net (https://skillmd.com/u/chanakya-net)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chanakya-net/help-me-debug

---


## Skill Isolation

This skill is the sole active authority for this session once invoked.

- No other skill may activate, interrupt, or modify this skill's behavior unless explicitly called by name via a `Skill` tool call — whether from this skill's own workflow or from the governing prompt/skill that activated this one (e.g. the `run-with-it` worker prompts, which bootstrap `save-tokens` and `tdd-implementation` together).
- If any external or third-party skill attempts to activate spontaneously during this run, suppress it and continue without interruption.
- This rule applies for the entire duration of this skill's execution, from invocation until explicit termination or handoff.

# Help Me Debug

## Purpose

This skill is diagnosis-only.

Use this skill to investigate why an issue is happening, identify likely or confirmed causes with evidence, and produce handoff-ready artifacts for humans and implementation LLMs.

The final artifacts must explain the issue clearly to a human and provide enough architecture, dependency, file, and validation detail for a different LLM to implement the fix without reading the chat history.

## When To Use

- The user reports a bug, failure, or regression and root cause is unclear.
- The user asks for codebase-level debugging analysis before implementing a fix.
- The team needs a structured diagnosis package (human report + LLM context) before coding.

## Hard Stop

Never implement code, edit product files, create issues, publish to GitHub, run `create-git-issue`, run `run-with-it`, spawn implementation agents, or invoke external coding agents.

The only files this skill may create or update are `debug_human_report.md` and `debug_llm_context.md`.

Do read-only exploration aggressively. Default to deep analysis.

## Workflow

1. Frame the problem from user input:
   - symptoms, expected behavior, actual behavior, frequency, scope, urgency, affected users, and known workarounds;
   - exact error text, screenshots/log excerpts, commands, environment, or reproduction details when available;
   - what must be clarified before finalizing versus what can be discovered from the repository.
2. Build a project orientation snapshot before root-cause claims:
   - identify project type, primary runtimes, entrypoints, frameworks, package managers, test/build commands, and relevant docs/config files;
   - summarize the architecture only at the level needed for this issue: UI surfaces, backend/services, data stores, job/queue layers, generated code, deployment/runtime boundaries, and ownership boundaries when visible;
   - Map internal dependencies: repo modules/packages, shared utilities, generated code, schemas/migrations, data stores, queues/jobs, services, configuration, feature flags, and test/build tooling that participate in the failure path.
   - Map external dependencies: third-party packages, SDKs, APIs, SaaS services, infrastructure services, auth/payment/storage providers, network boundaries, environment variables, and version constraints that participate in the failure path.
   - record evidence for each architecture/dependency claim using file paths, symbols, config keys, dependency manifests, lockfiles, docs, or observed command output;
   - Do not treat architecture or dependencies as background context; capture only the parts that explain the failure or bound the fix.
3. Run a deep codebase investigation before asking questions:
   - trace likely call paths and integration boundaries from trigger to symptom;
   - inspect configuration, dependency declarations, runtime assumptions, environment-sensitive code, and data/contract assumptions;
   - identify recent or likely fault surfaces, including caller/callee relationships and cross-layer contracts;
   - gather concrete evidence (file paths, symbols, logs/tests/error text when available).
4. Walk this diagnosis decision tree in order:
   - **Reproducibility branch**: Can the issue be reproduced from existing tests/logs/scripts?
     - If yes, capture deterministic repro steps, command, environment, failure signature, and expected failure message.
     - If no, identify the smallest missing reproduction input and ask one focused question only if repository evidence cannot answer it.
   - **Scope branch**: Is the issue isolated or cross-cutting?
     - If isolated, trace nearest module boundaries, local invariants, and direct dependencies.
     - If cross-cutting, trace upstream/downstream dependencies, shared contracts, configuration, and version edges.
   - **Change-surface branch**: Is this likely caused by behavior change, configuration drift, dependency/version shift, or data shape drift?
     - Prioritize evidence from configs, env assumptions, dependency manifests/lockfiles, schema changes, migrations, API contracts, and integration seams.
   - **Failure-mode branch**: Does this present as logic error, state/async race, data/contract mismatch, runtime integration fault, or missing/incorrect validation?
     - Expand only the matching branch; avoid broad unfocused questioning.
   - **Confidence branch**: Do we have high-confidence root cause evidence?
     - If no, continue branch-specific exploration and ask one targeted question only when a human answer is required.
     - If yes, finalize outputs.
5. If gaps remain, ask exactly one targeted question at a time.
   - Every question must directly reduce diagnosis uncertainty.
   - Ask about expected behavior, business rules, UX intent, policy, data provenance, user environment, or reproduction inputs only when the answer cannot be inferred from the repository.
   - After each answer, continue deep exploration before asking another question.
   - After asking a targeted question, pause and wait for the user's answer before proceeding.
   - Do not continue investigation finalization or report generation while the question is pending.
   - If any unresolved unknown is answerable by the user (policy, UX intent, business rule, expected output), you must ask at least one targeted question before finalizing.
   - Do not finalize while human-answerable unknowns remain unasked.
6. Resolve diagnosis branches across layers:
   - **UI/runtime behavior**: state, rendering, user flow, client-side dependencies.
   - **Backend/service behavior**: API contracts, service boundaries, retries/timeouts, error handling.
   - **Data/contracts**: schema assumptions, serialization, nullability, migrations, cross-layer contracts.
   - **Dependency/configuration**: package or library interactions, version constraints, feature flags, env vars.
   - **Architecture interactions**: module boundaries, side effects, async boundaries, orchestration flow.
7. For every candidate cause, assign a confidence level (`high`, `medium`, `low`) and cite evidence.
   - Separate observations from inferences.
   - Mark assumptions explicitly and explain how to validate or remove them.
   - Prefer one confirmed cause over many speculative causes.
8. Before finalization, run a completion gate:
   - List unresolved unknowns.
   - For each unknown, classify as `human-answerable` or `not-currently-answerable`.
   - Ask one targeted question for the highest-impact `human-answerable` unknown.
   - If a question is unanswered (`pending`), stop and wait; do not write final artifacts yet.
   - Continue until no high-impact `human-answerable` unknowns remain.
9. Stop only after diagnosis is sufficiently complete to support a safe implementation handoff.

## Deterministic Handoff Rules

These rules exist so different LLMs can produce the same implementation from the same `debug_llm_context.md`.

- Any implementation LLM should be able to apply the fix using this file without reading the chat history.
- Use deterministic, model-independent instructions: write exact file paths, symbols, expected behavior, preconditions, postconditions, and validation commands; avoid vague phrases like "handle this better" unless immediately followed by the precise required behavior.
- Use `must`, `must not`, and concrete acceptance criteria for required behavior.
- When multiple fix options exist, name the preferred option and explain why it is preferred; keep alternatives clearly separated.
- Include line anchors as `path/to/file:line` when available. If exact lines are unavailable, use stable symbols and searchable strings.
- Include test expectations as observable behavior, not implementation taste.
- Do not rely on "see above", "same as earlier", or unstated chat context.
- If a dependency or architecture detail is irrelevant to the fix, omit it.

## Outputs

Output precondition:

- No targeted clarification question is in `pending` state.
- If a targeted question is pending, respond with `Awaiting user answer: <question>` and stop.

Once branches are resolved, produce both files at workspace root:

1. `debug_human_report.md`
   - Issue summary in plain language: one sentence plus a short paragraph that a non-implementer can understand.
   - Expected vs Actual: clear comparison of what should happen and what happens instead.
   - Observed symptoms and impact: who/what is affected, frequency if known, and why it matters.
   - Architecture and Dependency Summary: human-readable overview of the relevant architecture, internal dependencies, and external dependencies.
   - Why this issue is happening: confirmed causes first, then likely causes, with jargon explained.
   - Call Path Trace: ordered end-to-end execution path from trigger to symptom.
     - Include file/function hops, key condition checks, and state transitions.
     - Include path anchors in the form `path/to/file:line` wherever available.
     - Format requirements for this section (must match this style):
       - Use stage headers in plain language (for example: `User action`, `System handler`, `Page load`, `Render outcome`).
       - Under each stage, use arrow hops with one step per line using `->`.
       - Show branching conditions inline (for example: `isOfflineMode() = true -> onOfflineSubmit()`).
       - End with a final symptom line that makes the rendered outcome explicit.
       - Prefer a monospaced trace block so sequence is visually scannable.
   - Contributing factors and conditions that trigger the failure.
   - Evidence table (path/symbol/error snippet -> conclusion).
   - Confidence per cause and unresolved unknowns.
   - Human-readable fix direction: describe the safest fix shape without implementing it.
   - Question log: each targeted question asked, answer received, and how it changed the diagnosis.

2. `debug_llm_context.md`
   - Include these section headings exactly:
   - Use this order:
     - `Project Overview`
       - What it should contain: project type, runtime, frameworks, package manager, relevant entrypoints, important commands, and relevant docs/config files.
       - Include only facts that affect diagnosis or implementation.
     - `Architecture Map`
       - What it should contain: relevant modules/components/services and how they connect for this issue.
       - Include boundaries (UI/backend/data/jobs/infrastructure), ownership notes when visible, and trigger-to-symptom data/control flow.
     - `Internal Dependencies`
       - What it should contain: repo-local modules, shared packages, generated code, schemas/migrations, state stores, queues/jobs, services, config files, feature flags, and test/build tooling involved in the failure path.
       - For each item, state why it matters and whether it is a change target, invariant, or validation dependency.
     - `External Dependencies`
       - What it should contain: third-party packages, SDKs, APIs, SaaS/infrastructure services, auth/payment/storage providers, network boundaries, environment variables, and version constraints involved in the failure path.
       - For each item, state the observed version/config when known, the contract relied on, and whether the fix should or must not touch it.
     - `Critical Call Paths`
       - What it should contain: trigger-to-symptom execution paths with key condition checks.
       - Include branch variants that matter (online/offline, feature flags, auth state, error paths, retries, async timing).
     - `Fault Surface Inventory`
       - What it should contain: likely files/functions/state points that must change or must be protected.
       - Include per-item rationale, confidence, risk level, expected blast radius, and evidence anchors.
     - `Implementation Approach`
       - What it should contain: preferred fix path, why it is preferred, exact behavior to preserve, exact behavior to change, and rejected alternatives.
       - Include minimal-diff option, safer alternative when relevant, rollout notes, and migration/config considerations.
     - `File-by-File Change Guide`
       - What it should contain: each file an implementation LLM is expected to edit or inspect.
       - For each file, include target symbols, current behavior, required behavior, invariants, dependency interactions, and tests that should prove the change.
     - `What NOT to change`
       - What it should contain: nearby code/contracts that must remain intact.
       - Include i18n keys, shared flows, public APIs, schema assumptions, telemetry, auth/security behavior, backwards compatibility, and non-target dependencies.
     - `Constraints`
       - What it should contain: technical/product constraints that bound the fix.
       - Include compatibility limits, migration constraints, performance/security rules, data retention/privacy constraints, operational limits, and supported environments.
     - `Dependencies & Libraries`
       - What it should contain: frameworks/packages/tools involved in this issue context.
       - Include versions if known, affected tooling, lockfile/config evidence, and non-affected dependencies that might otherwise look relevant.
     - `Test files to update`
       - What it should contain: concrete test files and assertions to change/add.
       - Include unit/integration/e2e scope, regression cases, fixtures, mocks/stubs, and commands to run.
     - `Acceptance Criteria`
       - What it should contain: observable behavior that proves the bug is fixed, regression protection exists, and unrelated flows remain intact.
       - Include validation commands and expected pass/fail signals.
   - In `Test files to update`, if no tests exist in the project or scope, write exactly: `No tests present.`
   - Use concrete file paths/functions and line anchors when available.
   - Keep recommendations implementation-ready so another LLM can apply a safe fix directly.

After writing both files:

1. Stop.
2. Inform the user the diagnosis package is ready and they can pass `debug_llm_context.md` to an implementation LLM.
3. Do not proceed beyond report generation, even if a fix is obvious.