ubs - SKILL.md Agent Skill

name: ubs user-invocable: false skill_api_version: 1 hexagonal_role: supporting metadata: tier: execution description: "Use when reviewing code with UBS for bugs, security issues, AI-generated quality, or pre-commit checks." practices:

pragmatic-programmer

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