joaquimscosta 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 |
next (cached) |
1 (config) | None — reads cached file + git drift check |
update --dry-run |
1, 5, 7 | Medium — config, docs, codebase scan (no write) |
status (with or without --focus) |
1-7 | Thorough — full protocol |
next (recalc) |
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. Renders Gaps, Blockers, Risks, and Specs as inline sections. Add --focus=<gaps|blockers|risks|specs> to render only one section |
update |
Git-aware status doc update (Phase A: what shipped + Phase B: full scan + auto-chains plan sync). Add --dry-run to preview the diff without writing. Add --incremental for post-sprint targeted edits only |
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) |
plan |
Project roadmap lifecycle — scaffold (create), show (read), sync (update). Defaults to show if roadmap exists, scaffold if not |
| (none) | Defaults to status. Footer suggests /roadmap next if next-actions.md is stale |
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, render four focus sections inline:
- Gaps — open/closed/in-progress with evidence (cross-references all gap analysis documents)
- Blockers — blocking chain analysis with critical path; for each blocker: what it blocks, owner, what's needed
- Risks — risk register with Likelihood (H/M/L) x Impact (H/M/L) scoring and suggested mitigations
- Specs — spec pipeline verification 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
With --focus=<gaps|blockers|risks|specs>, render only that section (skip the dashboard preamble and other sections).
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.
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) --dry-runvariant: runs Phase A + Phase B but stops at the diff preview without prompting or writing — read-only comparison of status doc vs current codebase--incrementalvariant: surgical targeted edits only (skips Phase B full scan)
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
plan
Consolidated project roadmap lifecycle. Read plan_file from .arkhe.yaml (default: docs/PROJECT-ROADMAP.md).
| Subcommand | Description |
|---|---|
scaffold |
Create initial PROJECT-ROADMAP.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 roadmap exists; scaffold if not |
Legacy file fallback: If {plan_file} is unset in .arkhe.yaml and docs/PROJECT-PLAN.md exists while docs/PROJECT-ROADMAP.md does not, treat the legacy path as {plan_file} for this run and emit a one-time migration notice suggesting mv docs/PROJECT-PLAN.md docs/PROJECT-ROADMAP.md (or pinning plan_file in .arkhe.yaml).
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