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

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.
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.
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).
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.
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.
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.
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.
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.
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:

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.
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:

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