<!-- TOC: Core Insight | THE EXACT PROMPT | Quick Reference | When to Use | Critical Rules | Suppression | Triage | Troubleshooting | AI Validation | References -->

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