Skip to content
Sheriff

Best Practices

Workflow Best Practices

Section titled “Workflow Best Practices”

Complete Full Passes Before Rescanning

Section titled “Complete Full Passes Before Rescanning”

Running a new static analysis scan mid-fix generates new fingerprints and resets your progress.

Recommended workflow:

  1. Run static analysis once
  2. Load SARIF into Sheriff
  3. Fix all issues (or all issues you plan to fix)
  4. Rescan to verify fixes and catch new issues
  5. Repeat if needed

Fix All Issues in a File Before Moving On

Section titled “Fix All Issues in a File Before Moving On”

Sheriff groups issues by file for a reason. Jumping between files wastes context and increases the chance of missing issues.

# Good: Complete one file
next → 3 issues in Service.java
[fix all 3]
done fps=[...] → mark all 3


# Bad: Partial fixes
next → 3 issues in Service.java
[fix 1]
done fps=[1] → mark 1
next → returns remaining 2 in Service.java (wastes a tool call)

Use Scope Filtering Strategically

Section titled “Use Scope Filtering Strategically”

Filter by rule type for batch efficiency:

// Fix all unused imports first (mechanical, fast)
{"action": "next", "scope": {"rule": "unused*"}}


// Then tackle complex issues
{"action": "next", "scope": {"rule": "DataFlowIssue"}}

Filter by severity for priority:

// Critical bugs first
{"action": "next", "scope": {"severity": "High"}}

Finding Issues After Edits

Section titled “Finding Issues After Edits”

Match by Snippet, Not Line Number

Section titled “Match by Snippet, Not Line Number”

After editing code, line numbers shift. Use the snip field to locate issues:

{
  "loc": "45:12",  // May be wrong after edits
  "snip": "if (value != null) {"  // Search for this
}

Agent approach:

  1. Note the snip content
  2. Search the file for that snippet
  3. The issue is at that location (regardless of line number)

Work Top-to-Bottom

Section titled “Work Top-to-Bottom”

When fixing multiple issues in a file, work from top to bottom. This minimizes line number drift for remaining issues.

Handling False Positives

Section titled “Handling False Positives”

Use skip Status

Section titled “Use skip Status”

Don’t leave false positives unmarked—they’ll keep appearing:

{"action": "done", "fps": ["fp12345678901234"], "status": "skip"}

Document Skip Reasons

Section titled “Document Skip Reasons”

When an agent skips issues, it should explain why:

“Marking as false positive: The static analyzer doesn’t see that validateInput() guarantees non-null here.”

Batch Size Recommendations

Section titled “Batch Size Recommendations”

Adjust the limit parameter based on issue complexity:

Issue TypeRecommended LimitReason
Unused imports25+ (default)Mechanical, fast
Constant checks10Need context
Null pointer issues3-5Require careful analysis
Security issues1-3Need thorough review
// Quick mechanical fixes
{"action": "next", "scope": {"rule": "unused"}, "limit": 20}


// Complex analysis needed
{"action": "next", "scope": {"rule": "SQL_INJECTION"}, "limit": 2}

Using Summary Effectively

Section titled “Using Summary Effectively”

Plan Before Starting

Section titled “Plan Before Starting”
{"action": "summary"}

Use the breakdown to:

  • Identify quick wins (high count, simple fixes)
  • Prioritize critical issues (high severity)
  • Estimate effort

Report Progress to Users

Section titled “Report Progress to Users”
{"action": "progress"}

“We’ve fixed 85 of 136 issues (63%). 12 null pointer issues and 39 formatting issues remain.”

Session Management

Section titled “Session Management”

State Persists Automatically

Section titled “State Persists Automatically”

Sheriff stores state in .sheriff/ directory. No need to save manually.

State survives:

  • Context compaction
  • Session restart
  • Agent switches

Clear State When Needed

Section titled “Clear State When Needed”

If you need to start fresh, delete the .sheriff/ directory:

Terminal window
rm -rf .sheriff/

Then reload the SARIF file.