technical-roadmaps

Original source / Raw SKILL.md

---
name: "technical-roadmaps"
description: "Turn an engineering strategy into a written Technical Roadmap Pack (Rumelt-style strategy: Diagnosis/Guiding Policy/Coherent Actions, roadmap table, initiative briefs, and alignment cadence). Use for technical roadmap, tech roadmap, engineering roadmap, architecture roadmap."
---

# Technical Roadmaps

## Scope

**Covers**
- Turning “technical work” (architecture, platform, reliability, tech debt) into a **written strategy + roadmap** that stakeholders can critique and improve.
- Applying Richard Rumelt’s strategy frame (**Diagnosis → Guiding policy → Coherent actions**) to engineering planning.
- Producing a roadmap that is **executable** (owners, milestones, dependencies, risks, metrics), not a vague wishlist.
- Aligning a technical roadmap with product/business constraints (quarters, launches, compliance/security, capacity).

**When to use**
- “Create a technical/engineering/architecture roadmap for the next 2–4 quarters.”
- “We need a written technical strategy and a roadmap we can review with leadership.”
- “We have many tech-debt/platform initiatives; turn them into a prioritized plan with dependencies and milestones.”
- “Our tech roadmap keeps being misunderstood—write it down so we can debug alignment.”

**When NOT to use**
- The problem/outcome is unclear (use `problem-definition` first).
- You need to choose *which* product bets matter most (use `prioritizing-roadmap` or `ai-product-strategy`).
- You only need delivery dates, milestone tracking, and RAG governance (use `managing-timelines`).
- You need a deep platform strategy / ecosystem design (use `platform-strategy`).

## Inputs

**Minimum required**
- **Audience + decision:** who this roadmap is for (Eng leadership, Execs, Product) and what decisions it must enable.
- **Time horizon + format:** e.g., 6 months / 12 months; Now-Next-Later vs quarterly.
- **Current-state diagnosis inputs:** top pain points, reliability/latency/cost signals, incident themes, scaling constraints, key architectural bottlenecks.
- **Constraints:** capacity assumptions, compliance/security requirements, platform constraints, non-negotiables.
- **Candidate initiatives:** known platform/architecture/tech-debt items (even a rough list).

**Missing-info strategy**
- Ask up to 5 questions from [references/INTAKE.md](references/INTAKE.md).
- If answers aren’t available, proceed with explicit assumptions and list them under **Open questions**.

## Outputs (deliverables)

Produce a **Technical Roadmap Pack** in Markdown (in-chat; or as files if the user requests):

1) **Technical Strategy (Rumelt)**: Diagnosis → Guiding policy → Coherent actions (template: [references/TEMPLATES.md](references/TEMPLATES.md))
2) **Roadmap table** (Now/Next/Later or quarters) with owners, dependencies, milestones, confidence, and metrics
3) **Initiative briefs** for the top 3–6 roadmap items (1 page each)
4) **Dependency + risk register** (top cross-team deps, key risks, mitigations)
5) **Alignment + governance plan** (review cadence, update rules, decision owners, comms template)
6) **Risks / Open questions / Next steps** (always included)

Expanded guidance: [references/WORKFLOW.md](references/WORKFLOW.md)

## Workflow (7 steps)

### 1) Intake + audience alignment
- **Inputs:** User request; [references/INTAKE.md](references/INTAKE.md).
- **Actions:** Confirm the audience, horizon, and roadmap “shape” (quarters vs Now/Next/Later). Identify the decision the roadmap must enable (funding, sequencing, headcount, trade-offs).
- **Outputs:** Intake summary + explicit assumptions + open questions list (if any).
- **Checks:** You can state: “This roadmap is for <audience> to decide <decision> over <horizon> using <format>.”

### 2) Write the strategy (Rumelt: Diagnosis → Guiding policy → Coherent actions)
- **Inputs:** Current-state signals; constraints; product/business context.
- **Actions:** Draft a written strategy using the Rumelt structure. Keep it concrete: name the constraints and trade-offs.
- **Outputs:** Technical Strategy section using [references/TEMPLATES.md](references/TEMPLATES.md).
- **Checks:** A reader can answer: “What’s the problem?”, “What’s our approach?”, “What actions are we taking (and not taking)?”

### 3) Build the initiative inventory (candidate “coherent actions”)
- **Inputs:** Candidate initiative list; strategy; incidents/metrics; architecture notes.
- **Actions:** Normalize initiatives into a table (theme, outcome, why now, dependencies, effort, risk). Merge duplicates; split overly broad items.
- **Outputs:** Initiative inventory (draft roadmap backlog).
- **Checks:** Each item has an outcome + a “why now” tied back to the Diagnosis/Guiding policy.

