---
name: scorpio-roomba
description: Systematically explore a codebase to find bugs, code quality issues, and improvement opportunities. Produces a prioritized report with findings that route into existing development pipelines. Use when you want to proactively improve a codebase without a specific task in mind.
---

# Roomba

A proactive codebase health scan that systematically explores code, traces execution flows, and identifies bugs, quality issues, and improvement opportunities — all with "fresh eyes." Unlike reactive skills that respond to specific requests, Roomba goes looking for trouble.

## Prerequisites

- A **Project Context document** from **scorpio-project-map**. If one doesn't exist or is stale, run scorpio-project-map first.
- The project should be in a buildable/runnable state (Roomba needs to understand what "working" looks like)

## Roomba Phases

```
Phase 1: Orient       → Consume project context, plan exploration route
Phase 2: Explore      → Systematically walk through code by module
Phase 3: Analyze      → Deep investigation with "fresh eyes"
Phase 4: Report       → Structured findings with impact/effort ratings
Phase 5: Route        → Map findings to downstream skill pipelines
```

## Phase 1: Orient

Consume the Project Context document and plan the exploration.

### Read Project Context

Read `docs/PROJECT-CONTEXT.md` (or wherever scorpio-project-map placed it). Understand:
- Project structure and module layout
- Tech stack and frameworks in use
- Architecture patterns and conventions
- Known constraints and project maturity

### Plan Exploration Route

Based on the project context, create an exploration plan that covers modules systematically — not randomly:

```markdown
## Exploration Plan

### Priority Order (high-risk areas first)
1. **[Auth module]** — Security-critical, high impact if buggy
2. **[Data layer]** — Data integrity, performance implications
3. **[API routes]** — External-facing, input validation surface
4. **[Core business logic]** — Feature correctness
5. **[UI components]** — User-facing behavior
6. **[Utilities/helpers]** — Shared code, wide blast radius if broken
7. **[Configuration/infra]** — Build, deploy, environment

### Scope
- **Full sweep**: All modules in priority order
- **Focused**: [Specific module or area if user requested]
```

### Prioritization Heuristics

Explore high-risk areas first:

| Area | Risk Level | Why |
|------|-----------|-----|
| Authentication / Authorization | High | Security impact |
| Payment / Financial logic | High | Financial impact |
| Data mutations (create, update, delete) | High | Data integrity |
| External API integrations | Medium-High | Failure points, error handling |
| Input validation / Sanitization | Medium-High | Security surface |
| Core business logic | Medium | Correctness |
| Shared utilities | Medium | Wide blast radius |
| UI rendering / State management | Medium | User experience |
| Configuration / Environment | Low-Medium | Deployment issues |
| Static content / Styling | Low | Cosmetic impact |

## Phase 2: Explore

Systematically walk through each module in the exploration plan.

### Per-Module Exploration

For each module in the plan:

1. **Survey** — List all files in the module:
   ```
   Glob: "src/[module]/**/*"
   ```

2. **Read entry points** — Start with the main files (index, router, service class):
   ```
   Read the primary entry point for the module
   ```

3. **Trace flows** — Follow imports and function calls to understand execution paths:
   ```
   Read imported files to understand the call chain
   Trace: Entry point → Handler → Service → Data layer → Response
   ```

4. **Read tests** — Check what's tested and what's not:
   ```
   Glob: "src/[module]/**/*.test.*" or "tests/[module]/**/*"
   Read test files to understand expected behavior
   ```

5. **Note observations** — Record anything that stands out before moving to analysis

### Exploration Depth

| Module Complexity | Files to Read | Depth |
|-------------------|---------------|-------|
| Small (< 5 files) | All files | Full read |
| Medium (5-15 files) | Entry points + key logic + tests | Targeted read |
| Large (15+ files) | Entry points + representative samples + tests | Sampling |

Don't try to read every file in a large codebase. Sample strategically and trace the most important paths.

## Phase 3: Analyze

Review each explored module with "fresh eyes" — pretend you've never seen this code before and look critically for issues.

### Analysis Checklist

For each module, evaluate against these categories:

#### Bugs and Errors
| Check | What to Look For |
|-------|------------------|
| Null/undefined handling | Missing null checks, optional chaining needed |
| Error handling | Uncaught exceptions, swallowed errors, missing try/catch |
| Type safety | Unsafe casts, `any` types, missing validation |
| Race conditions | Async operations without proper sequencing |
| Off-by-one errors | Loop bounds, array indexing, pagination |
| Resource leaks | Unclosed connections, missing cleanup |
| Logic errors | Inverted conditions, wrong operators, incorrect comparisons |

