roadmap-discovery

What this skill does

# Roadmap Discovery

Autonomous codebase analysis to identify improvement opportunities without user interaction.

## Contextd Integration (Optional)

If contextd MCP is available:
- `repository_index` for semantic search
- `branch_create/return` for isolated lens analysis
- `memory_record` for discovery persistence
- `memory_search` to compare with previous runs (trend analysis)
- Track which findings were addressed across sessions

If contextd is NOT available:
- Use Glob/Grep for pattern analysis
- Run lenses sequentially
- Output to terminal or `.claude/discovery/`

## When to Use

- **Pre-session:** Run before brainstorming for context
- **Onboarding:** Part of `/init` setup flow
- **On-demand:** Via `/discover` command
- **Trend tracking:** Compare current state to previous discovery runs

## Lenses

Filter analysis by concern:

| Lens | Focus Area |
|------|------------|
| `security` | OWASP Top 10, auth gaps, injection risks, secrets exposure, dependency vulnerabilities |
| `quality` | Test coverage, complexity, duplication, error handling |
| `perf` | N+1 queries, missing indices, unbounded operations, memory leaks |
| `docs` | Missing README sections, outdated comments, API gaps |
| `dx` | Onboarding friction, documentation gaps, tooling issues, contributor barriers |
| `compliance` | License audit, regulatory requirements, audit trails, data handling |
| `a11y` | WCAG compliance, a11y testing gaps, semantic HTML, ARIA usage |
| `all` | Run all lenses (default) |

### Lens Categories

**Core Lenses** (always recommended):
- `security`, `quality`, `perf`, `docs`

**Extended Lenses** (context-dependent):
- `dx` - Run for open source or team projects
- `compliance` - Run for enterprise or regulated industries
- `a11y` - Run for web/mobile UI projects

## Severity Framework

Classify findings by impact:

| Severity | Description | Action |
|----------|-------------|--------|
| CRITICAL | Security vulnerabilities, data loss risks | Immediate attention |
| MAJOR | Performance bottlenecks, significant UX issues | High priority |
| MINOR | Code smell, minor gaps | Normal priority |
| SUGGESTION | Nice-to-haves, polish items | Backlog |

## Complexity Scoring

Each finding includes complexity estimation for prioritization:

### Per-Finding Complexity

| Complexity | Effort | Typical Scope |
|------------|--------|---------------|
| TRIVIAL | < 1 hour | Single line change, config update |
| LOW | 1-4 hours | Single file, isolated change |
| MEDIUM | 1-2 days | Multiple files, some testing needed |
| HIGH | 3-5 days | Architectural change, significant refactor |
| EPIC | 1+ weeks | Major feature, cross-cutting concern |

### Effort vs Impact Matrix

Findings are classified into quadrants for prioritization:

```
                    HIGH IMPACT
                         │
    ┌────────────────────┼────────────────────┐
    │                    │                    │
    │   STRATEGIC        │   QUICK WINS       │
    │   (Plan for        │   (Do First)       │
    │    later)          │                    │
    │                    │                    │
────┼────────────────────┼────────────────────┼────
    │                    │                    │   LOW
HIGH│                    │                    │   EFFORT
EFFORT                   │                    │
    │   AVOID            │   FILL-INS         │
    │   (Deprioritize)   │   (Do when idle)   │
    │                    │                    │
    └────────────────────┼────────────────────┘
                         │
                    LOW IMPACT
```

**Quick Wins:** High impact, low effort - prioritize these
**Strategic:** High impact, high effort - plan and schedule
**Fill-ins:** Low impact, low effort - do during downtime
**Avoid:** Low impact, high effort - deprioritize or eliminate

## Execution Flow

### 1. Index Repository

```
mcp__contextd__repository_index(
  path: ".",
  exclude_patterns: ["node_modules/**", "vendor/**", ".git/**"]
)
```

### 2. Run Lens Analyzers

**Use Task tool for parallel execution when running multiple lenses.**

#### Parallel Execution Pattern

```
# Dispatch lenses in parallel via Task tool
Task(agent: "lens-analyzer", prompt: "Run security lens on <path>")
Task(agent: "lens-analyzer", prompt: "Run quality lens on <path>")
Task(agent: "lens-analyzer", prompt: "Run perf lens on <path>")
Task(agent: "lens-analyzer", prompt: "Run docs lens on <path>")
# Wait for all to complete, then aggregate
```

