roadmap

What this skill does

# Roadmap Analyst

Synthesize project documentation and codebase state into actionable status reports.

## Context Discovery

Run the shared context discovery protocol in [CONTEXT_DISCOVERY.md](../../references/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](../../references/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](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](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](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](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](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](../../references/LANE_DISCIPLINE.md). Stay in your lane.

## References

- [WORKFLOW.md](WORKFLOW.md) — Detailed discovery and mode workflows
- [EXAMPLES.md](EXAMPLES.md) — Usage examples
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — Common issues and fixes