| name | roadmap-discovery |
| description | Use when analyzing codebase for improvements, running discovery, finding issues, auditing security/quality/performance/compliance/accessibility/DX, identifying tech debt, or scanning for problems. Autonomous non-interactive analysis with lens filtering (security, quality, perf, docs, dx, compliance, a11y) and severity classification (CRITICAL, MAJOR, MINOR, SUGGESTION). Supports parallel lens execution, complexity scoring, trend analysis, and multi-format output (GitHub Issues, JIRA, Markdown). |
Roadmap Discovery
Autonomous codebase analysis to identify improvement opportunities without user interaction.
Contextd Integration (Optional)
If contextd MCP is available:
repository_index for semantic searchbranch_create/return for isolated lens analysismemory_record for discovery persistencememory_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 projectscompliance - Run for enterprise or regulated industriesa11y - 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 exposureGrep: innerHTML|dangerouslySetInnerHTML → DOM injection risksGrep: sql.*\+|"SELECT.*\$|'SELECT.*\$ → SQL injectionGrep: 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 blocksGrep: 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 queriesGrep: \.forEach.*await|for.*await → Sequential async in loopsGrep: 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 textGrep: onClick(?![^}]*onKeyDown) → Click without keyboard handlerGrep: 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
| Flag | Output |
|---|
| (default) | Summary to terminal |
--create-issues | Create GitHub Issues |
--jira | JIRA import CSV format |
--markdown | Markdown roadmap document |
--json | Full JSON output |
--contextd-only | Store only, no terminal output |
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:
Quality Control:
Trend Analysis:
Output Phase:
Error Handling:
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:
| Thought | Reality |
|---|
| "Which lens should I run?" | Default is ALL. Run all 7 lenses. |
| "Should I ask about this finding?" | No. Use confidence scoring, not questions. |
| "Repository isn't indexed" | Index it yourself. mcp__contextd__repository_index. |
| "There are 100+ findings" | Cap at 10 per lens per severity. Quality > quantity. |
| "This lens failed, abort" | Continue other lenses. Partial success is valid. |
| "I'll skip contextd, just terminal output" | contextd recording is MANDATORY. |
| "User didn't specify lens" | Default = all. Don't ask. |
| "Not sure about severity" | Make your best judgment. Document rationale. |
| "Should I run lenses sequentially?" | Use Task tool for parallel execution. |
| "No previous run to compare" | Skip trend analysis, note "First run". |
Common Mistakes
| Mistake | Correct Approach |
|---|
| Asking user which lens to run | Default is ALL. Use --lens argument if specified. |
| Failing when repo not indexed | Auto-index with repository_index before analysis. |
| Returning 100+ findings | Cap at 10 per lens per severity. Prioritize by impact. |
| Aborting on lens failure | Continue with working lenses. Report partial success. |
| Skipping contextd | memory_record is mandatory for every discovery run. |
| Waiting for user input | Discovery is autonomous. Make decisions, document them. |
| Using stale index | Check if HEAD changed. Re-index if needed. |
| Treating all findings equally | Apply severity, complexity, AND confidence scoring. |
| Running lenses sequentially | Use Task tool for parallel lens execution. |
| Ignoring quick wins | Always identify and highlight quick wins first. |
| Skipping trend analysis | Always compare to previous run if available. |
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:
| Confidence | Meaning | Action |
|---|
| HIGH (0.8-1.0) | Pattern clearly matches, minimal false positive risk | Include in top findings |
| MEDIUM (0.5-0.79) | Likely issue, but context matters | Include with caveat |
| LOW (0.2-0.49) | Possible issue, may be false positive | Include only if CRITICAL severity |
| VERY LOW (<0.2) | Likely false positive | Exclude from output |
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:
| Level | Cap | Rationale |
|---|
| Per lens, per severity | 10 | Prevents flood of minor issues |
| Total per lens | 25 | Focus on most impactful |
| Total output | 50 | Actionable, not overwhelming |
| Top findings summary | 10 | User can digest quickly |
| Quick wins highlight | 5 | Immediate action items |
Prioritization order:
- Severity (CRITICAL > MAJOR > MINOR > SUGGESTION)
- Quadrant (quick-win > strategic > fill-in > avoid)
- Confidence (HIGH > MEDIUM > LOW)
- 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
| OWASP Category | Detection Pattern |
|---|
| A01: Broken Access Control | Auth middleware gaps, missing role checks |
| A02: Cryptographic Failures | Weak hashing, hardcoded secrets |
| A03: Injection | SQL concatenation, innerHTML, exec patterns |
| A04: Insecure Design | Missing rate limits, no input validation |
| A05: Security Misconfiguration | Debug mode, default creds, verbose errors |
| A06: Vulnerable Components | Outdated deps, known CVEs |
| A07: Auth Failures | Weak passwords, missing MFA |
| A08: Data Integrity | Missing signatures, untrusted deserialization |
| A09: Logging Failures | Missing audit logs, sensitive data in logs |
| A10: SSRF | Unvalidated URLs, fetch with user input |
Compliance Lens - License Categories
| License Type | Compatibility | Action |
|---|
| MIT, BSD, Apache 2.0 | Permissive | Generally safe |
| GPL, LGPL, AGPL | Copyleft | Review obligations |
| Proprietary | Restricted | Verify license agreement |
| Unknown | Risk | Investigate before use |
Accessibility Lens - WCAG Levels
| Level | Requirement | Examples |
|---|
| A (Minimum) | Basic accessibility | Alt text, keyboard nav |
| AA (Recommended) | Enhanced | Color contrast, focus visible |
| AAA (Optimal) | Full accessibility | Sign language, extended audio |
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