#### Security
| Check | What to Look For |
|-------|------------------|
| Input validation | Unvalidated user input reaching business logic or queries |
| SQL/NoSQL injection | String concatenation in queries |
| XSS | Unescaped user content in HTML/templates |
| Auth/authz gaps | Missing permission checks, exposed endpoints |
| Secrets | Hardcoded credentials, keys in source |
| CSRF | Missing token validation on state-changing operations |

#### Code Quality
| Check | What to Look For |
|-------|------------------|
| Dead code | Unused functions, unreachable branches, commented-out code |
| Duplication | Same logic repeated across modules |
| Complexity | Functions doing too much, deeply nested conditionals |
| Naming | Misleading names, inconsistent conventions |
| Missing tests | Critical paths without test coverage |
| Outdated dependencies | Known vulnerabilities, deprecated APIs |

#### Performance
| Check | What to Look For |
|-------|------------------|
| N+1 queries | Database calls inside loops |
| Missing pagination | Unbounded data fetches |
| Unnecessary computation | Repeated calculations, missing memoization |
| Large payloads | Fetching full objects when only a few fields needed |
| Missing indexes | Queries on unindexed columns (check schema) |

### Fresh Eyes Principle

The key to effective analysis is approaching code without assumptions:
- Don't assume code works just because it's been in production
- Don't assume tests cover all cases just because tests exist
- Don't assume error handling is correct just because try/catch is present
- Question every assumption the code makes about its inputs
- Trace the actual data flow, don't just read the happy path

## Phase 4: Report

Produce a structured Roomba Report with all findings.

### Finding Format

Each finding follows this structure:

```markdown
### [ROOMBA-NNN] [Title]

**Category**: Bug | Security | Quality | Performance
**Module**: [module name]
**Impact**: High | Medium | Low
**Effort**: High | Medium | Low
**File(s)**: `path/to/file.ts:line`

**Finding**: [2-3 sentence description of the issue]

**Why it matters**: [1 sentence on the impact if left unfixed]

**Suggested action**: [1 sentence on what to do about it]

**Routes to**: scorpio-bug-investigate | scorpio-feature-plan | scorpio-task-plan
```

### Impact and Effort Ratings

**Impact** — What happens if this isn't fixed?

| Rating | Criteria |
|--------|----------|
| **High** | Security vulnerability, data loss risk, crash in production, major feature broken |
| **Medium** | Degraded UX, performance issue under load, error handling gap, maintainability concern |
| **Low** | Code smell, cosmetic issue, minor inconsistency, nice-to-have improvement |

**Effort** — How much work to fix?

| Rating | Criteria |
|--------|----------|
| **High** | Architectural change, multiple modules affected, requires migration |
| **Medium** | Multiple files, needs design thought, moderate testing needed |
| **Low** | Single file fix, straightforward change, obvious solution |

### Priority Matrix

Use impact and effort to suggest priority:

```
              │ Low Effort │ Med Effort │ High Effort │
──────────────┼────────────┼────────────┼─────────────┤
High Impact   │ DO FIRST   │ DO NEXT    │ PLAN        │
Medium Impact │ DO NEXT    │ CONSIDER   │ DEFER       │
Low Impact    │ CONSIDER   │ DEFER      │ SKIP        │
```

### Roomba Report Format

```markdown
# Roomba Report: [Project Name]

**Date**: [date]
**Scope**: Full sweep | Focused on [area]
**Modules explored**: [list]
**Project Context**: docs/PROJECT-CONTEXT.md

## Executive Summary

[3-5 sentences: overall codebase health assessment. What's good, what needs attention, what's concerning.]

## Findings Summary

| Priority | Count | Breakdown |
|----------|-------|-----------|
| DO FIRST | [N] | [N] bugs, [N] security |
| DO NEXT | [N] | [N] bugs, [N] quality |
| CONSIDER | [N] | [N] quality, [N] performance |
| DEFER | [N] | [N] quality |

### By Category
- **Bugs**: [N] findings
- **Security**: [N] findings
- **Quality**: [N] findings
- **Performance**: [N] findings

### By Module
| Module | Findings | Most Severe |
|--------|----------|-------------|
| [Auth] | [N] | [High / Medium / Low] |
| [API] | [N] | [High / Medium / Low] |

## Findings

### DO FIRST (High Impact)

[Findings sorted by impact, then effort]

### DO NEXT

[Findings]

### CONSIDER

[Findings]

### DEFER

[Findings]

## What's Working Well

[2-3 bullet points on strengths observed — Roomba isn't just a critic]

## Recommended Next Steps

1. [Top priority action] → Route to [skill]
2. [Second priority] → Route to [skill]
3. [Third priority] → Route to [skill]
```

