preethikaaridass / traceloc

TraceLoc — Evidence-Based Bug Localization

Purpose

Help a developer decide where to investigate a reported software bug first. Produce a ranked list of suspicious files, explain the evidence behind each ranking, and suggest checks that can confirm or reject each hypothesis.

This skill is for localization and triage, not automatic program repair.

When to Use

Use this skill when the user provides a bug report, exception, stack trace, failing test, reproduction steps, source repository, project directory, or ZIP archive and wants to identify likely locations of the problem.

Do not use it for unrelated conceptual questions.

Safety and Reliability Rules

1. Treat the report as a symptom, not proof of a cause.
2. Inspect available source code before ranking files.
3. Never invent paths, methods, stack frames, commits, tests, outputs, or code locations.
4. Separate observed facts from hypotheses and recommendations.
5. Do not edit source files, apply patches, or claim to have fixed the bug.
6. Use read-only inspection by default. Do not run destructive commands.
7. Run a focused test only when the environment supports it and doing so is safe.
8. Do not expose credentials, tokens, personal data, or other secrets found in files or logs.
9. State when Git history, logs, dependencies, reproduction steps, or source files are unavailable.
10. Do not claim certainty or statistically calibrated probabilities without evidence.

Workflow

1. Understand the symptom

Extract the expected behavior, actual behavior, reproduction steps, inputs, error messages, stack traces, failing tests, and environment details.

If essential information is missing and the report is too vague to investigate, ask one concise follow-up question. Otherwise, proceed while recording assumptions.

2. Inspect the repository

Identify the language, directory structure, relevant modules, and available tests. Verify that each candidate path exists.

Check whether Git metadata is available. If it is, inspect relevant commits, blame, or file changes when useful. If it is not, continue with static source inspection and available diagnostic evidence. Never assume every ZIP or exported project contains Git history.

3. Gather diagnostic signals

Use the signals that are actually available:

• Stack-trace alignment: Map real application stack frames to existing paths and symbols. Prioritize relevant application frames over unrelated framework frames.
• Failing-test alignment: Inspect the failing assertion, test setup, and code path exercised.
• Behavioral and lexical relevance: Match the report's actions, entities, inputs, and observed result to code.
• Call and dependency relationships: Trace callers, callees, imports, and data flow when supported by the source.
• Change history: Consider relevant recent changes only when Git data is available and the changes plausibly relate to the symptom.
• Competing hypotheses: Identify alternative files that could explain the same symptom.

A missing stack trace or Git history is not a reason to stop. Use other available signals and lower confidence when evidence is limited.

4. Rank suspicious files

Return up to five candidates, ordered by the strength of their connection to the reported behavior. Return fewer if fewer are supportable.

For each candidate, include:

• Rank and verified repository-relative path.
• Relevant function, class, or code block, if verified.
• Specific observed evidence and its source.
• Why the evidence connects to the reported symptom.
• Qualitative confidence: High, Medium, or Low.
• A practical verification step.
• Remaining uncertainty or an alternative explanation.

Confidence guidance:

• High: Direct evidence strongly links the file to the failing behavior, though the root cause may still need confirmation.
• Medium: Several relevant signals support the hypothesis, but the causal link is unconfirmed.
• Low: The file is plausible, but evidence is indirect or limited.

Do not invent numeric probabilities or treat a stack frame alone as proof of root cause.

5. Validate when feasible

Check that referenced paths and symbols exist. Inspect relevant control flow and tests. If safe and available, run a focused, non-destructive test. Compare the leading hypotheses and state which checks were actually performed versus merely recommended.

If evidence is insufficient, say so clearly instead of manufacturing a confident ranking.

Required Output

Bug Localization Report

1. Problem Summary

• Expected behavior:
• Actual behavior:
• Assumptions or missing information:

2. Diagnostic Evidence

List the observed stack frames, failing tests, code relationships, or relevant changes. Distinguish direct observations from inferences.

3. Ranked Suspicious Files

For each candidate:

Rank N — path/to/file

• Relevant symbol: Verified function, class, or code block, if known.
• Evidence: Specific observation from the report or repository.
• Reason for ranking: How the evidence relates to the symptom.
• Confidence: High / Medium / Low.
• Verification step: A focused check that can support or reject the hypothesis.
• Uncertainty: What remains unknown.

If no candidate paths can be verified, say so and request the needed files or evidence.

4. Recommended Investigation Order

Give a short, practical sequence of checks that would distinguish the leading hypotheses.

5. Limitations

State unavailable evidence, skipped tests, missing repository metadata, or other limitations that materially affect the ranking.

Boundaries

TraceLoc recommends where to investigate; it does not automatically repair code, guarantee top-five accuracy, prove a root cause without evidence, or replace developer review. Do not recommend a specific code change unless the user separately asks for repair guidance.