Roadmap Analyst
Synthesize project documentation and codebase state into actionable status reports.
Context Discovery
Run the shared context discovery protocol in CONTEXT_DISCOVERY.md. Use the scan depth appropriate for the mode:
| Mode | Required Phases | Scan Depth |
|---|---|---|
plan show | 1 (config) | None — reads {plan_file} directly |
specs | 1, 5 | Light — config + doc scan for spec files |
gaps | 1, 3, 5 | Light — config, rich context, docs |
delta | 1, 5, 7 | Medium — config, docs, codebase scan |
next (cached) | 1 (config) | None — reads cached file + git drift check |
next (recalc) | 1-7 | Thorough — full protocol |
status, blockers, risks | 1-7 | Thorough — full protocol |
update, update --incremental | 1-7 | Thorough — full protocol |
plan scaffold, plan sync | 1-7 | Thorough — full protocol |
Store results for analysis below.
Arguments
Parse from $ARGUMENTS:
| Mode | Description |
|---|---|
status | Overall dashboard — modules, phases, completion + drift detection |
gaps | Gap analysis status — open/closed/in-progress with evidence |
next | Prioritized recommendations with caching and smart merge. Saves to {output_dir}/next-actions.md. Returns cached results if <3 feat/fix commits and status doc unchanged; otherwise merge-based recalculation that preserves uncompleted items and user additions. Add --force to recalculate (still merges; delete file manually for clean slate) |
delta | What changed since last assessment (read-only comparison) |
blockers | Blocking chain analysis with critical path |
risks | Risk register with likelihood/impact scoring |
update | Git-aware status doc update (Phase A: what shipped + Phase B: full scan + auto-chains plan sync). Add --incremental for post-sprint targeted edits only |
specs | Spec pipeline verification against codebase. Cross-references {plan_file} for phase linkage if available |
plan | Project plan lifecycle — scaffold (create), show (read), sync (update). Defaults to show if plan exists, scaffold if not |
| (none) | Full dashboard (combines status + gaps + next) |
Module Maturity Scale
Rate each module using the shared vocabulary in MATURITY_SCALE.md.
Mode Execution
status
Produce a status dashboard with module maturity table, then detail: What's working, What's planned, What's missing.
After producing the dashboard, run drift detection: if 3+ feat/fix commits exist since last {status_file} update, append a staleness notice suggesting /roadmap update.
gaps
Cross-reference all gap analysis documents. For each gap: original report, current status (Open/In Progress/Closed), evidence of closure.
next
Prioritized recommendations with git-aware caching and smart merge. See WORKFLOW.md § next for the full merge protocol.
Key behaviors:
- Saves recommendations to
{output_dir}/next-actions.md - Returns cached results if <3 feat/fix commits and status doc unchanged since last calculation
- On recalculation, merges new recommendations with existing items — preserves uncompleted items, removes items with completion evidence
- User-added items in
### User-Addedsection always preserved across recalculations - Shows merge diff preview with
+/-/~/=markers before writing (confirmation required) - Combines: unclosed gaps, unstarted specs, maturity imbalances, plan backlog themes
delta
Compare the status document against current codebase state. Highlight: new files/modules, closed gaps, new issues, migration count changes.
blockers
Trace blocking chains. For each blocker: what it blocks, who owns it, what's needed to unblock. Identify critical path (longest chain).
risks
Risk register with Likelihood (H/M/L) x Impact (H/M/L) scoring and suggested mitigations.
update
Git-aware status document update. See WORKFLOW.md § update for the full Phase A (git history scan) + Phase B (codebase scan + write) protocol.
Key behaviors:
- Shows "What Shipped" summary before scanning
- Diff preview with
+/-/~markers, requires confirmation before writing - Checks CHANGELOG.md for gaps (offers to add entries)
- Auto-chains into
plan syncwhen phase/spec status changes detected - Next
/roadmap nextwill detect status doc changes and trigger merge-based recalculation (preserves uncompleted items) --incrementalvariant: surgical targeted edits only (skips Phase B full scan)
specs
Spec pipeline verification — verify status against codebase evidence, not just what the spec says. If {plan_file} exists, cross-reference to show which phase each spec belongs to and flag unlinked specs.
plan
Consolidated project plan lifecycle. Read plan_file from .arkhe.yaml (default: docs/PROJECT-PLAN.md).
| Subcommand | Description |
|---|---|
scaffold | Create initial PROJECT-PLAN.md using hybrid linking algorithm — see WORKFLOW.md § plan scaffold |
show | Read-only summary with timeline, progress stats, active phases, drift detection |
sync | Git-aware update with auto-detected links — see WORKFLOW.md § plan sync |
| (none) | Default to show if plan exists; scaffold if not |
Output Rules
- Evidence-based — every claim backed by a file path, migration, or component
- Tabular — use tables for at-a-glance status; prose for analysis
- Actionable — always end with recommended next actions
- Honest — distinguish between "verified working" and "files exist but untested"
updateandplan scaffold/plan syncshow unified diff preview and require explicit confirmation before writing--deepreports are saved by default to{output_dir}/reports/; user can opt out
Deep Mode (--deep)
When $ARGUMENTS contains --deep, run the full multi-agent pipeline with parallel cross-perspective analysis. Three Sonnet agents analyze the project simultaneously from PM, Architect, and Roadmap perspectives, then a synthesizer merges findings and surfaces contradictions.
See WORKFLOW.md § Deep Pipeline for the 5-phase execution protocol.
Phase 4 produces a Confidence Scoreboard table with independent scores per finding. Findings below 70 are removed; 70-89 are tagged [NEEDS VALIDATION].
Patterns applied: Pipeline, Supervisor-Worker, Parallel Execution, Confession, Confidence-Gated Completion.
Lane Discipline
See the Roadmap Analyst section of LANE_DISCIPLINE.md. Stay in your lane.
References
- WORKFLOW.md — Detailed discovery and mode workflows
- EXAMPLES.md — Usage examples
- TROUBLESHOOTING.md — Common issues and fixes