## Phase 5: Route

Map each finding to the appropriate downstream skill pipeline.

### Routing Rules

| Finding Type | Route To | Why |
|-------------|----------|-----|
| Confirmed bug with clear reproduction | **scorpio-bug-investigate** | Already has context, skip triage interview |
| Suspected bug, needs investigation | **scorpio-bug-investigate** | Needs deeper trace to confirm |
| Security vulnerability | **scorpio-bug-investigate** (P0) | Treat as critical bug |
| Feature improvement idea | **scorpio-feature-plan** | Needs design before implementation |
| Code quality / refactoring | **scorpio-task-plan** | Can go straight to task generation |
| Performance optimization | **scorpio-feature-plan** | Needs investigation and design |
| Missing test coverage | **scorpio-task-plan** | Straightforward to task out |
| Dependency update | **scorpio-task-plan** | Chore task |

### Routing Output

At the end of the report, produce a routing summary:

```markdown
## Routing Plan

### → scorpio-bug-investigate
- ROOMBA-001: Null pointer in save handler (P0)
- ROOMBA-004: Auth bypass on admin endpoint (P0)
- ROOMBA-007: Race condition in checkout flow

### → scorpio-feature-plan
- ROOMBA-003: Refactor payment module for testability
- ROOMBA-009: Add caching layer for frequent queries

### → scorpio-task-plan
- ROOMBA-002: Remove dead code in utils module
- ROOMBA-005: Add missing tests for user service
- ROOMBA-008: Update deprecated API calls
```

### User Approval Gate

After producing the report and routing plan, **pause and present to the user**. The user decides:
- Which findings to pursue
- Which to defer or dismiss
- Whether to proceed with the suggested routing

Do not automatically trigger downstream skills. The report is the deliverable — the user drives what happens next.

## Scope Modes

### Full Sweep (default)

Explore all modules in priority order. Produces a comprehensive report.

```
"Run Roomba on this project"
"Do a full codebase health check"
```

### Focused Sweep

Explore a specific area of the codebase.

```
"Run Roomba on the authentication module"
"Roomba the API layer"
"Check the database queries for issues"
```

For focused sweeps, adjust the report to only cover the targeted area.

## What NOT To Do

- Do not fix code during the scan — Roomba is read-only, report-only
- Do not generate tasks directly — route through the appropriate skill
- Do not skip the orientation phase — context prevents false positives
- Do not report style preferences as bugs (use project conventions as the standard)
- Do not flag intentional trade-offs as issues (check docs/comments for rationale)
- Do not try to read every file in a large codebase — sample strategically
- Do not bury critical findings in a long list — prioritize clearly
- Do not only criticize — note what's working well too

## Handling Large Codebases

For projects with 100+ source files:

1. **Sample, don't exhaust** — Read representative files from each module
2. **Prioritize risk** — Spend more time on auth, data, and external interfaces
3. **Use grep strategically** — Search for known anti-patterns across the codebase:
   ```
   Grep: "any" in *.ts files → potential type safety issues
   Grep: "TODO|FIXME|HACK|XXX" → known issues the team has flagged
   Grep: "catch.*\{\}" or "catch.*\{ \}" → swallowed errors
   Grep: "console.log" → debug logging left in
   Grep: "password|secret|key|token" → potential hardcoded secrets
   ```
4. **Time-box** — If the codebase is enormous, focus on the top 3-5 modules and note remaining areas as "not yet scanned"

## Skill Chain

Roomba is the entry point for proactive codebase improvement:

```
scorpio-project-map → roomba → ┬→ scorpio-bug-investigate → scorpio-execute → scorpio-qa-final → scorpio-qa-rework
                           ├→ scorpio-feature-plan → scorpio-execute → scorpio-qa-final → scorpio-qa-rework
                           └→ scorpio-task-plan → scorpio-execute → scorpio-qa-final → scorpio-qa-rework
```

All downstream paths converge on the standard scorpio-execute → QA loop.