Ubs Bug Scan

UBS Bug Scan

Prerequisites

# Install UBS
brew install dicklesworthstone/tap/ubs

# Verify
ubs --version

If command -v ubs fails, emit the install one-liner above and stop.

Workflow

1. Determine Scope

Pick the narrowest scope that covers the work:

Speed tip: Always scope to changed files. Full-project scans are for baselines only.

2. Run Scan

# Agent-parseable output (JSON)
ubs --staged --format=json --ci

# Token-efficient output (text, truncated)
ubs --staged --ci 2>&1 | tail -40

# Language-scoped
ubs --staged --only=js,python --ci

3. Parse Output

Findings have three severities:

JSON output structure:

{
  "summary": { "critical": 0, "warning": 1, "info": 3 },
  "findings": [
    {
      "file": "src/foo.ts",
      "line": 42,
      "severity": "warning",
      "category": "resource-lifecycle",
      "message": "File handle opened but never closed"
    }
  ]
}

4. Fix Findings

For each finding:

1. Navigate to file:line
2. Verify it's not a false positive (check surrounding context)
3. Fix the root cause (not just the symptom)
4. Re-run ubs <file> to confirm the fix
5. Repeat until exit 0

5. Commit Gate

# Golden rule: run before every commit
ubs --staged --ci
# Exit 0 = safe to commit
# Exit >0 = fix findings first

Useful Flags

Anti-Patterns

• Running ubs . on every commit (slow, noisy)
• Ignoring critical findings with UBS_SKIP=1
• Fixing symptoms instead of root causes
• Not re-running after fixes to confirm resolution

Reference

See references/ubs-quickref.md for condensed command reference and severity guide.