technical-roadmapping

name	technical-roadmapping
description	Use when turning strategy, architecture, or product goals into measurable technical roadmaps with phases, sequencing, dependencies, milestones, risks, staffing assumptions, and implementation-ready slices.
version	1.0.0
author	Hermes Agent
license	MIT
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["roadmap","planning","architecture","milestones","sequencing","delivery"],"related_skills":["principal-ai-architect","agentic-workflow-issue-factory","rag-evaluation-observability"]}}

Technical Roadmapping

Overview

Use this skill to convert ambiguous strategy into an executable technical roadmap. The goal is not to make a beautiful timeline. The goal is to make the next sequence of engineering work obvious, measurable, de-risked, and easy to hand to implementation agents or engineering teams.

A good technical roadmap connects business outcomes to architecture decisions, implementation slices, dependencies, risks, staffing assumptions, validation checkpoints, rollout gates, and measurable evidence. It should help a team decide what to build now, what to defer, what must be true before the next phase starts, and how to know the roadmap is working.

For AI/RAG/agent systems, roadmaps must explicitly include quality measurement, production observability, cost visibility, and safe rollout. Do not roadmap a sequence of features without also roadmapping the evidence and operational controls needed to trust them.

When to Use

Use when asked to:

• create a technical roadmap from a strategy, architecture, product goal, or backlog
• sequence AI/RAG/agent work across phases, milestones, or quarters
• turn a vague initiative into implementation-ready epics or GitHub issues
• prioritize technical work by business value, risk reduction, or dependency order
• define MVP, beta, GA, hardening, and scale phases
• identify prerequisites, blockers, risks, and staffing assumptions
• align engineering work with measurable outcomes and decision gates
• create a roadmap that coding agents or human teams can execute

Do not use for:

• a single isolated code fix
• a pure task list with no sequencing or tradeoffs
• a product roadmap that does not require technical architecture or delivery planning
• speculative brainstorming where the user explicitly does not want implementation guidance

Roadmap Principles

1. Outcome first. Start with the business/user outcome and success metric, not the feature list.
2. Evidence before scale. Build measurement, evals, and traces before relying on advanced behavior in production.
3. Dependencies before dates. A phase is ready when its prerequisites are true, not because a calendar says so.
4. Thin vertical slices. Prefer end-to-end slices that prove a workflow over horizontal platform work with no user-visible validation.
5. Risk burn-down. Sequence high-uncertainty architecture, data, security, and integration risks early.
6. Reversible decisions early; hard-to-reverse decisions deliberately. Use ADRs for strategy decisions that constrain later work.
7. Cost and operations are roadmap items. Unit economics, latency, monitoring, and support workflows are not afterthoughts.
8. Implementation-ready output. Each roadmap phase should decompose into issues or epics with acceptance criteria and verification commands.

Roadmap Inputs to Gather

Before producing a roadmap, identify or ask for:

Input	Why it matters
Target users/workflows	Prevents roadmap from becoming platform work detached from impact
Business outcomes	Defines priority and success metrics
Current system state	Avoids inventing prerequisites or duplicating existing work
Hard deadlines	Separates date constraints from dependency constraints
Team capacity	Makes sequencing realistic
Technical constraints	Surfaces architecture and integration risks
Data/source readiness	Critical for RAG, analytics, evals, and automation
Security/compliance constraints	Prevents late-stage rework
Cost/latency budgets	Shapes model, retrieval, infra, and rollout choices
Existing issues/ADRs/docs	Lets the roadmap reuse durable decisions

If these inputs are missing, proceed with explicit assumptions and mark where the plan needs confirmation.

Standard Roadmap Shape

Use this structure unless the user requests another format.

# Technical Roadmap: <initiative>

## Executive Summary
- Goal:
- Why now:
- Target users/workflows:
- Success metrics:
- Time horizon:

## Current State
- What exists:
- What is missing:
- Known constraints:
- Open questions:

## Guiding Architecture Decisions
- Decision 1:
- Decision 2:
- ADRs needed:

## Phase 0: Discovery and Baseline
Objective:
Key work:
Acceptance criteria:
Exit criteria:
Risks burned down:

## Phase 1: MVP / Thin Vertical Slice
Objective:
Key work:
Acceptance criteria:
Exit criteria:
Risks burned down:

## Phase 2: Production Hardening
Objective:
Key work:
Acceptance criteria:
Exit criteria:
Risks burned down:

## Phase 3: Scale and Optimization
Objective:
Key work:
Acceptance criteria:
Exit criteria:
Risks burned down:

## Cross-Cutting Workstreams
- Evaluation:
- Observability:
- Security/compliance:
- Data/platform:
- Developer experience:
- Documentation:

## Dependency Map
- Blockers:
- Prerequisites:
- Parallelizable work:

## Milestones and Decision Gates
| Milestone | Evidence required | Decision |
|---|---|---|

## Risks and Mitigations
| Risk | Impact | Mitigation | Owner |
|---|---|---|---|

## Issue/Epic Breakdown
| Epic/Issue | Phase | Outcome | Acceptance criteria |
|---|---|---|---|

## Non-Goals
- ...

## Rollout and Rollback
- Rollout:
- Rollback:
- Operational readiness:

Phase Design

Each phase should have:

• Objective: the outcome the phase proves
• Why this phase now: why it precedes later work
• Key work: implementation slices, not vague themes
• Acceptance criteria: observable/testable completion conditions
• Exit criteria: evidence needed to start the next phase
• Risks burned down: uncertainty removed by the phase
• Non-goals: work intentionally deferred

