Skip to content

Create High-Level Timeline

ContributorsPaul Atkins

Purpose

Generate a high-level timeline with milestones from a phased remediation plan. Produces a visual Gantt chart (Mermaid) and milestone summary suitable for stakeholder communication, SoW inclusion, or project kickoff decks.

Prerequisites

  1. Remediation plan — phased work items with effort estimates and dependency chains
  2. External dependencies (optional) — list of decisions/approvals that gate phases
  3. SoW (optional) — if milestones are already defined, align to them

Instructions

Step 1 — Map effort to duration

Convert T-shirt effort estimates to indicative durations. Use this default mapping (adjust based on team size and context):

Effort Duration (1 engineer) Duration (2 engineers, parallel where possible)
Trivial 0.5 days 0.5 days
Small 1–2 days 1 day
Medium 3–5 days 2–3 days
Large 5–10 days 3–5 days

State the team size assumption explicitly.

Step 2 — Identify the critical path

Walk the dependency graph from the remediation plan:

  1. List all dependency chains from first item to last
  2. Sum effort along each chain
  3. The longest chain is the critical path
  4. Note which external dependencies fall on the critical path — these are the highest-risk delays

Step 3 — Define milestones

Create one milestone per phase boundary. Each milestone has:

Field Description
Name Short label (e.g. "M1: DEV Deployment Operational")
Phase Which phase it concludes
Key deliverables 2–4 bullet points of what's delivered
Exit criteria Measurable condition for the milestone to be considered complete
External dependencies resolved Which dependencies from Section 5 of the SoW must be resolved before this milestone can begin

Add intermediate milestones within large phases if they span more than 4 weeks.

Step 4 — Build the Mermaid Gantt chart

Use Mermaid gantt syntax:

gantt
    title [System] Production Remediation Timeline
    dateFormat YYYY-MM-DD
    axisFormat %d %b

    section Phase 0 — Preconditions
    Source code access        :milestone, m0a, YYYY-MM-DD, 0d
    Azure DevOps migration    :p0_2, after m0a, 3d
    Legacy diagnostic         :p0_3, after p0_2, 5d
    Git hygiene               :p0_4, after p0_2, 2d
    M0: Preconditions Complete :milestone, m0, after p0_3, 0d

    section Phase 1 — Deployment
    ...

Rules for the Gantt chart: - Use after references to express dependencies (not absolute dates unless a start date is known) - Mark milestones with :milestone - Mark external dependency gates with :crit (critical) - Group by phase using section - Aggregate small items into logical groups (e.g. "Pipeline stages" instead of listing Test, Check, Build separately) - Keep to 15–25 items maximum for readability

If the start date is unknown, use a placeholder date and note "Dates are illustrative — timeline starts when Phase 0 dependency D1 is resolved."

Step 5 — Create the milestone summary table

| Milestone | Target | Key Deliverables | Dependencies Resolved |
|-----------|--------|------------------|-----------------------|
| M0 | Week 2 | Source in Azure DevOps; diagnostic report | D1, D2 |
| M1 | Week 6 | Pipeline green; DEV deployment | D3, D6, D7, D10 |
| ...

Use relative timing (Week N) if absolute dates aren't known.

Step 6 — Add risk-adjusted range

Provide two timeline views:

Scenario Assumption Total Duration
Optimistic All dependencies resolved on time; no surprises in diagnostic; 2 engineers X weeks
Expected 1–2 dependency delays of ~1 week each; minor diagnostic findings Y weeks
Pessimistic Major dependency delay (source access); significant code divergence; 1 engineer Z weeks

Step 7 — Note what's NOT in the timeline

Explicitly state: - Whether the timeline includes elapsed time waiting for external dependencies or only active engineering time - Whether Phase 3 items are parallelisable with Phase 2 - Any items that can be pulled forward if dependencies resolve early

Output

A single .md file named [system]-timeline.md containing: 1. Milestone summary table 2. Mermaid Gantt chart 3. Critical path narrative (2–3 sentences) 4. Risk-adjusted range table 5. Assumptions and caveats

Alternatively, the timeline can be a section within an existing SoW.

Troubleshooting

Error: Gantt chart is too detailed and unreadable. Cause: Every work item was included instead of logical groups. Solution: Aggregate related items. E.g. "Authentication integration" instead of listing app registration, Easy Auth config, backend authoriser, frontend AuthProvider, nginx update separately.

Error: Timeline doesn't account for dependency wait times. Cause: External dependencies were treated as zero-duration. Solution: Add explicit wait blocks with :crit style, or note that elapsed time will be longer than active engineering time.

Error: Phases overlap but the chart shows them sequentially. Cause: Some Phase 3 items can start during Phase 2 (e.g. docs lifecycle doesn't depend on PostgreSQL). Solution: Review the dependency graph. Items whose dependencies are met earlier can be pulled forward. Show them in the correct timeline position, not grouped by phase.