SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsroadmap-timeline

roadmap-timeline

Office & productivity

View repository

Updated 10-16 15:12

About this skill

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.