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 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:

Complexity Scoring

Each finding includes complexity estimation for prioritization:

Per-Finding Complexity

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:

{
  "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>",
      "location": "<file:line or pattern>",
      "recommendation": "<how to fix>",
      "effort": "low|medium|high",
      "complexity": "TRIVIAL|LOW|MEDIUM|HIGH|EPIC",
      "impact": "low|medium|high",
      "quadrant": "quick-win|strategic|fill-in|avoid",
      "confidence": "0.0-1.0",
      "references": ["<links to docs/standards>"],
      "first_seen": "<timestamp>",
      "occurrences": "<count if recurring>"
    }
  ]
}

4. Trend Analysis

Compare current run to previous discovery results:

# Load previous discovery from contextd
mcp__contextd__memory_search(
  project_id: "<project>",
  query: "discovery analysis",
  limit: 1
)

# Compare findings
- New findings: Present now, absent before
- Resolved findings: Absent now, present before
- Regressions: Resolved previously, reappeared now
- Persistent: Present in both runs

Trend Metrics:

• •Improvement rate: % of findings resolved since last run
• •Regression rate: % of resolved findings that reappeared
• •Velocity: Average findings resolved per week
• •Accumulation: New findings introduced per week

5. Store in contextd

mcp__contextd__memory_record(
  project_id: "<project>",
  title: "Discovery: <lens> analysis",
  content: "Found <total> issues. CRITICAL: <n>, MAJOR: <n>.
            Top findings: <list top 3>.
            Trend: <+/-n> since last run. <n> quick wins available.",
  outcome: "success",
  tags: ["roadmap-discovery", "<lens>", "<date>"]
)

6. Create Artifacts (Optional)

Based on output format flags, generate artifacts.

Output Formats

GitHub Issues Format

When --create-issues flag is set:

gh issue create \
  --title "[<severity>][<lens>] <title>" \
  --label "<lens>,discovery,<severity-lowercase>" \
  --body "## Description
<description>