### 4) Prioritize + sequence (make trade-offs explicit)
- **Inputs:** Inventory; constraints; dependencies; capacity assumptions.
- **Actions:** Prioritize based on: (a) alignment to strategy, (b) risk reduction, (c) enabling product work, (d) cost/effort, (e) dependency criticality. Sequence via dependencies and “first unlocks.”
- **Outputs:** Ranked list + sequencing rationale + explicit non-goals/cut list.
- **Checks:** You can justify the top 3 items in 1–2 sentences each, including what you deprioritized.

### 5) Convert into a roadmap (quarters or Now/Next/Later) with execution detail
- **Inputs:** Ranked list; sequencing; calendar constraints.
- **Actions:** Create the roadmap table with owners, milestones, dependencies, confidence, and success metrics. Add “decision gates” where uncertainty is high.
- **Outputs:** Roadmap table + milestone highlights.
- **Checks:** A team could start execution without guessing owners/dependencies; high-uncertainty items have a gate (spike/RFC/prototype).

### 6) Draft initiative briefs + alignment plan
- **Inputs:** Roadmap; top items; stakeholder map.
- **Actions:** Write 1-page briefs for the top 3–6 items and a comms/governance plan (review cadence, update rules, decision owners).
- **Outputs:** Initiative briefs + alignment/governance section (templates in [references/TEMPLATES.md](references/TEMPLATES.md)).
- **Checks:** Stakeholders know when/how the roadmap will change and what inputs trigger a refresh.

### 7) Quality gate + finalize
- **Inputs:** Full draft pack.
- **Actions:** Run [references/CHECKLISTS.md](references/CHECKLISTS.md) and score with [references/RUBRIC.md](references/RUBRIC.md). Ensure **Risks / Open questions / Next steps** are present with owners and dates where possible.
- **Outputs:** Final Technical Roadmap Pack.
- **Checks:** The pack is “debuggable”: written, coherent, measurable, and reviewable.

## Quality gate (required)
- Use [references/CHECKLISTS.md](references/CHECKLISTS.md) and [references/RUBRIC.md](references/RUBRIC.md).
- Always include: **Risks**, **Open questions**, **Next steps**.

## Examples

**Example 1 (platform scaling):** “We’re seeing reliability issues and slow delivery. Create a 2-quarter technical roadmap and strategy we can review with leadership.”  
Expected: a Rumelt-structured strategy plus a sequenced roadmap with owners, dependencies, milestones, and metrics.

**Example 2 (architecture modernization):** “We need an architecture roadmap to migrate off a legacy monolith while still shipping product features.”  
Expected: explicit trade-offs, dependency-aware sequencing, decision gates, and a governance cadence to keep alignment.

**Boundary example:** “Write a detailed project plan with dates for every task for the next 6 months.”  
Response: use `managing-timelines` for delivery planning; this skill is for strategy → roadmap (themes/initiatives/milestones), not task-level scheduling.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/INTAKE.md

```markdown
# Intake questions (Technical Roadmaps)

Ask up to 5 at a time. If answers aren’t available, proceed with explicit assumptions and record them under **Open questions**.

## Fast minimum (answer these first)
1) What’s the **audience** and what **decision** must this roadmap enable (funding, sequencing, headcount, trade-offs)?
2) What’s the **time horizon** (e.g., 2 quarters / 12 months) and preferred format (quarters vs Now/Next/Later)?
3) What are the top 3 **pain signals** today (incidents, latency, cost, dev velocity, quality, compliance)?
4) What are the **constraints** (capacity, deadlines, compliance/security, platform constraints, non-negotiables)?
5) What are the **candidate initiatives** (paste a list) and any known **dependencies**?

## Context + strategy
- What’s the product/company strategy that constrains technical choices (e.g., “enterprise readiness”, “international expansion”)?
- What’s explicitly **in scope** vs **out of scope**?
- What trade-off are we willing to make (speed vs cost vs reliability vs platform evolution)?

## Current-state diagnosis
- Architecture snapshot (high level): key systems, hotspots, known bottlenecks.
- Operational reality: on-call load, incident themes, SLO/SLA gaps, security findings.
- Delivery reality: cycle time, PR throughput, flaky tests, build times, deployment frequency.

## Execution constraints
- Team shape and ownership boundaries (who owns what today)?
- Any fixed dates/windows (launches, migrations, contract renewals)?
- External dependencies (vendors, other teams, data availability)?

## Output preferences
- Preferred roadmap style: Now/Next/Later, quarters, or “themes + milestones”.
- Do you want initiative briefs for the top 3, top 5, or top 6?
- Any required headings/format for leadership (doc style, 1-pager, deck outline)?


```

### references/TEMPLATES.md

