br4zz4:investigate

Diagnose root causes of bugs before implementing minimal tested fixes.

Updated May 25, 2025
One-click install
npx skills add https://github.com/oporpino/commons --skill br4zz4-investigate-oporpino
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: br4zz4:investigate
Source: https://github.com/oporpino/commons/tree/main/ai/shared/skills/br4zz4%3Ainvestigate
Command: npx skills add https://github.com/oporpino/commons --skill br4zz4-investigate-oporpino

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? It prevents quick patches and guesswork by enforcing a root-cause-first debugging workflow, so bugs are fixed at their source instead of being masked by superficial changes. ## Core Features & Use Cases - Structured investigation phases: Read errors and stack traces, trace data flow, check recent git changes, and gather evidence across multi-component systems before proposing any fix. - Spec and test-driven fixing: Write and commit a spec for approval, create a failing test first, then implement the smallest correct change and commit test plus fix together. - Documentation of learnings: Record the root cause in project learning files and update business rules so the same class of bug is prevented in the future. - Use Case: A production bug appears in a multi-service system. The skill guides you to instrument each component boundary, query production data read-only in a sandboxed console, identify the true origin of the bad value, and ship a minimal tested fix with a linked Asana subtask. ## Quick Start Ask the assistant to investigate and fix a reported bug using the investigate workflow, starting from the error message and recent changes.

Frequently Asked Questions about br4zz4:investigate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I investigate a bug before fixing it?▼

Start by reading error messages and stack traces completely, reproduce the bug consistently, and check recent changes with git log and git diff. Trace the data flow backward to the origin of the bad value before proposing any fix.

How to find root cause in a multi-component system?▼

Add diagnostic instrumentation at each component boundary, logging what data enters and exits each layer. Run the system once to gather evidence showing where the failure occurs, then analyze and fix at the source rather than the symptom.

Can I query production data safely during debugging?▼

Yes, use the sandbox-enabled console command for read-only production queries where no writes are persisted. Never run save, update, destroy, delete, or create methods, and ask the user before using any unsafe write-capable console.

Why should I write a failing test before the fix?▼

A failing test proves the bug exists and verifies the fix actually resolves it. The test must fail before the fix is implemented, then pass after, and both are committed together.

What should I do when multiple fix attempts fail?▼

After three or more failed hypotheses, stop and question the architecture instead of stacking more fixes. Repeated failures usually indicate a structural issue that needs discussion rather than another patch.