#### Core Lenses

**Security:**
- `Grep: password|secret|api_key|token|credential` → Secrets exposure
- `Grep: innerHTML|dangerouslySetInnerHTML` → DOM injection risks
- `Grep: sql.*\+|"SELECT.*\$|'SELECT.*\$` → SQL injection
- `Grep: crypto\.createHash\(['"]md5|sha1` → Weak cryptography
- Check `package.json`/`requirements.txt` for known vulnerable deps
- Scan for hardcoded IPs, URLs, or credentials
- OWASP Top 10 pattern matching

**Quality:**
- `Grep: catch\s*\(\w*\)\s*\{\s*\}` → Empty catch blocks
- `Grep: TODO|FIXME|HACK|XXX` → Technical debt markers
- Test file ratio analysis → Coverage gaps
- Cyclomatic complexity estimation → Overly complex functions
- Duplicate code detection → DRY violations

**Perf:**
- `Grep: for.*SELECT|\.find\(\)(?!.*limit)` → N+1 queries
- `Grep: \.forEach.*await|for.*await` → Sequential async in loops
- `Grep: JSON\.parse\(.*JSON\.stringify` → Unnecessary serialization
- Missing database indices check
- Unbounded array/list operations

**Docs:**
- `Glob: README.md` + section check → Required sections present
- API endpoint documentation → OpenAPI/Swagger coverage
- Inline comment quality → Complex code documented
- CHANGELOG.md existence and currency

#### Extended Lenses

**Developer Experience (dx):**
- `Glob: CONTRIBUTING.md` → Contributor guide exists
- Setup script analysis → Onboarding friction assessment
- `Grep: # TODO: document|needs docs` → Documentation debt
- Dev tooling audit → Linter, formatter, pre-commit hooks
- Local development environment → docker-compose, devcontainer
- Error message quality → Helpful vs cryptic errors

**Compliance:**
- `Glob: LICENSE*` → License file exists and valid
- Dependency license audit → Compatible licenses
- `Grep: PII|GDPR|HIPAA|SOC2` → Compliance markers
- Audit logging presence → Sensitive operations logged
- Data retention policies → Documented and implemented
- Third-party data sharing → Privacy policy alignment

**Accessibility (a11y):**
- `Grep: <img(?![^>]*alt=)` → Images without alt text
- `Grep: onClick(?![^}]*onKeyDown)` → Click without keyboard handler
- `Grep: role=|aria-` → ARIA usage patterns
- Semantic HTML analysis → div/span overuse vs semantic elements
- Color contrast indicators → Hardcoded colors to check
- Focus management → tabindex usage, focus traps
- `Glob: *.test.*|*.spec.*` → a11y test coverage (jest-axe, cypress-axe)

### 3. Aggregate Findings

Combine results across lenses:

```json
{
  "project": {
    "name": "<project>",
    "path": "<path>",
    "analyzed_at": "<timestamp>",
    "discovery_version": "2.0"
  },
  "summary": {
    "total_findings": "<count>",
    "by_severity": {
      "CRITICAL": "<count>",
      "MAJOR": "<count>",
      "MINOR": "<count>",
      "SUGGESTION": "<count>"
    },
    "by_lens": {
      "security": "<count>",
      "quality": "<count>",
      "perf": "<count>",
      "docs": "<count>",
      "dx": "<count>",
      "compliance": "<count>",
      "a11y": "<count>"
    },
    "quick_wins": "<count>",
    "total_effort_days": "<estimated>"
  },
  "trend": {
    "previous_run": "<timestamp or null>",
    "delta": {
      "total": "<+/- count>",
      "CRITICAL": "<+/- count>",
      "MAJOR": "<+/- count>"
    },
    "resolved_since_last": ["<finding_ids>"],
    "new_since_last": ["<finding_ids>"],
    "regressions": ["<finding_ids that reappeared>"]
  },
  "findings": [
    {
      "id": "find_001",
      "lens": "security",
      "severity": "MAJOR",
      "title": "<short title>",
      "description": "<detailed description>