Using UBS for Code Review
Core Insight: UBS catches what compiles but crashes — null derefs, missing await, resource leaks, security holes. It has many false positives; triage is essential, not optional.
The Golden Rule
ubs <changed-files> before every commit.
Exit 0 = safe to proceed.
Exit 1 = triage findings.
Exit 2 = run `ubs doctor --fix`.
THE EXACT PROMPT — Fix-Verify Loop
1. Scan: Run UBS on changed files
ubs --staged # Staged files (<1s)
ubs --diff # Unstaged changes vs HEAD
ubs file.ts file2.py # Specific files
2. Triage each finding:
Real bug? → Fix root cause (not symptom)
False positive? → // ubs:ignore — [why it's safe]
3. Re-run until exit 0
ubs --staged
4. Commit when clean
Why This Workflow Works
--staged is fast — Scans only what you're committing- Fix root cause — Masking symptoms creates debt
- Exit 0 gate — Clean scan = confidence to commit
- Justification required — Every
ubs:ignore must explain why
Quick Reference
# Core workflow
ubs --staged # Staged files only (<1s)
ubs --diff # Working tree changes vs HEAD
ubs . # Full project scan
# Language-specific (--only=js excludes TS!)
ubs --only=go,rust src/ # Go and Rust only
ubs --only=ts,tsx frontend/ # TypeScript (js≠ts)
# Noise reduction
ubs --skip=11,12 . # Skip TODO/debug categories
ubs --profile=loose . # Skip minor nits
# Output formats (json=summary, jsonl=per-finding details)
ubs . --format=jsonl # Per-finding details
ubs . --format=sarif > results.sarif # IDE/GitHub integration
# PR review (new issues only)
ubs . --comparison=baseline.json --fail-on-warning
# Troubleshooting
ubs doctor # Check environment
ubs doctor --fix # Auto-fix issues
When to Use What
| You Want |
Command |
Why |
| Quick pre-commit |
ubs --staged |
Fast, only staged files |
| Strict gate |
--fail-on-warning |
Blocks on all findings |
| Skip noise |
--skip=11,12 |
TODO/debug categories |
| Language focus |
--only=go,py |
Target specific languages |
| PR review |
--comparison=baseline.json |
Shows NEW issues only |
| Security audit |
--category=security |
Focused security scan |
| Full report |
--html-report=out.html |
Shareable dashboard |
| Per-finding data |
--format=jsonl |
Detailed parsing (json=summary only) |
| Environment fix |
ubs doctor --fix |
First-line troubleshooting |
Critical Rules
| Rule |
Why |
Consequence |
| Exit 2 → doctor |
Scanner error |
Run ubs doctor --fix immediately |
| Every ignore needs why |
Audit trail |
// ubs:ignore — caller validates |
| Fix root cause |
Prevents debt |
Don't mask symptoms |
| Don't skip triage |
Real bugs hide |
Review every finding |
| JS/TS needs AST engine |
Semantic analysis |
ubs doctor --fix if degraded |
Suppression
// GOOD — explains why it's safe
eval(trustedConfig); // ubs:ignore — internal config, not user input
// BAD — no justification
eval(config); // ubs:ignore
Per-Language Comment Styles
| Language |
Suppression Format |
| JS/TS/Go/Rust/Java |
// ubs:ignore — reason |
| Python/Ruby/Shell |
# ubs:ignore — reason |
| SQL |
-- ubs:ignore — reason |
Rule: Every ubs:ignore MUST explain why the code is actually safe.
Is This Finding Real?
Finding → Code path executes? → No → FALSE POSITIVE (dead code)
→ Yes ↓
Guard clause exists? → Yes → FALSE POSITIVE (ubs:ignore)
→ No ↓
Validated elsewhere? → Yes → FALSE POSITIVE (cross-file)
→ No → REAL BUG, fix it
Triage by Severity
| Blocks Commit |
Blocks PR |
Discuss in PR |
| Null safety (1) |
Error swallowing (8) |
Debug code (11) |
| Security (2) |
Division by zero (6) |
TODO markers (12) |
| Missing await (3) |
Promise no catch (9) |
TypeScript any (13) |
| Resource leaks (4) |
Array mutation (10) |
Deep nesting (14) |
Category numbers map to --skip=N and --category=N flags.
Full breakdown: TRIAGE.md
Troubleshooting
| Problem |
Cause |
Fix |
| Exit code 2 |
Missing optional scanners |
ubs doctor --fix |
| JS/TS degraded |
AST engine missing |
ubs doctor --fix |
| Too many findings |
Legacy code |
Use --comparison for baseline |
| Too slow |
Full scan |
Use --staged or --only= |
| False positive storm |
Test fixtures |
Add to .ubsignore |
AI Code Validation
AI-generated code is prone to:
| Pattern |
Bug |
Category |
user.profile.name |
No null check |
1 (Null safety) |
fetch(url) |
Missing await |
3 (Async) |
open(file) |
Never closed |
4 (Resource) |
catch (e) {} |
Swallowed error |
8 (Error handling) |
# After AI writes code:
ubs [file] --fail-on-warning
References
| Need |
Document |
| Prioritize findings |
TRIAGE.md |
| Identify false positives |
FALSE-POSITIVES.md |
| CI/CD, hooks, workflows |
WORKFLOWS.md |
gabrielmoreira