astroville/sprout / .claude/skills/debugging-investigation
debugging-investigation
VerifiedDebugging guidance and structured report template for thorough bug investigation, evidence gathering, and root cause documentation.
Core approach
- Reproduce the problem if feasible.
- Gather evidence before drawing conclusions.
- Separate observations, hypotheses, and confirmed root causes.
- Narrow the failure surface methodically.
- Prefer the smallest fix that addresses the actual cause.
Practical guidance
- Ground before you guess. Before proposing a diagnosis, fix, or design, enumerate the load-bearing claims it depends on (what specific code does, what payloads contain, where errors originate, how working siblings of the same shape behave). Mark each
read(you've inspected the actual source in this session) orassumed. Read the assumed ones — or downgrade the proposal to "still investigating" — before writing it down. Output the claim list visibly in your summary. A proposal that departs structurally from working in-tree siblings of the same shape (plugin, provider, integration, form, migration, adapter, command) treats the deviation as the first hypothesis to disprove, not a feature. - Look at logs, tests, stack traces, configuration, recent changes, and runtime assumptions together.
- Pay attention to environment differences, race conditions, stale state, and boundary failures.
- When reproduction is incomplete, be explicit about what is inferred.
- Trace the complete end-to-end code flow — from user interaction or trigger through every layer to where the bug manifests. Do not stop at the immediate method.
- Read every file in the flow. Do not skim or assume.
- Look for secondary defects in the same flow — other bugs that aren't the reported issue but would cause problems.
- Check all code paths that could trigger the issue (different input formats, config modes, error handling branches).
Investigation report template
Use this template when documenting investigation findings. All sections are required unless explicitly not applicable. Add additional sections for information that doesn't fit the template.
## Summary
### Categorization
| Attribute | Assessment |
|-----------|------------|
| **Criticality** | [critical/high/medium/low] — [short explanation] |
| **Ease of Fix** | [easy/moderate/hard] — [short explanation] |
| **Caused by our codebase?** | [Yes/No] — [short explanation] |
| **Needs more research?** | [Yes/No] — [short explanation] |
### Background
[Simple text description of what this bug is, its complexity, criticality, and estimated fix effort]
### Analysis
[Simple description of why it is occurring]
### Root Cause
[Simple description of the root cause]
### Source
[Simple description of what code is involved]
### Fix Direction
[Simple description of what is needed to fix the issue — high level only, no implementation details]
---
## Problem Statement
[Full research details on the issue and cause. Include reproduction steps if available. Reference specific error messages, logs, stack traces.]
## Environment Details
[List any relevant setup, config, or environmental details or factors. If not applicable, say so.]
---
## Root Cause Analysis
[Full root cause analysis with evidence. Cite specific code, conditions, and data that prove the root cause. Separate confirmed findings from hypotheses.]
---
## Code Flow (End to End)
[Numbered list of the complete code flow from the entry point (user interaction, API call, job trigger) through every layer to where the bug manifests. Include file paths and line numbers at each step.]
1. `path/to/file.ext:NN` — [what happens at this step]
2. `path/to/file.ext:NN` — [next step in the flow]
3. ...
---
## Key Files
[Group by logical area. Each area gets a table.]
### [Area name, e.g., "API Layer" or "Storage Service"]
| File | Lines | Relevance |
|------|-------|-----------|
| `path/to/file.ext` | NN–MM | [description of relevance] |
### [Next area]
| File | Lines | Relevance |
|------|-------|-----------|
| `path/to/file.ext` | NN–MM | [description of relevance] |
---
## Secondary Defects
[Other bugs or concerns discovered during investigation that aren't the reported issue but exist in the same code flow. If none found, state "None identified."]
---
## Notes
[Any additional observations, context, or concerns not covered above]
---
## Recap
[2-3 sentence recap of the investigation: what the bug is, what causes it, and how severe it is]
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |