Roadmap

Roadmap Analyst

Synthesize project documentation and codebase state into actionable status reports.

Context Discovery

Run the shared context discovery protocol in CONTEXT_DISCOVERY.md. Execute all phases in order (use thorough scan mode for Phase 7). Store results for analysis below.

Arguments

Parse from $ARGUMENTS:

Module Maturity Scale

Rate each module using the shared vocabulary in MATURITY_SCALE.md.

Mode Execution

status

Produce a status dashboard:

Then detail: What's working, What's planned, What's missing.

After producing the dashboard, check for documentation drift:

1. Find last modification of {status_file} via git: git log -1 --format="%H %ai" -- {status_file} 2. Count feature/fix commits since: git log {hash}..HEAD --oneline --no-merges | grep -cE "^[a-f0-9]+ (feat|fix):" 3. If 3 or more feat/fix commits exist since last update, append a notice at the end of the output:

⚠️  Documentation may be stale: {N} feature/fix commits since last status update ({date}).
Run `/roadmap update` to sync.

gaps

Cross-reference all gap analysis documents. For each gap: original report, current status (Open/In Progress/Closed), evidence of closure.

next

Prioritized recommendations combining: unclosed gaps, unstarted specs, module maturity imbalances, frontend-backend parity gaps.

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.

risks

Risk register:

update

Generate an updated status document with git-history awareness. Two phases:

Phase A: Git History Scan

Before the codebase scan, analyze what changed since the last doc update:

1. Find last modification of {status_file}: git log -1 --format="%H %ai" -- {status_file} 2. If no previous commit found, skip Phase A (first-time setup — Phase B handles it) 3. List commits since: git log {hash}..HEAD --oneline --no-merges 4. Group by PR number (parse (#NN) from commit messages) and commit type (feat:, fix:, docs:, etc.) 5. For each feature/fix group, summarize:

• Scope (new components, routes, hooks, test files — inferred from file paths in the diff)
• Related specs (cross-reference arkhe/specs/ changes in the commit range)
• Related ADRs (new files in docs/adr/ in the commit range)

6. Present a "What Shipped" summary to the user before proceeding to the full scan:

## What Shipped Since Last Update (2026-03-09, 10 commits ago)

1. Glossary Management + Dictionary Browser (PR #32, specs 022-025)
   - 6 components, 2 hooks, 5 test files, /dictionary route
2. App Header Unification (PR #33)
   - Refactored navigation components
3. skrebe.app Redirect (1aff903, ADR-0010)
   - New middleware + DNS config

This context feeds into Phase B so the codebase scan knows what to look for and can produce more accurate updates.

Phase B: Full Codebase Scan + Write (existing behavior, enhanced)

1. Run full context discovery + codebase scan (same as before) 2. Read existing status document 3. Preserve format and structure 4. Update all data points — now informed by the git history from Phase A:

• Module maturity ratings
• Phase completion entries (Phase A identifies which phases completed)
• Spec pipeline entries (Phase A identifies which specs shipped)
• ADR table entries (Phase A identifies new ADRs)
• Test coverage section
• Commit count and date
• Risk register (close risks for shipped features)

5. Show diff preview and ask for confirmation 6. Write updated file to {status_file} 7. Also check CHANGELOG.md — if [Unreleased] is missing entries for shipped features from Phase A, suggest adding them after the status update is applied (don't auto-write CHANGELOG without explicit confirmation) 8. Report changes made

specs

Spec pipeline verification:

Verify status against codebase, not just what the spec says.

plan

Consolidated project plan — lifecycle management from scaffold to sync.

Read plan_file from .arkhe.yaml roadmap: section (default: docs/PROJECT-PLAN.md).

Parse subcommand from remaining arguments:

plan scaffold

Create the initial plan document by consolidating scattered planning artifacts.

1. Context discovery — run standard protocol (CONTEXT_DISCOVERY.md) 2. Read existing docs — read {status_file}, product roadmaps (docs/**/roadmap.md), backlogs (docs/**/backlog.md) 3. Scan specs — glob {specs_dir}/*/spec.md, extract: spec ID (directory name), title (first # heading), status (Status: field) 4. Scan ADRs — glob docs/adr/[0-9]*.md, extract: number (filename), title (first # heading), status 5. Auto-detect phase mappings — run the hybrid linking algorithm (see WORKFLOW.md § Hybrid Linking Algorithm) 6. Present proposed plan — show full document in chat with [AUTO-LINKED] markers on detected mappings, [MANUAL] on explicit matches, [UNLINKED] on unmapped items 7. Confirm — ask user to review linkages and approve; apply corrections 8. Write — write to {plan_file}

If {plan_file} already exists, warn and offer: overwrite, sync instead, or cancel.

plan show

Read-only consolidated view.

1. Read {plan_file} — if missing, suggest scaffold 2. Parse and present summary: timeline table, progress stats (phases done/total, specs linked/total, ADRs linked/total), active phases, next up 3. Drift detection: if plan doc was last committed >7 days ago and 3+ feat/fix commits exist since, append: "⚠️ Plan may be stale. Run /roadmap plan sync to update."

plan sync

Git-aware update of the plan document — follows the update mode's Phase A + Phase B pattern.

1. Phase A: Git History Scan — detect since last plan sync: new/modified specs, new ADRs, phase completion signals (feat: commits grouped by PR), backlog changes 2. Phase B: Auto-detect new links — run hybrid linking on any new specs/ADRs from Phase A 3. Phase C: Diff and confirm — show proposed changes as +/-/~ markers; ask confirmation 4. Phase D: Write — update {plan_file} preserving user-edited sections

See WORKFLOW.md § plan for detailed execution protocol.

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 (using +/-/~ markers) 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

Roadmap Skill — Examples

Usage examples for the Roadmap Analyst skill.

Example 1: Status Dashboard

Input: /roadmap:roadmap status

Output:

## Project Status Dashboard
_Generated: 2026-02-17_

### Module Overview

| Module | Backend | Frontend | Maturity | Notes |
|--------|---------|----------|----------|-------|
| auth | JWT + refresh tokens | Login page + protected routes | API Ready | Missing MFA |
| catalog | CRUD endpoints | List + detail pages | Tested | Good coverage |
| orders | Service layer only | Not started | Service Layer | No controllers yet |
| payments | Stub (Stripe types) | Not started | Stub | Blocked on Stripe setup |
| notifications | Not started | Not started | — | Not yet considered |

### Working Features
- User authentication: `src/auth/` (JWT, refresh, logout)
- Catalog browsing: `src/catalog/` (6 endpoints, paginated)
- Product search: `src/catalog/search.ts` (full-text via Postgres)

### Planned Features
- Order management: spec exists (`arkhe/specs/003-orders/spec.md`)
- Payment processing: referenced in roadmap, no spec yet

### Missing / Not Started
- Notifications: no docs, no code
- Admin dashboard: mentioned in README but no further planning

### Recommended Next Actions
1. Complete orders module (controllers + frontend) — spec ready
2. Create payment spec — blocks revenue features
3. Design notification system — growing user need

Example 2: Gap Analysis

Input: /roadmap:roadmap gaps

Output:

## Gap Analysis Tracking

| Gap | Source | Status | Evidence |
|-----|--------|--------|----------|
| No rate limiting | api-gap-analysis.md | Open | No middleware found |
| Missing input validation | api-gap-analysis.md | Closed | `src/middleware/validate.ts` |
| No error boundaries | design-gap-analysis.md | In Progress | `ErrorBoundary.tsx` exists, not wired to all routes |
| No loading states | design-gap-analysis.md | Closed | Skeleton components in `src/components/ui/` |
| No audit trail | security-review.md | Open | No logging beyond console |
| No backup strategy | infra-review.md | Open | No backup scripts or config |

### Summary
- **Total gaps:** 6
- **Closed:** 2 (33%)
- **In Progress:** 1 (17%)
- **Open:** 3 (50%)

### Priority Open Gaps
1. Rate limiting — security risk, should address before launch
2. Audit trail — compliance requirement
3. Backup strategy — data loss risk

Example 3: Blockers Analysis

Input: /roadmap:roadmap blockers

Output:

## Blocking Chain Analysis

### Critical Path
Stripe API keys → Payment module → Order checkout → Revenue features

### Blocking Items

| Blocker | Blocks | Owner | Needed Action |
|---------|--------|-------|---------------|
| Stripe API keys not provisioned | Payment module | DevOps | Request sandbox keys |
| Payment module stub | Order checkout flow | Backend | Implement after Stripe |
| No CI/CD pipeline | Production deployment | DevOps | Set up GitHub Actions |
| Design system incomplete | All new UI work | Frontend | Finish token migration |

### External Dependencies
- **Stripe**: Sandbox access needed. No ETA from provider.
- **DNS**: Domain purchased but not configured for production.

### Unblocking Recommendations
1. Request Stripe sandbox keys immediately (unblocks payment → orders)
2. Set up CI/CD pipeline (unblocks deployments)
3. Complete design token migration (unblocks UI work)

Example 4: Delta Report

Input: /roadmap:roadmap delta

Output:

## Delta Report
_Comparing PROJECT-STATUS.md (2026-02-10) vs current codebase_

### New Since Last Update
- 3 new migration files: V005, V006, V007
- New module: `src/search/` (full-text search)
- 12 new test files in `tests/catalog/`
- New component: `SearchBar.tsx`

### Gaps Closed
- Input validation: now present in all API routes
- Loading states: skeleton components added

### New Issues
- `src/orders/checkout.ts` has TODO: "implement payment integration"
- Test coverage dropped in `auth` module (removed 2 test files)

### Metrics
| Metric | Previous | Current | Change |
|--------|----------|---------|--------|
| Source files | 47 | 58 | +11 |
| Test files | 23 | 33 | +10 |
| Migrations | 4 | 7 | +3 |
| API endpoints | 12 | 15 | +3 |

Example 5: Risk Register

Input: /roadmap:roadmap risks

Output:

## Risk Register

| # | Risk | Likelihood | Impact | Score | Mitigation |
|---|------|-----------|--------|-------|------------|
| 1 | No rate limiting | High | High | Critical | Add express-rate-limit before launch |
| 2 | Single point of failure (1 server) | Medium | High | High | Plan horizontal scaling |
| 3 | No backup strategy | Low | High | Medium | Implement daily DB backups |
| 4 | Payment integration delay | Medium | Medium | Medium | Build order system without payments first |
| 5 | Design system debt | Medium | Low | Low | Schedule token migration sprint |

Example 6: Spec Pipeline

Input: /roadmap:roadmap specs

Output:

## Spec Pipeline

| Spec | Title | Status | Evidence |
|------|-------|--------|----------|
| 001-auth | Authentication | Complete | All endpoints live, tests passing |
| 002-catalog | Product Catalog | Complete | CRUD + search implemented |
| 003-orders | Order Management | In Progress | Service layer only, no controllers |
| 004-payments | Payment Processing | Proposed | Spec exists, no implementation |
| 005-notifications | Notifications | — | No spec, no implementation |

### Summary
- **Complete:** 2/4 (50%)
- **In Progress:** 1/4 (25%)
- **Proposed:** 1/4 (25%)
- **No Spec:** 1 feature mentioned in roadmap but not specified

Example 7: Update with Git History (Phase A + B)

Input: /roadmap update

Output (Phase A — What Shipped):

## What Shipped Since Last Update
_Last update: 2026-03-09 (da3c514), 10 commits ago_

1. **Glossary Management + Dictionary Browser** (PR #32)
   - Specs: 022, 023, 024, 025
   - 6 new components, 2 hooks, 5 test files
   - New route: /dictionary

2. **App Header Unification** (PR #33)
   - Refactored: AppHeader.tsx, NavLinks.tsx

3. **skrebe.app Redirect** (1aff903)
   - New ADR: 0010-skrebe-app-domain-redirect.md

⚠️  CHANGELOG.md [Unreleased] is missing entries for 3 features.

Running full codebase scan...

Output (Phase B — Proposed Updates):

## Proposed Updates to docs/PROJECT-STATUS.md

  ~ Last updated: 2026-03-09 → 2026-03-15
  ~ Branch: da3c514 → 1aff903
  ~ Velocity: 129 → 139 commits
  ~ skrebe-web: 4 routes → 5 routes, ~54 → ~63 components, 12 → 18 hooks
  ~ text-core: 8 → 10 test files
  + Phase 3e: Glossary Management + Dictionary Browser → Done
  + Phase 3f: ALUPEC Phonology Rule → Done
  + Spec 022: Glossary Management UX → Complete
  + Spec 023: Glossary UX Polish → Complete
  + Spec 024: Glossary Gap Detection → Complete
  + Spec 025: Dictionary Browser → Complete
  + ADR 0010: skrebe.app → papia.studio redirect → Active
  + Test row: Glossary (4 files) + Dictionary (3 files)

Apply updates to PROJECT-STATUS.md? (y/N)

After approval, if CHANGELOG gaps exist:

Add CHANGELOG entries for 3 shipped features under [Unreleased]? (y/N)

Example 8: Status with Drift Warning

Input: /roadmap status

Output (end of dashboard):

### Recommended Next Actions
1. Translation Memory + Eval Harness (Phase 4) — next on Track A
2. Expand LLM golden pairs — 5 → 10-15

---
⚠️  Documentation may be stale: 4 feature/fix commits since last status update (2026-03-09).
Run `/roadmap update` to sync.

Zero-Config Example

The skill adapts to any project structure:

[No .arkhe.yaml found — using dynamic discovery]
[Read CLAUDE.md — identified as Python Django project]
[Detected: pyproject.toml, Django 5.0]
[Found apps/: users, products, orders, payments]
[Found tests/: 45 test files]
[Found docs/: architecture.md, api-spec.md]

## Project Status Dashboard
...

---

Example 9: Plan Scaffold

Input: /roadmap:roadmap plan scaffold

Output:

## Context Discovery
[Standard context discovery — found .arkhe.yaml, PROJECT-STATUS.md, 2 roadmaps, 1 backlog]

## Planning Artifacts Found
- docs/PROJECT-STATUS.md — 14 phases, 26 specs in pipeline, 10 ADRs
- docs/skrebe/roadmap.md — 9 backlog themes
- docs/papia-asr/roadmap.md — 6 backlog themes
- arkhe/specs/ — 26 spec directories scanned

## Hybrid Linking Results

### Confirmed (from existing docs)
- Spec 01 → Phase 1c [MANUAL] — listed in PROJECT-STATUS.md "PR #6"
- Spec 022-025 → Phase 3e [MANUAL] — listed in PROJECT-STATUS.md
- ADR-0007 → Phase ASR-1 [MANUAL] — referenced in papia-asr/roadmap.md
  (22 specs + 8 ADRs confirmed from docs)

### Auto-Detected (from git history)
- Spec 020 → Phase 3d [AUTO-LINKED] — created 2026-03-08, during Phase 3d window
- ADR-0010 → Phase 3b [AUTO-LINKED] — created 2026-03-01

### Unlinked
- Spec 000 (Trust Guards) → ? [UNLINKED] — predates defined phases

Review the proposed plan. Adjust any linkages? (Type corrections or 'approve')
> Spec 000 → Phase 0. Otherwise approve.

Writing to docs/PROJECT-PLAN.md...
Plan created with 14 phases, 26 specs linked, 10 ADRs linked, 9 backlog themes.

---

Example 10: Plan Show

Input: /roadmap:roadmap plan

Output:

## Project Plan Summary
_Source: docs/PROJECT-PLAN.md (last synced: 2026-04-03)_

### Timeline
| Phase | Status | Specs | ADRs |
|-------|--------|-------|------|
| 0 | Done | 1 | 2 |
| 1a-b | Done | 2 | 1 |
| 1c | Done | 1 | 0 |
| 1d | Done | 1 | 0 |
| 1e | Done | 3 | 0 |
| 2 | Done | 3 | 0 |
| 3a-f | Done | 6 | 2 |
| 4 | In Progress | 0 | 0 |
| ASR-1 | Done | 1 | 1 |
| ASR-2 | Not Started | 0 | 0 |

### Progress
- Phases: 13/16 complete (81%)
- Specs: 26/26 linked to phases
- ADRs: 10/10 linked to phases
- Backlog: 9 themes (1 active)

### Active Phase(s)
**Phase 4: TM + Eval** — TM core shipped (PR #35); eval harness + fuzzy UX remaining

### Next Up
Backlog Theme 5: Word List Quality (High priority, no blockers)

---

Example 11: Plan Sync

Input: /roadmap:roadmap plan sync

Output:

## What Changed Since Last Sync
_Last sync: 2026-04-01 (bb4804d), 3 commits ago_

1. **CI Workflow** (PR #37, ci:) — new GitHub Actions workflow
2. **TM Case Fix + F1 Selector** (PR #38, fix:) — bug fixes in TM matching
3. **Docs updates** (docs:) — PROJECT-STATUS.md, roadmap sync

## Auto-Detection
- No new specs found
- No new ADRs found
- Phase 4: no completion signal (still In Progress)

## Proposed Updates to docs/PROJECT-PLAN.md

  ~ Phase 4 evidence: added "PR #38 — case-insensitive TM matching"
  ~ Timeline last-synced date: 2026-04-01 → 2026-04-03

Apply updates to docs/PROJECT-PLAN.md? (y/N)
> y

Plan document updated. 2 changes applied.

---

Example 12: Incremental Update (Post-Sprint Sync)

Input: /roadmap:roadmap update --incremental

Context: After completing Sprint 010 using /core:develop. Wave context files exist.

Output:

## Wave Context
Found wave-context-3.md from /core:develop session (2026-04-02).
Features built: offline sync engine, conflict resolution UI, service worker.

## What Shipped Since Last Update (2026-03-28, 8 commits ago)

1. **Offline Sync Engine** (PR #38, feat:, specs 027-029)
   - 4 services, 2 hooks, 8 test files
2. **Conflict Resolution UI** (PR #39, feat:, spec 030)
   - 3 components, 1 hook, 4 test files
3. **Service Worker Registration** (PR #40, fix:)
   - Updated PWA config, added cache strategies

## Proposed Updates to docs/PROJECT-STATUS.md

### Header
  ~ Last updated: 2026-03-28 -> 2026-04-02
  ~ Commits: 144 -> 152
  ~ Branch hash: a1b2c3d -> e4f5g6h

### Module Maturity
  ~ offline-sync: Service Layer -> Tested
  ~ conflict-resolution: Stub -> Service Layer

### Phases
  ~ Phase 2 (Offline-First): In Progress -> Done

### Specs
  + Spec 027: Sync Engine Core -> Complete
  + Spec 028: Conflict Detection -> Complete
  + Spec 029: Background Sync -> Complete
  + Spec 030: Conflict Resolution UI -> Complete

Apply updates to docs/PROJECT-STATUS.md? (y/N)
> y

Status document updated. 9 changes applied.
Phase status changed. Run `/roadmap plan sync` to update the project plan.

Roadmap Skill — Troubleshooting

Common issues and fixes for the Roadmap Analyst skill.

Status Report Shows No Modules

Symptom: Module table is empty or shows only root-level files.

Cause: Codebase structure doesn't match expected patterns.

Fix: 1. Create .arkhe/roadmap/architecture.md describing your module structure:

   ## Modules
   - `services/auth/` — Authentication service
   - `services/api/` — API gateway
   - `web/` — Frontend application

2. Or ensure modules follow standard patterns: src/, apps/, packages/, libs/

Gap Analysis Returns Empty

Symptom: Gaps mode says "No gap analysis documents found."

Cause: No documents matching gap analysis patterns found.

Fix: 1. Create .arkhe/roadmap/documents.md listing your gap analyses:

   ## Gap Analyses
   - `docs/reports/api-gaps.md` — API completeness assessment
   - `docs/reports/security-review.md` — Security findings

2. Or place gap analysis docs in standard locations: docs/reports/, docs/gaps/

Delta Report Says "No Previous Status"

Symptom: Delta mode can't find a previous status document to compare against.

Cause: No PROJECT-STATUS.md or configured status file exists.

Fix: 1. Run update mode first to create a baseline: /roadmap:roadmap update 2. Or set the status file path in .arkhe.yaml:

   roadmap:
     status_file: docs/PROJECT-STATUS.md

Update Mode Overwrites Custom Sections

Symptom: Running update removes custom sections from the status doc.

Cause: Custom sections don't match expected format.

Fix: The skill preserves existing structure. If custom sections are lost: 1. Use version control to restore: git diff docs/PROJECT-STATUS.md 2. Add custom sections under a ## Custom heading — the skill won't modify unknown headings

Maturity Ratings Seem Wrong

Symptom: Module rated as "Stub" but has real code.

Cause: Files don't match tech-stack-aware scan patterns.

Fix: 1. Check that your tech stack was correctly detected (build file present at root) 2. Describe module structure in .arkhe/roadmap/architecture.md 3. Verify files are in expected locations for your framework

Blockers Mode Misses External Dependencies

Symptom: Known external blockers (API keys, approvals) not shown.

Cause: External dependencies aren't documented in discoverable files.

Fix: Document blockers in: 1. .arkhe/roadmap/project.md under a ## Blockers section 2. Or in your status document under a ## Blockers heading 3. Or in gap analysis documents

Specs Mode Can't Find Specs

Symptom: Spec pipeline is empty despite having spec files.

Cause: Specs are in a non-standard location.

Fix: 1. Standard locations: arkhe/specs/*/spec.md, specs/**/*.md, docs/specs/**/*.md 2. Or configure in .arkhe.yaml:

   roadmap:
     context_dir: .arkhe/roadmap

And in .arkhe/roadmap/documents.md:

   ## Specs
   - `planning/features/*/requirements.md` — Feature specs

Update Phase A Shows "No Commits Since Last Update" But Docs Seem Wrong

Symptom: Phase A (git history scan) reports no drift, but the status doc has incorrect or outdated content.

Cause: The status file was recently committed (perhaps with errors or incomplete data), so git history shows no gap.

Fix: Phase B (full codebase scan) still runs regardless of Phase A results. Phase A is additive context that helps Phase B be more targeted — but Phase B catches discrepancies whether or not git shows drift. If the content is wrong despite a recent commit, Phase B will propose corrections based on the actual codebase state.

When to Use update vs delta

Use delta when you want to see what's stale without changing anything. Use update when you want to fix the staleness.

Risk Scores Seem Arbitrary

Symptom: Risk likelihood/impact ratings don't match project context.

Cause: Insufficient context about project priorities and constraints.

Fix: 1. Define project constraints in .arkhe/roadmap/project.md:

   ## Constraints
   - Launch deadline: Q2 2026
   - Single developer
   - Budget: limited cloud spend

2. These constraints inform risk scoring (tight deadline = higher impact for delays)

When to Use update vs update --incremental

Use --incremental when you know what changed (just finished a sprint) and want to quickly record it. Use full update when you suspect the document has drifted and need a comprehensive reconciliation.

Note: --incremental reads wave-context files from /core:develop if available, but works with git-only when they aren't present.

Plan Scaffold Produces Empty Phases

Symptom: Timeline section has few or no phases after scaffolding.

Cause: No status document or roadmap files with phase tables found. The scaffold requires at least one source of phase information.

Fix: 1. Ensure {status_file} exists and contains a phase table (run /roadmap update to create one) 2. Or ensure docs/**/roadmap.md files exist with phase lists 3. If starting from scratch, create a minimal phase table in your status doc first, then scaffold

Plan Sync Says "No Changes" But Plan Seems Stale

Symptom: /roadmap plan sync reports no changes, but the plan document has incorrect or outdated data.

Cause: The plan doc was recently synced (git shows no gap between sync and HEAD), but content was already wrong at last sync time.

Fix: Run /roadmap plan scaffold to regenerate from current state. Scaffold always rebuilds from scratch (with overwrite confirmation), while sync only applies incremental changes from git history since the last sync.

Roadmap Skill — Workflow

Detailed codebase scanning protocol and mode workflows for the Roadmap Analyst skill.

Context Discovery Protocol

Run the shared context discovery protocol in CONTEXT_DISCOVERY.md. Execute all phases in order (use thorough scan mode for Phase 7). For tech-stack-aware module scanning, see TECH_STACK_DETECTION.md. For module maturity assessment, see MATURITY_SCALE.md.

Mode Workflows

status

1. Run full context discovery 2. Build module inventory with maturity ratings 3. Cross-reference docs against codebase:

• Features described in docs → find implementation evidence
• Implementation found → verify it matches documentation

4. Produce dashboard:

• Module maturity table
• What's working (evidence-backed)
• What's planned (doc-backed)
• What's missing (no docs, no code)

5. Drift detection — after producing the dashboard:

• Get last {status_file} commit: git log -1 --format="%H %ai" -- {status_file}
• Count feat:/fix: commits since that hash: git log {hash}..HEAD --oneline --no-merges | grep -cE "^[a-f0-9]+ (feat|fix):"
• If >= 3, append a notice at the end of the output:

     ⚠️  Documentation may be stale: {N} feature/fix commits since last status update ({date}).
     Run `/roadmap update` to sync.

6. Plan reference — if {plan_file} exists, append: "Full project plan: {plan_file}". Apply the same drift detection to {plan_file} and suggest /roadmap plan sync if stale.

gaps

1. Run context discovery 2. Find all gap analysis documents 3. For each gap:

• Extract the original finding
• Search codebase for closure evidence
• Classify: Open / In Progress / Closed

4. Produce gap tracking table with evidence

next

1. Run full context discovery (thorough) 2. Collect all open items:

• Unclosed gaps
• Unstarted specs
• Module maturity imbalances
• Frontend-backend parity issues

3. If {plan_file} exists, also consult:

• The Backlog section for prioritized themes with dependencies
• The Timeline for the next "Not Started" phase
• Use these as additional inputs when ranking

4. Rank by: impact, effort, dependencies, urgency 5. Recommend 3-5 prioritized next actions

delta

1. Read the status document (from config or default path) 2. Run codebase scan 3. Compare current state vs documented state:

• New files, modules, migrations since last update
• Gaps that have been addressed
• New issues or regressions
• Metric changes (file counts, test counts)

4. Produce delta report

blockers

1. Run context discovery 2. Identify blocking items from:

• Gap analyses (dependencies marked as blocking)
• Specs (prerequisites not met)
• Research (unanswered questions blocking decisions)
• External dependencies (APIs, services, approvals)

3. Trace blocking chains:

• A blocks B blocks C
• External X blocks internal Y

4. Identify critical path (longest blocking chain)

risks

1. Run context discovery 2. Extract risks from:

• Gap analyses
• Research documents
• Module maturity assessment (immature critical modules = risk)
• Missing tests (untested code = risk)
• External dependencies

3. Score each: Likelihood (H/M/L) x Impact (H/M/L) 4. Suggest mitigations 5. Produce risk register

update

Phase A: Git History Scan

1. Read .arkhe.yaml for status_file path (default: docs/PROJECT-STATUS.md) 2. Get last status doc commit:

   git log -1 --format="%H %ai" -- {status_file}

3. If no previous commit found, skip Phase A (first-time setup — Phase B handles it) 4. List commits since last doc update:

   git log {last_hash}..HEAD --oneline --no-merges

5. Categorize commits:

• feat: → new features (group by PR number if (#NN) present in message)
• fix: → bug fixes
• docs(adr): or new files in docs/adr/ → ADR additions
• Changes to arkhe/specs/*/spec.md → spec completions
• New *.test.* or *.spec.* files → test count changes

6. For each feature group, check the diff for scope:

   git diff --stat {last_hash}..{feature_commit} -- packages/ src/

7. Present "What Shipped" summary to the user before proceeding 8. Also check CHANGELOG.md — flag if [Unreleased] is missing entries for any feature groups

Phase B: Full Codebase Scan + Write

1. Run full context discovery + full codebase scan (existing behavior) 2. Read existing status document 3. Preserve format and structure 4. Update all data points — now informed by Phase A findings:

• Module maturity ratings
• Phase completion entries (add rows for shipped phases identified in Phase A)
• Spec pipeline entries (add rows for completed specs identified in Phase A)
• ADR table entries (add new ADRs discovered in Phase A)
• Test coverage section (update counts)
• Header: commit count, date, branch hash
• Risk register: close risks addressed by shipped features
• Recommended next actions: refresh based on current state

5. Diff Preview (Required Format)

Present proposed changes using unified diff markers, grouped by document section:

   ## Proposed Updates to {status_file}

   ### Header
     ~ Last updated: {old_date} -> {new_date}
     ~ Branch: {old_hash} -> {new_hash}
     ~ Velocity: {old_count} -> {new_count} commits

   ### Module Maturity
     ~ {module}: {old_maturity} -> {new_maturity}

   ### Phases
     + Phase {id}: {title} -> Done

   ### Specs
     + Spec {id}: {title} -> Complete

   ### Risks
     - Risk {id}: {title} (closed: shipped in PR #{N})

Markers: + = added, - = removed, ~ = modified. Do NOT use narrative descriptions -- show exact changes.

6. Confirmation Gate: "Apply updates to {status_file}? (y/N)"

• If no: present the full updated document as a code block for manual application. Stop here.

7. Write updated file to {status_file} 8. If CHANGELOG gaps were found in Phase A, suggest: "CHANGELOG.md is missing entries for {N} features. Add them? (y/N)"

• On confirmation, add entries under [Unreleased] with appropriate categories

9. Report changes made 10. If {plan_file} exists and updates included phase status changes or new specs completed, suggest: "Phase status changed. Run /roadmap plan sync to update the project plan."

update --incremental

Lightweight post-sprint sync. Skips full codebase scan (Phase B). Uses git history + optional wave context to apply targeted edits. Designed to be fast enough to use after every sprint.

Step 1: Read Wave Context (Optional)

If /core:develop was used for the most recent sprint:

• Glob {specs_dir}/*/wave-context-*.md for completion summaries
• Read the most recent wave context file (by modification date)
• Extract: features built, files modified, tests added, validation results

Fallback: If no wave-context files found, skip this step and rely entirely on git history from Step 2. The incremental update works without /core:develop — wave context just provides richer detail.

Step 2: Phase A — Git History Scan

Same protocol as the full update Phase A: 1. Read .arkhe.yaml for status_file path 2. Get last status doc commit 3. List and categorize commits since 4. Present "What Shipped" summary

Step 3: Targeted Edits (Replaces Phase B)

Read existing {status_file}. Apply ONLY the following changes using the Edit tool (targeted edits, NOT a full rewrite):

• Header: Update date, commit count, branch hash
• Sprint/Iteration Log: Add entry for this sprint (if section exists)
• Module Maturity: Update ONLY for modules touched in Phase A commits (leave untouched modules as-is)
• Phase Dashboard: Mark phases complete if all their specs were delivered
• Spec Pipeline: Mark completed specs, add new specs discovered
• ADR Table: Add new ADR entries from Phase A
• Risk Register: Close risks addressed by shipped features

Do NOT recalculate untouched sections. Do NOT rewrite the entire document. The goal is surgical precision — change only what the git history tells you changed.

Step 4: Diff Preview + Confirmation

Use the same unified diff format as the full update (see § update Phase B step 5):

• Group changes by document section using +/-/~ markers
• "Apply updates to {status_file}? (y/N)"
• If no: present as code block for manual application

Step 5: Write + Plan Sync Suggestion

• Write if confirmed
• If {plan_file} exists and phase status changed, suggest: "Phase status changed. Run /roadmap plan sync to update the project plan."

specs

1. Run context discovery 2. Find all spec files:

• arkhe/specs/*/spec.md
• specs/**/*.md
• Any path configured in context

3. For each spec:

• Extract title and requirements
• Search codebase for implementation evidence
• Classify: Proposed / Ready / In Progress / Complete

4. Produce pipeline table with evidence 5. If {plan_file} exists, cross-reference: show which phase each spec belongs to from the plan's Spec Traceability section. Flag specs that are Complete but not linked to any phase.

plan

plan scaffold

1. Read .arkhe.yaml for plan_file path (default: docs/PROJECT-PLAN.md) 2. Check if {plan_file} exists:

• If yes: warn "Plan document already exists at {plan_file}. Overwrite / sync instead / cancel?"
• If user chooses sync, redirect to plan sync; if cancel, stop

3. Run full context discovery (CONTEXT_DISCOVERY.md Phases 1–7) 4. Gather planning artifacts:

• Read {status_file} — extract: phase table (ID, scope, status, evidence), module maturity, spec pipeline, risk register
• Glob docs/**/roadmap.md — extract: phase lists, backlog themes, known risks
• Glob docs/**/backlog.md — extract: themes with status, priorities, dependencies
• Glob docs/superpowers/plans/*.md — extract: implementation plan titles and dates

5. Scan specs:

• Glob {specs_dir}/*/spec.md (specs_dir from .arkhe.yaml, default: arkhe/specs)
• For each: extract ID (directory name), title (first # heading), status (Status: field or frontmatter)
• Build inventory: {id, title, status}

6. Scan ADRs:

• Glob docs/adr/[0-9]*.md
• For each: extract number (filename), title (first # heading), status (Status section or _Status:_ line)
• Build inventory: {number, title, status}

7. Run hybrid linking algorithm (see § Hybrid Linking Algorithm below) 8. Generate plan document using the PROJECT-PLAN.md template from TEMPLATES.md:

• Fill Timeline from phases found in status doc and roadmaps
• Fill Phase Details with scope, status, linked specs, linked ADRs, evidence
• Fill Backlog from themes with priority and dependencies
• Fill Spec Traceability from inventory + phase mappings
• Fill ADR Traceability from inventory + phase mappings
• Include Sprint/Iteration Log only if sprint data found in existing docs
• Fill References with paths to all source documents read

9. Present proposed plan in chat with confidence markers:

• [AUTO-LINKED] on phase-to-spec and phase-to-ADR mappings detected from git
• [MANUAL] on mappings found explicitly in existing docs
• [UNLINKED] on specs/ADRs that couldn't be mapped to any phase

10. Confirm: "Review the proposed plan. Adjust any linkages? (Type corrections or 'approve')"

• Apply user corrections to linkage mappings

11. Write to {plan_file} 12. Report: "Plan created at {plan_file} with N phases, M specs linked, K ADRs linked, J backlog themes."

plan show

1. Read .arkhe.yaml for plan_file path 2. If {plan_file} doesn't exist:

• "No plan document found at {plan_file}. Run /roadmap plan scaffold to create one."
• Stop

3. Read {plan_file} 4. Parse and present summary view:

   ## Project Plan Summary
   _Source: {plan_file} (last synced: {date from git})_

   ### Timeline
   | Phase | Status | Specs | ADRs |
   |-------|--------|-------|------|
   | {id} | {status} | {count} | {count} |

   ### Progress
   - Phases: {done}/{total} complete ({percent}%)
   - Specs: {linked}/{total} linked to phases
   - ADRs: {linked}/{total} linked to phases
   - Backlog: {count} themes ({in_progress} active)

   ### Active Phase(s)
   {Details for phases with status "In Progress"}

   ### Next Up
   {First "Not Started" phase or top backlog item}

5. Drift detection (both conditions must be true):

• Get last {plan_file} commit: git log -1 --format="%H %ai" -- {plan_file}
• Check age: was the plan last committed more than 7 days ago?
• Count feat:/fix: commits since: git log {hash}..HEAD --oneline --no-merges | grep -cE "^[a-f0-9]+ (feat|fix):"
• If plan is >7 days old AND >= 3 feat/fix commits exist since, append: "⚠️ Plan may be stale: {N} feature/fix commits since last sync ({date}). Run /roadmap plan sync to update."
• Both conditions prevent false positives: active development weeks with recent syncs won't trigger, and quiet weeks with no commits won't trigger.

plan sync

1. Read .arkhe.yaml for plan_file path 2. If {plan_file} doesn't exist: suggest scaffold and stop 3. Phase A: Git History Scan

• Get last plan doc commit: git log -1 --format="%H %ai" -- {plan_file}
• If no previous commit, warn and suggest scaffold instead
• List commits since: git log {last_hash}..HEAD --oneline --no-merges
• Categorize:
• New/modified specs: changes in {specs_dir}/ paths
• New ADRs: new files in docs/adr/
• Phase signals: feat: commits grouped by PR, phase references in messages
• Backlog changes: modifications to docs/**/backlog.md or docs/**/roadmap.md
• Present "What Changed" summary to user

4. Phase B: Auto-detect new links

• For new specs from Phase A: run hybrid linking (git-based phase mapping)
• For new ADRs from Phase A: run hybrid linking
• For phase completion signals: propose status changes ("Not Started" → "In Progress" or "Done")

5. Phase C: Diff and confirm

• Read existing {plan_file}
• Identify user-edited sections (content not matching auto-generated patterns)
• Present proposed changes using the unified diff format defined in § update Phase B step 5 (use +/-/~ markers grouped by section). Example:

     ## Proposed Updates to {plan_file}

     ### Timeline
       ~ Phase 4 status: In Progress -> Done

     ### Spec Traceability
       + Spec 026: {title} -> linked to Phase 4 [AUTO-LINKED]

     ### ADR Traceability
       + ADR 0011: {title} -> linked to Phase 5 [AUTO-LINKED]

     ### Backlog
       ~ Theme 1: In Progress -> Done

• Do NOT use narrative descriptions -- show exact changes with markers.

6. Phase D: Confirm and write

• "Apply updates to {plan_file}? (y/N)"
• If yes: write updated file preserving user-edited content
• If no: present proposed changes as a code block for manual application
• Report changes made

---

Hybrid Linking Algorithm

Maps specs and ADRs to project phases using git history + document content analysis. Used by plan scaffold and plan sync.

Step 1: Collect Phase Definitions

Extract phases from existing planning documents:

• {status_file} phase tables — each row has a phase ID, scope, status, and PR/commit references
• docs/**/roadmap.md — completed phases lists with PR/commit evidence

These define the canonical phase list with date ranges (inferred from PR merge dates or commit dates in evidence).

Step 2: Build Phase Commit Ranges

For each phase that has PR or commit evidence:

# For phases with PR references (e.g., "PRs #19, #21")
git log --oneline --format="%H %ai" -- . | grep "(#19)" | tail -1   # first commit
git log --oneline --format="%H %ai" -- . | grep "(#21)" | head -1   # last commit

# For phases with commit references (e.g., "2fa521a")
git log -1 --format="%ai" 2fa521a   # get date

Build a timeline: {phase_id, start_date, end_date} for each phase.

For phases without explicit evidence, estimate the date range as:

• start = preceding phase's end date (or first project commit if no predecessor)
• end = following phase's start date (or HEAD if no successor)
• If multiple consecutive phases lack evidence, divide the gap equally between them

Step 3: Map Specs to Phases

For each spec in {specs_dir}/*/spec.md:

1. Explicit match (highest confidence): Check if the spec ID is mentioned in a phase's scope/evidence column in the status doc. Mark as [MANUAL]. 2. Git-based match (medium confidence): Find the spec file's creation commit:

   git log --diff-filter=A --format="%H %ai" -- {specs_dir}/{spec_dir}/spec.md

Map the creation date to the phase whose date range contains it. Mark as [AUTO-LINKED]. 3. Content-based match (low confidence): Search spec content for phase references, PR numbers, or feature keywords matching a phase's scope. 4. Unmatched: Mark as [UNLINKED].

Step 4: Map ADRs to Phases

Same cascade as Step 3, but for ADR files in docs/adr/:

1. Explicit match: ADR referenced in status doc's ADR table with phase context → [MANUAL] 2. Git-based match: ADR creation date falls within a phase's date range → [AUTO-LINKED] 3. Content-based match: ADR ## Context references specific features or phases 4. Unmatched → [UNLINKED]

Step 5: Present for Confirmation

Group by confidence level:

## Proposed Linkages

### Confirmed (from existing docs)
- Spec 022 → Phase 3e [MANUAL] — listed in PROJECT-STATUS.md
- ADR-0007 → Phase ASR-1 [MANUAL] — referenced in papia-asr/roadmap.md

### Auto-Detected (from git history)
- Spec 020 → Phase 3d [AUTO-LINKED] — created 2026-03-08, during Phase 3d window
- ADR-0010 → Phase 3b [AUTO-LINKED] — created 2026-03-01, during Phase 3b window

### Unlinked
- Spec 000 → ? [UNLINKED] — created before any defined phase

User can approve all, adjust individual mappings, or skip unlinked items.

Step 6: Persist Mappings

Store confirmed mappings in the plan document's Phase Details sections:

### Phase 3e: Glossary Management + Dictionary Browser
- **Status:** Done
- **Specs:** 022 (Glossary Management UX), 023 (Glossary UX Polish), 024 (Glossary Gap Detection), 025 (Dictionary Browser)
- **ADRs:** _(none)_
- **Evidence:** PRs #32, #33

These explicit listings become the source of truth for future sync operations — already-linked items are not re-analyzed.

Output Templates

Status Dashboard

## Project Status Dashboard
_Generated: {date}_

### Module Overview

| Module | Backend | Frontend | Maturity | Notes |
|--------|---------|----------|----------|-------|

### Working Features
- {feature}: {evidence}

### Planned Features
- {feature}: {document reference}

### Missing / Not Started
- {feature}: {gap reference or "not yet considered"}

### Recommended Next Actions
1. {action with rationale}

Risk Register

## Risk Register
_Generated: {date}_

| # | Risk | Likelihood | Impact | Score | Mitigation | Owner |
|---|------|-----------|--------|-------|------------|-------|
| 1 | {risk} | H/M/L | H/M/L | {LxI} | {action} | {team/person} |

---

Deep Pipeline (--deep)

When $ARGUMENTS contains --deep, execute this multi-agent pipeline -- the most complex in the roadmap plugin. Three Sonnet agents analyze the project simultaneously from PM, Architect, and Roadmap perspectives. A synthesizer then merges findings and surfaces contradictions.

Phase 1: Context Gathering (2 Parallel Haiku Agents)

Launch 2 Haiku agents in parallel:

Agent A -- Config & Documentation: "Run the context discovery protocol from CONTEXT_DISCOVERY.md. Return: project name, configuration (output_dir, context_dir, status_file), personas, project phases, documentation inventory (categorized as: status docs, gap analyses, specs, ADRs, research), and key constraints. Read all documentation files discovered."

Agent B -- Codebase Scan: "Detect tech stack from build files using TECH_STACK_DETECTION.md. Scan the codebase for: module inventory (name, source file count, test file count), directory structure, detected architecture patterns, migration count, TODO/FIXME count, and infrastructure files (Docker, CI/CD, deployment). Return structured results."

Provide each agent with the relevant reference files.

Phase 1.5: Context Compression (Single Haiku Agent)

Before distributing to Phase 2, compress Phase 1 outputs to reduce token duplication. Launch a single Haiku agent receiving both Phase 1 outputs.

Agent prompt: "Compress these two context reports into the structured formats below. Preserve ALL data points but eliminate prose. Target: <1,600 tokens total."

Agent A Compressed Output (target: <800 tokens):

PROJECT: {name}
CONFIG: output_dir={}, context_dir={}, status_file={}, plan_file={}
PERSONAS: {comma-separated list}
PHASES: {id: status} (table, one line per phase)
DOCS: {category: count} (status:N, gaps:N, specs:N, adrs:N, research:N)
CONSTRAINTS: {bullet list of 3-5 key constraints}

Agent B Compressed Output (target: <800 tokens):

STACK: {language, framework, build tool}
MODULES: {name: src_files/test_files/maturity} (table)
ARCH_PATTERN: {detected pattern}
INFRA: {docker:y/n, ci:y/n, deploy:y/n}
TODOS: {count}
MIGRATIONS: {count}

Phase 2 agents receive the compressed output from Phase 1.5, not the raw Phase 1 output. This reduces per-agent context from ~8,000 tokens to ~1,600 tokens.

Phase 2: Parallel Perspective Analysis (3 Parallel Sonnet Agents)

Launch 3 Sonnet agents simultaneously, each with the compressed context from Phase 1.5 but a different analytical lens:

Agent C -- PM Perspective: "You are a product manager analyzing this project. Using the context provided, identify: requirement gaps (features needed but not built), unmet user needs, scope creep (features built that aren't in documented scope), missing user stories for existing features, user-facing risks, and priority recommendations. Focus on user value, not technical concerns. After your analysis, append a Builder Confessions block."

Agent D -- Architect Perspective: "You are a systems architect analyzing this project. Using the context provided, identify: architectural risks (boundary violations, pattern drift, tech debt), module maturity imbalances, missing infrastructure (monitoring, error handling, security), data model concerns, scalability bottlenecks, and dependency risks. Focus on structural health, not user stories. After your analysis, append a Builder Confessions block."

Agent E -- Roadmap Perspective: "You are a project analyst analyzing this project. Using the context provided, assess: phase/milestone completion status, gap closure rate, blocker chains, spec pipeline status, documentation freshness, velocity indicators, and timeline risk. Focus on project trajectory, not architecture or requirements. After your analysis, append a Builder Confessions block."

Each agent must end with a Builder Confessions block:

## Builder Confessions
- **Assumption**: {what was assumed without verification}
- **Uncertainty**: {areas where confidence is low}
- **Shortcut**: {where a deeper analysis was skipped}
- **Missing data**: {what couldn't be found in the codebase}

Phase 3: Cross-Reference Synthesis (Sonnet Agent)

Launch a single Sonnet agent to merge the three perspectives:

Agent prompt: "You are a project health synthesizer. You have three independent analyses of the same project -- from PM, Architect, and Roadmap perspectives. Your job is to:

1. Merge findings into a unified view -- deduplicate, consolidate related findings 2. Surface contradictions -- where perspectives disagree (e.g., PM says 'auth is ready' but Architect says 'boundary violations in auth module') 3. Map cross-perspective dependencies -- PM gap X requires architectural change Y which blocks roadmap milestone Z 4. Build unified risk register -- combine risks from all three perspectives, deduplicate, re-score with cross-perspective context 5. Produce Cross-Perspective Insights -- the unique findings that only emerge from comparing all three perspectives

Output format: A comprehensive Project Health Report using ALL 11 sections from the template in TEMPLATES.md. Do not skip sections -- if a section has no findings, include it with 'No issues found in this area.' Every section MUST be present:

1. Executive Summary 2. Phase/Milestone Status 3. Module Implementation Matrix 4. Decision Traceability 5. Documentation Health 6. Gap Analysis Risk Map 7. Dependency Graph (Mermaid) 8. Blocking Chain 9. Risk Register 10. Prioritized Action Plan 11. Recommendations

Additionally, include a 'Cross-Perspective Insights' section for findings that only emerge when all three perspectives are compared."

Provide the agent with:

• All three Phase 2 analyses (including their Builder Confessions)
• The Project Health Report template from TEMPLATES.md

Note: The synthesis agent MAY read codebase files to verify claims from Phase 2 analyses (called "Synthesis Verification"). Limit to 10 file reads maximum -- this is a verification step, not original research. Note any verification reads in the methodology footer.

Phase 4: Independent Confidence Scoring (Parallel Haiku Agents)

CRITICAL: The Phase 3 synthesis agent MUST NOT score its own findings. Phase 4 uses independent agents with NO access to the Phase 3 synthesis narrative or rationale. This separation prevents self-reinforcing confidence where the agent that produced a finding rates its own work highly.

Option A (Standard, >= 10 findings): Batched Parallel Haiku Agents

Group findings into batches of 3-5. For each batch, launch a Haiku agent with ONLY:

• The finding text (stripped of synthesis commentary)
• The original evidence (file paths, code references)
• The scoring rubric below

Do NOT provide the Phase 3 synthesis narrative, rationale, or cross-perspective analysis.

Agent prompt: "Score each finding 0-100 using ONLY the evidence provided. You have NO knowledge of why these findings were selected or how they relate to each other.

Rubric:

• 90-100: Evidence from multiple independent sources (e.g., PM gap confirmed by Architect code review)
• 70-89: Evidence from one source with corroboration (e.g., file path exists + doc mentions it)
• 50-69: Single-source finding with limited evidence (e.g., only one perspective flagged it)
• Below 50: Speculative or based on assumptions

For each finding, return: score, evidence summary (1 sentence), and action (Include / [NEEDS VALIDATION] / Remove)."

Option B (Lite, < 10 findings): Single Batch Haiku Agent

If total findings < 10, use a single Haiku agent receiving ALL findings as a flat list. Same restriction: NO access to Phase 3 synthesis rationale. Same rubric and output format.

Required Output: Confidence Scoreboard

Both options MUST produce this table:

| # | Finding | Source(s) | Score | Evidence Summary | Action |
|---|---------|-----------|-------|-----------------|--------|
| 1 | {finding} | PM, Arch | 92 | Confirmed by code + docs | Include |
| 2 | {finding} | Roadmap | 78 | Git evidence, no code check | [NEEDS VALIDATION] |
| 3 | {finding} | PM | 55 | Doc-only, not verified | Remove |

Filtering Rules (Non-Negotiable):

• Below 70: REMOVE from final report entirely
• 70-89: Tag with [NEEDS VALIDATION] and include
• 90+: Include as-is

Phase 5: Report Generation

1. Produce the final Project Health Report with all confidence annotations 2. Include the Cross-Perspective Insights section (unique to --deep) 3. Include a Methodology footer noting this was a multi-agent analysis with 3 parallel perspectives 4. Every finding includes its source perspective (PM/Architect/Roadmap) and confidence score 5. Save to {output_dir}/reports/{YYYY-MM-DD}-health-report.md by default. Ask: "Report saved to {path}. Keep it? (Y/n)". If user says no, delete the file. Default is SAVE -- --deep analysis is expensive and its output should persist. 6. Actionable Follow-up — after saving, offer:

   The health report identified {N} risks and {M} action items. Would you like to:
   1. Update {status_file} risk register with new findings
   2. Generate prioritized backlog items from findings
   3. Both
   4. Skip

• Option 1: Read {status_file}, find Risk Register section, append new risks (source: "health report {date}"). Show diff preview using the unified diff format (see § update Phase B step 5). Confirm before writing.
• Option 2: Generate markdown backlog items from findings scored 70+: | # | Item | Source | Priority | Finding |. Output to chat (not auto-saved).
• Option 3: Both in sequence.
• Option 4: Skip.

Deep Pipeline Summary