```markdown
# Templates (Technical Roadmaps)

Use these templates to produce the deliverables in `skills/technical-roadmaps/SKILL.md`.

## 1) Technical Strategy (Rumelt) — template

# Technical Strategy: <Title>

## Context
- Audience:
- Horizon:
- Decision this enables:

## Diagnosis (what’s true / constraints)
- Current-state summary (2–5 bullets):
- Evidence (metrics/incidents/examples):
- Key constraints (capacity, deadlines, compliance/security):

## Guiding policy (how we will approach it)
- Policy 1:
- Policy 2:
- Policy 3:
- (Optional) Policy 4–5:

## Coherent actions (what we will do)
| Theme | Action / initiative | Outcome | Why now | Dependencies | Owner | Confidence |
|---|---|---|---|---|---|---|
|  |  |  |  |  |  |  |

## Explicit trade-offs (what we will NOT do)
- Non-goal 1:
- Non-goal 2:

## Success metrics
- Metric 1 (baseline → target):
- Metric 2 (baseline → target):

## Risks + mitigations
- Risk:
  - Mitigation:

## Open questions
- Q:
  - Owner:
  - By when:

## 2) Roadmap table — template

| Timeframe (Q / Now-Next-Later) | Theme | Initiative | Owner | Milestones | Dependencies | Effort | Confidence | Success metric |
|---|---|---|---|---|---|---|---|---|
|  |  |  |  |  |  |  |  |  |

## 3) Initiative brief (1 page) — template

# Initiative: <Name>

## Problem / opportunity
- What’s broken / constrained?
- Evidence:

## Proposed approach
- What we’ll do:
- What we won’t do:

## Why now
- Trigger (scale, incidents, cost, product bet, compliance):

## Scope
- In:
- Out:

## Dependencies
- Teams/systems:
- External:

## Milestones (high level)
1) <Gate / RFC / spike>:
2) <Build>:
3) <Migration / rollout>:
4) <Measure + harden>:

## Risks + mitigations
- Risk:
  - Mitigation:

## Success metrics
- Metric (baseline → target):

## 4) Dependency + risk register — template

| Item | Type (dependency/risk) | Impact | Likelihood | Mitigation | Owner | Date |
|---|---|---|---|---|---|---|
|  |  |  |  |  |  |  |

## 5) Governance + comms plan — template

## Cadence
- Weekly (team):
- Monthly (cross-functional):
- Quarterly (leadership refresh):

## Update rules
- What triggers a roadmap change:
- Who approves changes:
- How changes are communicated:

## Status update template (copy/paste)
- **This period:** (wins, shipped milestones)
- **Next:** (upcoming milestones)
- **Risks/blocks:** (needs help/decisions)
- **Changes to roadmap:** (what moved and why)


```

### references/WORKFLOW.md

```markdown
# Workflow notes (Technical Roadmaps)

This file expands the workflow in `skills/technical-roadmaps/SKILL.md` with practical guidance and patterns.

## Core principle: write it down so you can debug it
If the technical roadmap keeps getting misunderstood, the fix is often to produce a **single written strategy + roadmap** that can be reviewed, critiqued, and iterated.

## Rumelt strategy in practice (engineering version)

### Diagnosis (what’s true right now?)
Good inputs:
- Reliability signals (incidents, SLO breaches, pager load)
- Performance/cost signals (p95 latency, infra spend trends)
- Delivery signals (cycle time, lead time, deploy frequency, build times)
- Architecture constraints (coupling, scaling limits, data model bottlenecks)

Output characteristics:
- Specific, evidence-backed, and framed as constraints.
- Names the “why now” (what changed, what broke, what’s coming).

### Guiding policy (how will we approach it?)
Examples (choose 3–5, keep them crisp):
- “Prefer platform primitives over bespoke team solutions.”
- “Reduce coupling before attempting re-architecture.”
- “Stabilize reliability (SLOs) before scaling traffic.”
- “Security-by-default for all new services.”

### Coherent actions (what will we do?)
Engineering roadmap items should be:
- Outcome-oriented (what improves, by how much)
- Dependency-aware (what unblocks what)
- Sized enough to execute (or explicitly gated by an RFC/spike)

## Roadmap patterns that work well for engineering

### Time horizons
- 0–6 weeks: can be more specific (owners, milestones)
- 1–2 quarters: should be sequenced with dependencies, but avoid task-level detail
- 3–4 quarters: should be theme-heavy with major milestones and clear confidence levels

### Use “decision gates” to handle uncertainty
For any large or ambiguous item, avoid pretending you know the full solution up front. Add a gate as an explicit milestone:
- **Gate types:** RFC, architecture review, spike, prototype, load test, vendor evaluation.
- **Gate output:** a decision plus a smaller, clearer next milestone (or a kill decision).
- **Gate check:** “What did we learn that changes scope, sequence, or resourcing?”

Pattern:
- Gate → commit to near-term learning output
- After gate → re-sequence the roadmap using the new constraints

## Aligning technical roadmaps with product roadmaps
Technical roadmaps land best when they connect to product outcomes without pretending technical work is the product roadmap.

Practical moves:
- Add a **“product bet enabled”** column for each initiative where applicable.
- Describe technical work in terms of **risk reduction**, **time-to-ship**, **reliability**, **cost**, or **capability unlocks**.
- Separate “must do” (risk/compliance) from “should do” (improvement) from “could do” (nice-to-have).

## Common anti-patterns (and fixes)
- **Anti-pattern:** Roadmap is a list of activities.  
  **Fix:** Rewrite each item as an outcome with a success metric.
- **Anti-pattern:** No trade-offs; everything is “top priority”.  
  **Fix:** Add non-goals/cut list and explicitly name the constraints.
- **Anti-pattern:** No owners/dependencies, so execution stalls.  
  **Fix:** Assign owners and call out cross-team dependencies up front.
- **Anti-pattern:** Over-specific long-range dates.  
  **Fix:** Use themes + major milestones and label confidence; add decision gates.

## Recommended governance
- Treat the roadmap as a **living document** with a simple version history.
- Review cadence:
  - Weekly team check: are gates/milestones on track?
  - Monthly cross-functional review: dependency and trade-off review
  - Quarterly refresh: re-run Diagnosis and re-sequence as needed

```

