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:

Situation	Command	Speed
Pre-commit (staged files)	ubs --staged	<1s
Working tree changes	ubs --diff	<1s
Specific files	ubs src/file.ts src/other.ts	<1s
Full project	ubs .	~30s

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:

Severity	Action	Exit code
critical	Must fix before commit	non-zero
warning	Should fix, judgment call	non-zero with --fail-on-warning
info	Optional improvement	zero

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

Flag	Purpose
--format=json	Machine-parseable output
--format=sarif	SARIF for IDE integration
--ci	Stable timestamps, CI-friendly
--only=js,python	Restrict to specific languages
--exclude=rust	Skip specific languages
--category=resource-lifecycle	Focus on category packs
--fail-on-warning	Treat warnings as failures
--staged	Scan only git-staged files
--diff	Scan only modified files (working tree vs HEAD)
--comparison=baseline.json	Diff against a baseline
--html-report=report.html	Generate shareable HTML report
--suggest-ignore	Show directories to add to .ubsignore

---

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.