Roadmap Timeline

---
name: roadmap-timeline
description: >
  Generates a polished, self-contained HTML roadmap or milestone timeline from any project
  data — SharePoint lists, pasted tables, or a verbal description. Use when asked to build
  a project roadmap, product roadmap, migration timeline, release plan, onboarding sequence,
  run-of-show, phase plan, or any visual schedule showing items over time. Interviews the
  user if data is incomplete, constructs a validated JSON document, then renders it into a
  single sandbox-safe HTML file. Chooses between two layouts automatically: horizontal
  roadmap with swimlanes (for phase-range data) or vertical milestone list (for
  point-in-time events). No external dependencies — output runs inside a SharePoint
  sandboxed iframe.
metadata:
  author: zrosenfield
---

# Roadmap Timeline

Generates a complete, self-contained HTML visualization by (1) interviewing the user or parsing their data, (2) constructing and validating a JSON document, then (3) rendering that JSON into HTML using `assets/roadmap-timeline-template.html`. The JSON is the authoritative source of truth; the HTML is fully determined by it.

---

## Step 1: Determine the Data Source

Check what the user has already provided before asking anything:

- **SharePoint lists**: Call `list_items` on the relevant lists. Read all needed columns before proceeding.
- **CSV or table pasted in chat**: Parse all rows. Do not ask for data you already have.
- **Verbal description only**: Proceed to Step 2.

---

## Step 2: Interview the User

If the data or intent is not fully clear, ask these questions in a single message — not one at a time:

1. **Topic**: What is this timeline about? (e.g., "Q3 product launch plan," "cloud migration phases," "new employee onboarding")
2. **Date range**: What is the overall span? (start and end dates for the full view)
3. **Swimlanes / tracks**: Are there parallel workstreams or teams? (e.g., "Engineering," "Product," "Marketing") If yes → roadmap mode. If items are point-in-time events only → milestones mode.
4. **Items**: List the phases or milestones with their dates, owners, and status.
5. **Palette**: Warm paper (cream/terra-cotta), deep ink (dark/gold), clean white (white/green), or slate (gray/blue)? Default to slate for roadmaps, warm-paper for milestone lists.
6. **Footer**: Any footer text (date, project name, audience)?

Confirm your understanding before building the JSON.

---

## Step 3: Choose the Rendering Mode

**Roadmap mode** — use when items have start and end date ranges (duration blocks):
- Items span days, weeks, or months
- Multiple parallel workstreams exist (or a single flat track is still cleaner as roadmap)
- The user mentions "phases," "sprints," "quarters," "swimlanes," or "gantt"

**Milestones mode** — use when items are point-in-time events:
- Items have a single date (no duration)
- The user mentions "milestones," "deliverables," "checkpoints," "onboarding steps," or "run of show"

When data is mixed (some ranges, some points), use roadmap mode and mark point-in-time items as `"milestone": true`.

---

## Step 4: Build and Validate the JSON Document

Construct the JSON object. Full schema:

### `report` object

| Field | Required | Description |
|---|---|---|
| `title` | yes | Report title, shown in header strip |
| `subtitle` | no | Subtitle or context line |
| `date_range_start` | roadmap only | ISO date string, e.g. `"2026-01-01"` |
| `date_range_end` | roadmap only | ISO date string, e.g. `"2026-06-30"` |
| `palette` | yes | `warm-paper`, `deep-ink`, `clean-white`, or `slate` |
| `footer` | no | Footer text |

### `mode` string

`"roadmap"` or `"milestones"`.

### `swimlanes` array (roadmap mode only)

| Field | Required | Description |
|---|---|---|
| `id` | yes | Short identifier, e.g. `"eng"` |
| `label` | yes | Display name, e.g. `"Engineering"` |

### `items` array

| Field | Required | Description |
|---|---|---|
| `id` | yes | Unique short identifier, e.g. `"item-1"` |
| `title` | yes | Display label for the block or card |
| `swimlane_id` | roadmap only | References a swimlane `id` |
| `start` | yes | ISO date string |
| `end` | roadmap mode | ISO date string (omit for pure milestones mode) |
| `status` | yes | `on-track`, `at-risk`, `delayed`, `complete`, or `planned` |
| `milestone` | no | `true` if this is a point-in-time event within a roadmap |
| `owner` | no | Text name of the owner (no Person column — plain text only) |
| `description` | no | Additional detail shown in tooltip (roadmap) or card body (milestones) |
| `dependencies` | no | Array of `id` strings; rendered as a text note, not as arrows |