### references/CHECKLISTS.md

```markdown
# Checklists (Technical Roadmaps)

Use these before finalizing the pack.

## Strategy (Rumelt) checklist
- [ ] Diagnosis is specific (not generic) and backed by evidence (metrics/incidents/examples).
- [ ] Guiding policy is 3–5 crisp principles that constrain choices.
- [ ] Coherent actions clearly derive from Diagnosis + Guiding policy.
- [ ] Trade-offs/non-goals are explicit (what we will *not* do).
- [ ] Assumptions and uncertainties are called out with decision gates (RFC/spike).

## Roadmap checklist
- [ ] Roadmap items are outcome-oriented (not “do work”).
- [ ] Owners are named (team/role is acceptable if names aren’t known).
- [ ] Dependencies are explicit and sequenced (unlock order is clear).
- [ ] Milestones exist for near-term items; longer-horizon items have themes + major milestones.
- [ ] Confidence is stated for each major item (high/med/low).
- [ ] Success metrics exist (baseline → target where possible).

## Alignment + governance checklist
- [ ] Audience and decision are explicit (what approval is needed).
- [ ] Update cadence is defined (monthly/quarterly refresh) and realistic.
- [ ] Change-control rules exist (“trade, don’t add” if capacity is fixed).
- [ ] Comms template exists and uses consistent language.

## Final pack checklist
- [ ] Includes: Dependency + risk register.
- [ ] Includes: Risks / Open questions / Next steps.
- [ ] Uses templates consistently (no missing sections).
- [ ] Written so stakeholders can critique it async (debuggable).


```

### references/RUBRIC.md

```markdown
# Rubric (Technical Roadmaps)

Score each dimension 1–5. A strong pack is **≥4** on most dimensions and **no 1s**.

## 1) Diagnosis quality
1: Vague (“we need to improve reliability”) with no evidence.  
3: Some evidence, but missing key constraints or “why now”.  
5: Specific constraints with clear evidence and urgency.

## 2) Guiding policy coherence
1: A list of slogans; doesn’t constrain choices.  
3: Some principles, but too many or inconsistent.  
5: 3–5 crisp principles that clearly drive decisions.

## 3) Actionability of coherent actions
1: Wishlist; no owners, deps, or milestones.  
3: Some execution detail, but sequencing unclear.  
5: Executable plan with owners, deps, milestones, and decision gates.

## 4) Alignment and stakeholder usefulness
1: Written for the wrong audience; no decision ask.  
3: Audience is implied; decisions unclear.  
5: Audience + decision are explicit; stakeholders can approve/critique async.

## 5) Feasibility and trade-offs
1: Ignores capacity/constraints; no trade-offs.  
3: Mentions constraints, but doesn’t change plan.  
5: Plan reflects constraints; non-goals/cut list is explicit.

## 6) Measurability and risk management
1: No success metrics; risks missing.  
3: Some metrics/risks, but shallow or unowned.  
5: Metrics (baseline → target) + risk register with owners and mitigations.

## Ship / no-ship guidance
- **Ship:** No 1s, and at least four dimensions are 4–5.
- **Revise:** Any 1, or more than two dimensions at 3 or below.


```