## Location
\`<file:line>\`

## Recommendation
<recommendation>

## Metadata
- **Effort:** <effort>
- **Complexity:** <complexity>
- **Impact:** <impact>
- **Confidence:** <confidence>

## References
<references>

---
*Generated by roadmap-discovery v2.0*"

Integration with github-planning skill:

• •Use github-planning skill for epic creation when findings > 10
• •Group related findings into parent issues
• •Apply project board automation labels

JIRA Import Format

When --jira flag is set, generate CSV:

Summary,Description,Issue Type,Priority,Labels,Story Points
"[SECURITY] <title>","<description>\n\nRecommendation: <rec>",Task,<priority>,discovery;security,<points>

Priority Mapping:

• •CRITICAL → Highest
• •MAJOR → High
• •MINOR → Medium
• •SUGGESTION → Low

Story Points Mapping:

• •TRIVIAL → 1
• •LOW → 2
• •MEDIUM → 5
• •HIGH → 8
• •EPIC → 13

Markdown Roadmap Format

When --markdown flag is set:

# Discovery Roadmap - <project>

Generated: <timestamp>
Previous Run: <timestamp or "First run">

## Executive Summary

- **Total Findings:** <n>
- **Critical Issues:** <n> (immediate attention required)
- **Quick Wins:** <n> (high impact, low effort)
- **Trend:** <+/-n> since last run

## Quick Wins (Do First)

| Finding | Lens | Effort | Location |
|---------|------|--------|----------|
| <title> | <lens> | <effort> | <location> |

## Critical Issues

### <title>
- **Severity:** CRITICAL
- **Location:** `<file:line>`
- **Description:** <description>
- **Recommendation:** <recommendation>

## By Category

### Security (<n> findings)
...

### Quality (<n> findings)
...

## Trend Analysis

| Metric | Value |
|--------|-------|
| Resolved since last | <n> |
| New since last | <n> |
| Regressions | <n> |
| Improvement rate | <n>% |

## Appendix: All Findings

<full findings table>

Integration Points

With /brainstorm

Run discovery before brainstorming to inform design:

1. /discover --lens all
2. Review findings
3. /brainstorm with context

With /init

Run discovery during project setup:

/init            # Set up project, then run /discover
/discover --lens security,quality

With github-planning

Create structured GitHub artifacts from findings:

/discover --lens all
# For many findings, use github-planning to create epic
/plan --from-discovery

Pre-session Hook

Can be configured as SessionStart hook for automatic context.

Cross-Project Comparison

With contextd, compare findings across projects:

mcp__contextd__memory_search(
  query: "discovery CRITICAL",
  limit: 10
)
# Aggregate patterns across all indexed projects

Limitations

• •Non-interactive: Cannot ask clarifying questions
• •Pattern-based: May have false positives
• •Point-in-time: Reflects current state only
• •Trend analysis requires previous contextd records

Attribution

Adapted from Auto-Claude roadmap_discovery and ideation agents. See CREDITS.md for full attribution.

Pre-Flight (MANDATORY)

BEFORE running ANY analysis:

1. Check repository index freshness:
   - If no index exists: mcp__contextd__repository_index(path: ".")
   - If HEAD changed since last index: re-index
   - Never skip indexing - stale data = stale findings

2. mcp__contextd__memory_search(
     project_id: "<project>",
     query: "discovery analysis <date>"
   )
   → Load recent discovery results for trend analysis

3. Determine lenses:
   - Default: all (run security, quality, perf, docs, dx, compliance, a11y)
   - If --lens specified: parse comma-separated list
   - If --core: run only security, quality, perf, docs
   - NEVER ask user which lens - use default or argument

4. Set finding caps:
   - Max 10 findings per lens per severity
   - Prioritize by confidence and impact

5. Check output format:
   - Default: terminal summary
   - Parse --create-issues, --jira, --markdown, --json flags

Do NOT ask the user any questions during discovery. This is autonomous analysis.

Mandatory Checklist

EVERY discovery invocation MUST complete ALL steps:

Analysis Phase:

• • Complete pre-flight (index check, memory search)
• • Run ALL specified lenses (default: all 7)
• • Use Task tool for parallel lens execution when possible
• • For each lens, execute analysis (see Run Lens Analyzers section)
• • Apply severity classification to each finding
• • Apply complexity scoring to each finding
• • Calculate effort vs impact quadrant
• • Apply confidence scoring

Quality Control:

• • Cap findings (max 10 per lens per severity)
• • Group similar findings
• • Remove duplicates
• • Sort by severity then confidence
• • Identify quick wins (high impact + low effort)

Trend Analysis:

• • Load previous discovery results from contextd
• • Calculate delta (new, resolved, regressions)
• • Compute improvement metrics
• • Flag regressions prominently

Output Phase:

• • Generate summary with counts by severity and lens
• • List quick wins first
• • List top findings (max 10 total)
• • If --create-issues: create GitHub Issues (respecting --min-severity)
• • If --jira: generate JIRA CSV
• • If --markdown: generate roadmap document
• • RECORD to contextd (see Storage section)

Error Handling:

• • If a lens fails, continue with other lenses
• • Report partial success with failure details
• • Never fail entire discovery for one lens error

Discovery is NOT complete until contextd recording is done.

Autonomy Requirements (Critical)

Discovery is 100% non-interactive. NEVER:

• •Ask "Which lens should I analyze?"
• •Ask "Should I create issues for this?"
• •Ask "Is this finding valid?"
• •Wait for user confirmation
• •Request clarification on severity

ALWAYS:

• •Make reasonable inferences based on patterns
• •Use confidence scores instead of asking
• •Run with defaults if no arguments provided
• •Complete fully without user input
• •Record ALL findings (contextd stores everything)
• •Use Task tool for parallel execution when appropriate

If you catch yourself about to ask a question: STOP. Make a decision and document it.

Red Flags - STOP and Reconsider

If you're thinking any of these, you're about to violate the skill:

Common Mistakes

Self-Sufficiency Protocol

Discovery must handle its own prerequisites:

Missing Index

IF mcp__contextd__semantic_search returns no results:
  mcp__contextd__repository_index(
    path: ".",
    exclude_patterns: ["node_modules/**", "vendor/**", ".git/**", "dist/**"]
  )
  THEN proceed with analysis

Stale Index

IF git log -1 --format=%H != last_indexed_commit:
  mcp__contextd__repository_index(path: ".")
  THEN proceed with analysis

Partial Lens Failure

IF security_analyzer throws error:
  record error in findings: "Security analysis failed: <reason>"
  continue with quality, perf, docs, dx, compliance, a11y analyzers
  include partial results in output
  note failure in summary

No Previous Discovery

IF mcp__contextd__memory_search returns no previous discovery:
  skip trend analysis
  note "First discovery run" in output
  proceed with full analysis

Confidence Scoring

Apply confidence to each finding:

When in doubt about severity or confidence: bias toward including the finding with documented uncertainty rather than asking the user.

Finding Caps (Quality Control)

Maximum findings per category:

Prioritization order:

1. •Severity (CRITICAL > MAJOR > MINOR > SUGGESTION)
2. •Quadrant (quick-win > strategic > fill-in > avoid)
3. •Confidence (HIGH > MEDIUM > LOW)
4. •Effort (LOW > MEDIUM > HIGH for same severity)

If over cap: drop lowest priority items, note "N additional findings omitted"

Extended Lens Details

Security Lens - OWASP Top 10 Coverage

Compliance Lens - License Categories

Accessibility Lens - WCAG Levels

Contextd Integration Details

Recording Findings

# Record summary for quick retrieval
mcp__contextd__memory_record(
  project_id: "<project>",
  title: "Discovery Run <date>",
  content: "<summary JSON>",
  outcome: "success",
  tags: ["discovery", "<date>"]
)

# Record individual critical findings
FOR each CRITICAL finding:
  mcp__contextd__memory_record(
    project_id: "<project>",
    title: "CRITICAL: <finding title>",
    content: "<finding details>",
    outcome: "pending",
    tags: ["discovery", "critical", "<lens>"]
  )

Tracking Resolution

When a finding is addressed:

mcp__contextd__memory_outcome(
  memory_id: "<finding_memory_id>",
  outcome: "resolved",
  notes: "Fixed in commit <sha>"
)

Cross-Project Analysis

# Find common patterns across projects
mcp__contextd__memory_search(
  query: "CRITICAL security",
  limit: 50
)
# Aggregate findings by type to identify systemic issues