Avoid phases named only by time period, such as “Q1” or “Month 2.” Use outcome names:

• “Make quality measurable”
• “Ship the first production workflow”
• “Harden for real users”
• “Optimize cost and scale”
• “Expand workflow coverage”

AI/RAG Roadmap Pattern

For AI systems, use this sequencing by default unless project context says otherwise.

Phase 0: Baseline and Decision Readiness

Goal: make the current state measurable enough to choose the right work.

Include:

• inventory source systems and data readiness
• define target workflows and success metrics
• create or expand golden datasets
• document existing architecture and constraints
• identify required ADRs
• establish baseline cost, latency, quality, and failure modes

Exit criteria:

• baseline metrics exist
• top risks are named
• first production slice is selected
• implementation issues are scoped

Phase 1: Thin Production Slice

Goal: ship the smallest end-to-end workflow that proves user value.

Include:

• ingestion/retrieval/generation path for one workflow
• typed tool or API boundaries when agents are involved
• basic trace capture for prompts, retrievals, tools, model, tokens, cost, and latency
• no-answer or escalation behavior
• smoke evals and regression checks

Exit criteria:

• workflow completes for target users
• quality meets minimum threshold
• traces explain failures
• rollback path is documented

Phase 2: Quality and Reliability Hardening

Goal: make the system trusted enough for broader use.

Include:

• richer eval slices by query/workflow type
• retrieval strategy improvements only where metrics justify them
• reranking/model routing policies with cost and latency gates
• error handling, retries, idempotency, and human escalation paths
• production dashboards and alert thresholds

Exit criteria:

• regression gates are enforced
• failure modes are observable
• cost and latency are within budget
• on-call/support workflows are clear

Phase 3: Expansion and Unit Economics

Goal: grow workflow coverage without losing quality or cost control.

Include:

• additional workflows or namespaces
• quality/cost routing policies
• automated feedback-to-eval loops
• production sampling for online evaluation
• budget alerts and anomaly detection
• deprecation/retirement criteria for unused strategies

Exit criteria:

• roadmap priorities are driven by adoption, completion rate, quality, cost, and support burden
• new workflows can be added with reusable patterns
• expensive model/retrieval paths have measured lift

Prioritization Rubric

Score roadmap items using a lightweight weighted rubric.

Dimension	High score means
Business impact	Directly improves a valuable workflow or measurable outcome
User reach	Affects many users or a critical user segment
Risk reduction	Burns down technical, data, security, or delivery uncertainty
Dependency leverage	Unblocks multiple later workstreams
Evidence quality	Can be validated with clear metrics/evals/traces
Effort	Small enough to ship and verify quickly
Reversibility	Can be rolled back or changed without major migration
Unit economics	Improves or protects cost/latency per successful outcome

Prefer items that combine high business impact, high risk reduction, and high dependency leverage. Do not prioritize solely by ease if the roadmap is trying to reduce strategic uncertainty.

Dependency Mapping

Separate work into:

• Foundational prerequisites: must exist before other work can start
• Risk probes: small experiments that decide between paths
• Vertical slices: end-to-end user workflow increments
• Hardening work: reliability, evals, observability, security, rollout controls
• Scale work: cost, latency, capacity, and operational efficiency
• Polish work: UX and documentation improvements that depend on proven workflows

A good dependency map makes parallel work explicit:

Baseline evals ─┬─> Retrieval strategy decision ─┬─> Production slice
                │                                └─> Namespace cleanup
                └─> Observability schema ─────────> Dashboard + alerts

Roadmap Output Formats

Choose the smallest useful output.

Executive roadmap

Use for leadership alignment. Emphasize outcomes, milestones, risks, and decision gates. Keep implementation detail light.

Engineering roadmap

Use for teams and coding agents. Include phases, dependencies, files/modules likely to change, issues, acceptance criteria, tests, and verification commands.

Issue-ready roadmap

Use when the user wants work created in GitHub. Each roadmap item should become one issue or epic with:

• problem statement
• architecture context
• scope and non-goals
• likely files/modules
• acceptance criteria
• verification commands
• rollout/rollback notes

ADR-backed roadmap

Use when sequencing depends on hard-to-reverse decisions. Identify ADRs before implementation issues.

Common Pitfalls

1. Feature list pretending to be a roadmap. A roadmap must show sequencing, dependencies, evidence, and tradeoffs.
2. Dates without assumptions. If using dates, state capacity and dependency assumptions.
3. Skipping measurement. For AI systems, evals and observability must arrive before broad rollout.
4. Too much platform before proof. Build the thinnest end-to-end slice before broad abstractions unless compliance or scale requires otherwise.
5. No exit criteria. Without phase gates, teams advance on hope instead of evidence.
6. No non-goals. Roadmaps invite scope creep unless deferred work is explicit.
7. Ignoring migration and rollback. Production roadmaps need safe rollout and recovery paths.
8. Overloading one phase. If a phase has more than 5-7 major work items, split it or define sub-milestones.
9. No issue handoff. A roadmap that cannot become issues leaves implementation agents to rediscover the plan.

Verification Checklist

• Roadmap starts with business/user outcomes and success metrics
• Current state and assumptions are explicit
• Phases are outcome-based, not only date-based
• Each phase has acceptance criteria and exit criteria
• Dependencies and parallelizable work are called out
• Risks have mitigations or discovery tasks
• AI/RAG work includes eval, observability, cost, and rollout controls
• Non-goals and deferred work are explicit
• Roadmap items can become scoped issues or epics
• Rollout and rollback are addressed for production behavior changes