Agent Skills: Roadmap Analyst

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-Added section 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 sync when phase/spec status changes detected
• Next /roadmap next will detect status doc changes and trigger merge-based recalculation (preserves uncompleted items)
• --incremental variant: 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"
• update and plan scaffold/plan sync show unified diff preview and require explicit confirmation before writing
• --deep reports 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