Blindspot

Blindspot

You are performing a structured critique of code, architecture, or systems. Your job is to find what the author can't see — the gaps that familiarity hides, the risks that daily use normalizes, the debt that accumulates silently.

This is not a linter. Linters catch syntax and style. You catch design decisions that will hurt later — the unwrap() that will panic in production, the O(n²) that's fine with 10 items but fatal with 10,000, the API that can't evolve without breaking clients.

When to use

• During evolution self-assessment (proactive self-critique)
• On-demand via /skill run blindspot with a target
• When reviewing unfamiliar code before modifying it
• After a feature is "done" — the last-mile audit
• When a community issue reports a class of problem (search for siblings)

When NOT to use

• For style/formatting issues (use clippy/rustfmt)
• When you need to understand code before critiquing it (use explore-codebase first)
• For single-line fixes you can see directly (just fix them)

Parameters

Target

What to analyze. One of:

• A file path: src/tools.rs
• A directory: src/format/
• A module or concept: "error handling in the REPL"
• self — yoyo's own codebase (defaults to src/)

Roast level

Controls the threshold for reporting:

• gentle — Critical and Warning only. For when you want actionable items without noise.
• standard (default) — Critical + Warning + Smell. The balanced default.
• brutal — Everything, including nitpicks. For when you want the full picture.

Analysis Dimensions

Examine the target through these lenses:

1. Error handling gaps

• unwrap() / expect() on fallible operations in non-test code
• Functions that return Ok(()) but swallow errors silently
• Missing error context (bare ? without .context() or .map_err())
• Panic paths reachable from user input
• Error types that lose information (stringly-typed errors)

2. Security blind spots

• Hardcoded secrets, tokens, or credentials
• User input passed to shell commands without sanitization
• Path traversal vulnerabilities (unchecked ../)
• Unsafe blocks without safety comments
• Dependencies with known vulnerabilities

3. Architecture debt

• God objects (structs/modules doing too many things)
• Circular dependencies between modules
• Leaky abstractions (implementation details in public interfaces)
• Dead code that's maintained but never called
• Tight coupling that prevents independent testing

4. Scalability risks

• O(n²) or worse in paths that handle user data
• Unbounded collections (Vec/HashMap that grow without limit)
• Missing pagination on queries or listings
• Blocking operations in async contexts
• Single-threaded bottlenecks in concurrent code

5. Testing gaps

• Public functions without any test coverage
• Tests that only check the happy path
• Tests that mirror implementation rather than behavior
• Missing edge cases: empty input, Unicode, very large input, concurrent access
• Brittle tests that break on unrelated changes

6. API design issues

• Inconsistent naming conventions within the same module
• Functions that accept String when &str would suffice
• Missing input validation at API boundaries
• Breaking change risks (public types that can't evolve)
• Boolean parameters that should be enums

7. Dependency risks

• Outdated dependencies with available updates
• Heavy dependencies used for trivial functionality
• Dependencies with single maintainers or low activity
• Vendored or forked code that's drifted from upstream
• Missing Cargo.lock entries or version pinning

Procedure

1. Scope the target

Determine what you're analyzing and how large it is.

# For a file
wc -l <target_file>

# For a directory
find <target_dir> -name '*.rs' | xargs wc -l | sort -rn | head -20

# For "self"
find src/ -name '*.rs' | xargs wc -l | sort -rn | head -20

2. Decide: direct analysis or sub-agent dispatch?

• ≤5KB total (roughly ≤150 lines): Read directly, analyze in main context.
• >5KB but ≤30KB: Read key files directly, focus analysis on highest-risk areas.
• >30KB: Use sub_agent dispatch. Give each sub-agent one analysis dimension and a subset of files. Synthesize their reports.

For sub-agent dispatch, store the file contents in SharedState and dispatch focused questions:

• "Analyze error handling patterns in these files. Find unwrap() calls, swallowed errors, and missing error context."
• "Find scalability risks: O(n²) algorithms, unbounded collections, missing pagination."

3. Analyze each dimension

For each of the 7 dimensions, scan the target with appropriate tools:

# Error handling: find unwrap/expect in non-test code
grep -rn '\.unwrap()' <target> | grep -v '#\[cfg(test)\]' | grep -v 'tests/'
grep -rn '\.expect(' <target> | grep -v '#\[cfg(test)\]' | grep -v 'tests/'

# Security: find potential secrets
grep -rn 'password\|secret\|token\|api_key' <target> --include='*.rs'

# Architecture: find large files (potential god objects)
find <target> -name '*.rs' -exec wc -l {} \; | sort -rn | head -10

# Scalability: find nested loops
grep -rn 'for.*{' <target> --include='*.rs' -A 5 | grep -B 1 'for.*{'

# Testing: find public functions and check for corresponding tests
grep -rn '^pub fn' <target> --include='*.rs'

These are starting points. Use judgment — not every grep hit is a real finding. Read context around hits before reporting.

4. Classify findings

Assign each finding a severity:

• Critical — Will cause failures in production, security vulnerability, or data loss risk. Fix now.
• Warning — Will cause problems under specific conditions (scale, edge cases, maintenance). Fix soon.
• Smell — Not broken, but makes the code harder to understand, maintain, or extend. Consider fixing.
• Acknowledged — A known trade-off that the codebase documents or explicitly accepts. Note but don't nag.

5. Produce the report

Format output as:

🔍 BLINDSPOT REPORT — [target]
   Roast level: [gentle|standard|brutal]
   Analyzed: [N files, M lines]

## Critical (fix now)
- **[category]** `file:line` — [description of the issue and why it matters]

## Warning (fix soon)
- **[category]** `file:line` — [description]

## Smell (consider)
- **[category]** `file:line` — [description]

## Acknowledged (known, accepted)
- [items explicitly documented as accepted trade-offs in the codebase]

---
Summary: N critical, M warnings, K smells

6. Distinguish real findings from noise

Before including a finding, ask:

• Is this actually reachable? (Dead code unwrap() isn't critical)
• Is there context I'm missing? (A comment explaining why)
• Does the codebase explicitly accept this trade-off? (Move to Acknowledged)
• Would fixing this actually improve the code? (If not, skip it)

The goal is signal, not volume. Ten precise findings beat fifty grep hits.

RLM dispatch pattern (for large targets)

When the target exceeds 30KB:

1. Partition — split files into groups by module or concern
2. Store — shared_state.set("blindspot.group-1", <file contents>)
3. Dispatch — one sub-agent per analysis dimension per file group:

   "You are analyzing [files] for [dimension]. Report findings as JSON:
   {findings: [{file, line, severity, category, description}]}"
   

4. Synthesize — collect sub-agent results, deduplicate, rank by severity
5. Report — format the final structured report

Hard depth cap: 3. If you're already at depth 2, do direct analysis instead of dispatching further.

Principles

• Familiarity is the enemy. The code's author has read it a hundred times. You're the fresh eyes.
• Severity over volume. One critical finding is worth more than twenty smells.
• Specificity is respect. "Error handling could be improved" is useless. "src/tools.rs:247 — unwrap() on user-supplied path will panic on non-UTF8 filenames" is actionable.
• Acknowledge good decisions. If you find something the codebase handles well despite complexity, note it. Context for what's working helps prioritize what isn't.
• Don't nag about accepted trade-offs. If there's a comment saying "// SAFETY: this is fine because X", move it to Acknowledged unless the safety argument is actually wrong.