issue-localization
Skill177 starsChanged 7 days agoApache-2.0View on GitHub
Search existing evidence and working code before tracing the first wrong state and testing root-cause hypotheses. Use for problem analysis, fault localization, unexpected behavior, test failures, and cross-module failures.
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- agent-evaluationSkill
- algorithm-developmentSkill
- buildSkill
- change-reviewSkill
- container-buildSkill
- engineering-solution-designSkill
- interface-migrationSkill
- lintSkill
- long-horizon-developmentSkill
- model-artifact-integrationSkill
- multi-repo-devSkill
- performance-optimizationSkill
- repository-agent-setupSkill
- simulation-regressionSkill
- test-impact-analysisSkill
- unified-core-runtimeSkill
- vendorSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 13 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Use for errors, unexpected behavior, and failures with an unknown cause.
- Distinctive: line 13
Read relevant source, tests, existing results, and recent related changes.
- Distinctive: line 24
Read the relevant errors, stack traces, and existing logs in full, then inspect current implementation, call relationships, configuration …
- Distinctive: line 28
Search only relevant history, known issues, and reference implementations.
- Distinctive: line 31
Prefer existing reproduction conditions.
- Distinctive: line 65
Stop expanding the investigation when evidence is sufficient.
- Distinctive: line 70
If the cause cannot be confirmed, report the narrowed scope and next check, and explicitly state that localization is incomplete.
- Distinctive: line 79
Use a minimal reproduction or targeted test to demonstrate the original problem, then implement the smallest fix and run regression …
- Distinctive: line 82
Do not hide unknown causes by widening tolerances, silently falling back, extending timeouts, or adding retries.
- Distinctive: line 84
If the contract requires fault tolerance, still explain the failure mechanism, boundary, and how failures remain visible.
- Distinctive: line 90
If repeated fixes are ineffective, stop and recheck assumptions and boundaries.
- Distinctive: line 104
If raw packages are missing, tools are unavailable, or timing is incomparable, state how this affects the conclusion and choose safe …
- Distinctive: line 107
If evidence remains insufficient, report the gap and stop inferring.
- Distinctive: line 108
Do not automatically restart shared services, clear data, update dependencies, or replace the environment.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Issue Localization: Search Before Tracing
Scope and prerequisites
Use for errors, unexpected behavior, and failures with an unknown cause. The
goal is to narrow the fault and establish causal evidence, not to guess a fix.
Hand off performance-only issues to performance-optimization.
Read relevant source, tests, existing results, and recent related changes;
preserve the current worktree.
See the skill index for domain knowledge and tool entry
points. Do not blindly scan the entire repository or preload every module.
Workflow
1. Describe the symptom and inspect existing evidence first
Clarify expected and actual behavior, trigger conditions, affected versions, first anomaly time or cycle, and inputs and outputs. Read the relevant errors, stack traces, and existing logs in full, then inspect current implementation, call relationships, configuration switches, similar tests, and working paths. Do not ask again for information already available in context. Search only relevant history, known issues, and reference implementations; a search hit is not root-cause evidence.
Prefer existing reproduction conditions. If the issue cannot be reproduced reliably, preserve known events and identify missing evidence instead of guessing a fix. Any new collection must distinguish specific hypotheses and avoid sensitive data or unbounded logs.
2. Narrow the investigation to the first incorrect boundary
Trace inputs, state transitions, and call paths backward from the symptom, comparing normal and failing examples layer by layer. Find the earliest provable anomalous input, configuration, timing, state, or output. Distinguish where an error is observed from where it is introduced; do not patch only the final consumer that reports the error. In multi-component systems, inspect only relevant boundaries and add minimal instrumentation if needed; do not instrument everything.
For autonomous-driving issues, use evidence to check coordinates and units, event time and receipt time, input freshness, reset, configuration, upstream outputs, and downstream interpretation. For logs across clock domains, confirm synchronization and offsets; do not infer causality only from log print order. For planning anomalies, distinguish input and decision boundaries, optimization solving, trajectory stitching, and control response. Explore only relevant areas; do not require checking every failure category.
3. Form and test necessary hypotheses
Separate confirmed facts, hypotheses to test, and eliminated causes. For each candidate cause, state supporting evidence, falsification conditions, and the smallest discriminating check. Prioritize low-cost hypotheses that can narrow the scope most; the number depends on uncertainty, not a mechanical requirement to list three. Change one main variable per experiment when possible; predict the outcome before running it.
Stop expanding the investigation when evidence is sufficient. Update hypotheses when an experiment fails; do not stack patches or repeat operations that add no information. Correlation, temporal proximity, or a parameter change that “seems to help” does not by itself prove a root cause. If the cause cannot be confirmed, report the narrowed scope and next check, and explicitly state that localization is incomplete.
4. Fix the root cause and prevent regression
For analysis-only tasks, stop at the root cause and evidence boundary; modify implementation only when a fix is authorized. State the chain “trigger condition → first incorrect input/state → propagation path → visible symptom.” Use a minimal reproduction or targeted test to demonstrate the original problem, then implement the smallest fix and run regression coverage matching the impact. Do not hide unknown causes by widening tolerances, silently falling back, extending timeouts, or adding retries. If the contract requires fault tolerance, still explain the failure mechanism, boundary, and how failures remain visible.
For scenario behavior, hand off to simulation-regression; do not
automatically launch full-stack replay for a local defect already covered by
evidence.
If repeated fixes are ineffective, stop and recheck assumptions and
boundaries. Ask the user before architectural redesign or scope expansion.
Deliverables and acceptance
Report the symptom, reproduction status, first-failure boundary, key source and runtime evidence, eliminated causes, causal chain, fix or next check, and residual risks. Distinguish “reproduced,” “scope narrowed,” “root cause confirmed,” and “fixed and verified.” A code change or successful test-process exit does not prove that the original symptom is resolved.
Failure handling
If raw packages are missing, tools are unavailable, or timing is incomparable, state how this affects the conclusion and choose safe alternative evidence that tests the same hypothesis. If evidence remains insufficient, report the gap and stop inferring. Do not automatically restart shared services, clear data, update dependencies, or replace the environment.
Basis
Retain the first-failure-layer and causal-chain methods from context. Adapt evidence gathering, comparison with working examples, and single-hypothesis experiments from Superpowers systematic-debugging; do not copy its fixed retry counts or requirement to read everything.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