### Date-to-Percentage Computation (roadmap mode)

The skill pre-computes all layout positions as percentages. No JavaScript is required for positioning — all values are embedded in the HTML as inline styles.

| Value | Formula |
|---|---|
| `total_days` | Days between `date_range_end` and `date_range_start` (inclusive span) |
| `item_left_pct` | `((item_start − date_range_start) / total_days) × 100` |
| `item_width_pct` | `((item_end − item_start) / total_days) × 100` |
| `today_left_pct` | `((today − date_range_start) / total_days) × 100` |

Rules:
- Clamp all results to 0.00–100.00
- Round to 2 decimal places
- Minimum rendered width for any block: 1.50% (so very short items are always visible)
- If `item_end` equals `item_start`, treat the item as a milestone (diamond) regardless of the `milestone` flag

Today's date is known from the system context. If today falls outside the date range, omit the today-line entirely.

### Validation Checklist

Run every check before rendering. Fix any failure before proceeding.

**Document level:**
- [ ] `mode` is `"roadmap"` or `"milestones"`
- [ ] `report.palette` is one of: `warm-paper`, `deep-ink`, `clean-white`, `slate`
- [ ] `items` array has at least one entry
- [ ] Roadmap mode: `report.date_range_start` and `report.date_range_end` are present and parseable as ISO dates
- [ ] Roadmap mode: `date_range_end` is after `date_range_start`
- [ ] Roadmap mode: `swimlanes` array has at least one entry

**Per item:**
- [ ] `id` is unique within the `items` array
- [ ] `title` is present and non-empty
- [ ] `start` is a valid ISO date string
- [ ] Roadmap mode: `end` is present and not before `start`
- [ ] `status` is one of: `on-track`, `at-risk`, `delayed`, `complete`, `planned`
- [ ] Roadmap mode: `swimlane_id` references a valid swimlane `id`
- [ ] `dependencies` entries (if present) each reference a valid item `id`
- [ ] `item_left_pct + item_width_pct` does not exceed 101 (floating-point tolerance)

**Computation check:**
- [ ] All percentage values computed and clamped to 0–100
- [ ] Milestone items have `item_width_pct = 0` (rendered as diamonds, not blocks)
- [ ] Today-line computed only when today is within the date range

---

## Step 5: Render the HTML

Read `assets/roadmap-timeline-template.html`.

For both modes:
1. Replace `{{REPORT_TITLE}}` in `<title>` with a concise page title.
2. Replace `{{PALETTE_CLASS}}` on `<body>` with `palette-` + palette name.
3. Replace `{{HEADER}}` with the `.rpt-header` strip (title, subtitle, date range).
4. Replace `{{CONTENT}}` with the full rendered visualization (roadmap or milestones).
5. Replace `{{FOOTER}}` with footer text (or empty string).
6. Replace `{{INLINE_SCRIPT}}` with any enhancement JS (tooltip hover, palette switcher if needed).

See `references/components.md` for the exact HTML structure of each mode.

### Roadmap Mode Rendering

Generate the month-marker ruler, then one `.swimlane` row per swimlane entry. Within each row:
- Render phase blocks as `<div class="phase-block status-{status}">` with inline `left` and `width` percentage styles.
- Render milestone items as `<div class="milestone-diamond status-{status}">` with inline `left` percentage style.
- Render the today-line as `<div class="today-line">` with inline `left` percentage style (omit if today is out of range).

### Milestones Mode Rendering

Group items by phase (if phases are named in `description` or a `group` field is provided). For each item render a `.milestone-card` with a date badge, status dot, title, owner, and description.

---

## Hard Constraints

- No external URLs, CDN links, or web fonts in the output HTML.
- No `<script src>` tags. All JavaScript must be inline.
- All data values must be pre-rendered into the HTML — the page must be fully correct with JavaScript disabled. JS adds tooltips and animations but must never be required for correctness.
- Do not generate Python, PowerShell, or any other scripts — output is always the HTML file.
- Do not render until the validation checklist passes.
- Owner fields must be plain text — no Person column types.