Bug Predict FAQ

What does bug predict do?

It scans your codebase for code patterns and complexity signals that historically cause production incidents, then returns a risk report grouped by severity with file paths and line numbers.

When should I use it?

Use bug predict before merging a large PR, during code review to focus attention on real risks, or as a periodic health check on high-churn modules. If you need broader vulnerability scanning rather than pattern-based prediction, consider a security audit instead.

How do I run it?

The fastest way is to point it at a path:

/bug-predict src/

You can also use natural language — for example, "predict bugs in src/" or "find risky code in the auth package". If you don't specify a path, the skill walks you through scoping before it runs. See the task guide for the full walkthrough.

What patterns does it detect?

It detects three pattern types:

It also weighs cyclomatic complexity, change frequency, and code smells when calculating the overall risk score.

Does it flag false positives?

It automatically suppresses known-safe patterns — for example, eval() inside test fixture strings, JavaScript regex.exec() calls, and broad exceptions marked with # INTENTIONAL: or # noqa: BLE001. Keywords like fallback, graceful, and intentional in surrounding comments are also treated as intentional and filtered out.

How is the risk score calculated?

The score runs from 0 to 100 and reflects a combination of pattern matches, their severity, and contextual signals like file complexity and change frequency. A score is shown at the top of every report alongside the total file and finding counts.

What are the three subagents doing under the hood?

BugPredictionWorkflow coordinates three specialized subagents — pattern-scanner, risk-correlator, and prevention-advisor — and synthesizes their findings into a single report with a summary, a bugs section, and prioritized prevention suggestions.

How do I generate a report programmatically?

Call format_bug_predict_report(result, input_data) from workflows.bug_predict_report. It takes the raw result dict and the original input data, and returns a formatted string you can print or write to a file. For a standalone CLI run, call main() from the same module.

Can I customize the workflow's system prompt?

Yes. Pass a system_prompt_suffix string when constructing BugPredictionWorkflow:

from workflows.bug_predict import BugPredictionWorkflow

workflow = BugPredictionWorkflow(system_prompt_suffix="Focus only on authentication code.")
result = workflow.execute(path="src/auth/")

How do I debug a failed scan?

Run the related tests first with pytest -k "bug-predict" -v. If the tests pass but your scan still fails, add a logger.debug statement at the suspected failure point and re-run with logging enabled. The source files to inspect are src/attune/workflows/bug_predict.py and the bug_predict_report module in the same directory.

Tags: bugs, prediction, scanning, race-condition

Unresolved references

Auto-generated by attune-author fact-check. Review and either fix the source code, fix this doc, or add an override.