Delivery Timeline

Delivery Timeline

Generates a delivery timeline from a completed milestones.yaml. Asks for delivery parameters (production deploy date, QA rounds, days per QA session), updates milestones with day estimates, and produces timeline.yaml with two sections: a relative-day timeline and a real-date workback schedule anchored to the production deploy date.

Prerequisites

• Completed {base_directory}/implementation/milestones.yaml (output from /implementation-planner)

Usage

/delivery-timeline [base-directory]

If no directory is provided, auto-detect by looking for implementation/milestones.yaml in the current directory.

If not found, prompt the user: "Where are your planning artifacts located?"

Wait for the user to provide a path before proceeding. Store as base_directory.

Process

Step 1: Determine Base Directory and Load Milestones

If no directory parameter was provided, check if implementation/milestones.yaml exists in the current directory.

• If found, use current directory as base_directory
• If not found, prompt: "Where are your planning artifacts located?" and wait for user response

Once base_directory is determined:

Read {base_directory}/implementation/milestones.yaml and extract each milestone's id, name, dependencies, and estimated_duration.

Also read meta.ordering_strategy if present. Store as ordering_strategy. If absent, default to foundation-first.

The ordering_strategy value drives structural differences in Steps 6 and 7:

• multi-pr: PR/review/merge cycles are inserted after each milestone in the development timeline; the fixed pre-QA PR block in Step 7 is omitted.
• All other strategies (single-feature-branch, value-first, risk-first, vertical-slice, foundation-first): standard single-PR post-development flow (no change to current behavior).

Step 2: Gather Delivery Parameters

Ask the user the following three questions. You may present them together in a single message:

1. Production deploy date — "What is your desired production deploy date? (YYYY-MM-DD)"
2. QA rounds — "How many rounds of QA are required?"
3. QA days per round — "How many days should be allotted for each QA session?"

If the provided production deploy date falls on a Saturday or Sunday, warn the user:

"Note: [date] falls on a weekend. Would you like to use [previous Friday] or [next Monday] instead?"

Wait for the user to confirm or correct before proceeding. Store the confirmed values as:

• production_deploy_date (ISO 8601 date string)
• qa_rounds (integer ≥ 1)
• qa_days_per_round (integer ≥ 1)

Step 3: Convert Durations to Days

Convert each milestone's estimated_duration string to a whole number of business days using this table:

For durations expressed in days already (e.g., 5 days), use the number as-is.

Step 4: Update milestones.yaml

Add estimated_days to every milestone entry in {base_directory}/implementation/milestones.yaml. Do not modify any other fields.

Example — before:

- id: m0
  name: Foundation & Project Setup
  estimated_duration: 1 week

After:

- id: m0
  name: Foundation & Project Setup
  estimated_duration: 1 week
  estimated_days: 5

Step 5: Determine Project Size

Calculate total_development_days by summing estimated_days across all milestones.

Large project if either condition is true:

• total_development_days > 30
• Number of milestones > 5

Large projects receive two rounds of QA feedback by default, but this is overridden by the user-provided qa_rounds value from Step 2. is_large_project is still recorded in the summary for informational purposes.

Step 6: Build the Development Timeline

Starting at Day 0, assign a completion_day to each milestone in dependency order. Each milestone's start_day is the business day after its last dependency completes (or 0 if no dependencies). Its completion_day is start_day + estimated_days.

Day calculation formula:

• No dependencies: start_day = 0
• Has dependencies: start_day = max(dependency.completion_day) + 1 (next business day after dependencies complete)
• completion_day = start_day + estimated_days

For sequential milestone chains (each depends on the previous):

m0: start_day=0, completion_day=0+estimated_days(m0)=5
m1: start_day=5+1=6, completion_day=6+estimated_days(m1)=16
m2: start_day=16+1=17, completion_day=17+estimated_days(m2)=27
...

For parallel milestones (sharing same dependency), they all start the day after that dependency completes. They share the same start_day but their completion_day is calculated independently based on their individual estimated_days.

Standard strategies (all except multi-pr)

last_milestone_day = the highest completion_day among all milestones.

multi-pr strategy

After each milestone, insert four PR cycle phases before the next milestone may start. Use the milestone id as a prefix (e.g. for m0: m0-pr-creation, m0-pr-review, m0-review-feedback, m0-merge).

The PR cycle adds 4 business days of overhead after each milestone. The next milestone's start_day = completion_day of its predecessor's merge phase + 1 (starts the day after merge completes).

For sequential milestones under multi-pr:

m0: start_day=0, completion_day=0+estimated_days(m0)=5
m0-pr-creation: start_day=5, completion_day=5          # 0 days, opens same day
m0-pr-review: start_day=5, completion_day=5+2=7
m0-review-feedback: start_day=7, completion_day=7+2=9
m0-merge: start_day=9, completion_day=9                # 0 days, merges same day

m1: start_day=9+1=10, completion_day=10+estimated_days(m1)=20
# ... repeat for each milestone

For parallel milestones under multi-pr, each branch gets its own PR cycle. A milestone depending on multiple parallel predecessors starts the day after the latest merge completion_day among them (max(merge.completion_day) + 1).

last_milestone_day = the highest completion_day of the final [milestone-id]-merge phase across all milestones.

Step 7: Append Post-Development Timeline

Add delivery phase items starting from last_milestone_day. Each item has a start_day (day the work begins) and completion_day (day the work is done). Items with estimated_days: 0 complete on the same day they start.

Use qa_rounds and qa_days_per_round from Step 2 to drive the QA section.

Fixed Pre-QA Phases

Standard strategies (all except multi-pr): Include the full PR/merge/deployment block below. This represents the single end-of-project PR.

multi-pr strategy: Omit post-pr-creation, post-pr-review, post-review-feedback, and post-merge — those cycles already occurred per-milestone in Step 6. Start directly with post-deployment.

QA Phases (repeated for each round 1..qa_rounds)

For each round R from 1 to qa_rounds, generate the following phases using qa_days_per_round as the QA Deadline duration. Use round-specific ids (e.g. post-qa-r1-deadline, post-qa-r2-deadline). When qa_rounds == 1, ids may omit the round suffix (e.g. post-qa-deadline).

Fixed Post-QA Phase (all projects)

Step 8: Build Workback Schedule

Map every timeline item (milestones + delivery phases) to a real calendar date by working backwards from production_deploy_date.

Anchor point: production_deploy_date = the real date for completion_day of post-signoff (the final day of the timeline, total_delivery_days).

Business day arithmetic: When counting backwards, skip Saturdays and Sundays. One business day back from a Monday is the previous Friday.

For each timeline item:

• completion_date = production_deploy_date minus (total_delivery_days − item.completion_day) business days
• start_date = production_deploy_date minus (total_delivery_days − item.start_day) business days

project_start_date = production_deploy_date minus total_delivery_days business days (Day 0).

Include all items from timeline in the same order. Also append a final entry for production-deploy with date: production_deploy_date.

Step 9: Generate timeline.yaml

Write {base_directory}/delivery/timeline.yaml.

Create directory if it doesn't exist:

mkdir -p {base_directory}/delivery

Output Format

Updated milestones.yaml

The estimated_days field is added to each milestone entry. All other content is preserved exactly.

timeline.yaml Schema

The output document includes: version, project, generated, milestones_file, summary (total days, project size, QA rounds, delivery model), timeline (milestones + delivery phases with start_day/completion_day/estimated_days), and workback (production deploy date, project start date, real calendar schedule).

See references/output-spec.md for the complete document specification with all fields, phase types, and workback calculation rules.

See references/example.yaml for a full example.

Example Output

See references/example.yaml for a complete sample timeline.

Gap Analysis

After generating timeline.yaml, perform a gap analysis and report findings inline.

Checks

Coverage

• Every milestone in milestones.yaml appears in timeline.yaml
• All milestone dependencies are respected (no milestone completes before its dependencies)
• estimated_days was added to every milestone in milestones.yaml

Duration Reasonableness

• No single milestone has estimated_days: 0 (flag for review)
• No milestone exceeds 30 days without a note explaining the scope
• Duration conversions match the table in Step 2

Project Size Classification

• is_large_project correctly reflects total_development_days > 30 OR milestone_count > 5
• QA rounds in timeline.yaml match user-provided qa_rounds
• QA Deadline phases each use qa_days_per_round days

Delivery Model

• ordering_strategy was read from milestones.yaml (or defaulted to foundation-first)
• delivery_model in timeline.yaml summary matches the resolved strategy
• For multi-pr: each milestone has a corresponding [milestone-id]-pr-creation / pr-review / review-feedback / merge block in the timeline; post-pr-creation through post-merge are absent from post-development phases
• For all other strategies: post-pr-creation through post-merge are present in post-development phases; no per-milestone PR blocks exist

Timeline Integrity

• completion_day values are strictly increasing for sequential milestones
• Parallel milestones have correct independent completion_day values
• Post-development phases follow immediately after last_milestone_day
• total_delivery_days = completion_day of post-signoff

Workback Integrity

• project_start_date = production_deploy_date minus total_delivery_days business days
• production-deploy entry date matches production_deploy_date
• All completion_date values are on weekdays (Mon–Fri)
• workback.schedule contains all entries from timeline in the same order
• post-signoff completion_date = production_deploy_date

Gap Analysis Report

After generating files, output a brief inline report:

## Timeline Gap Analysis

**Project:** [name]
**Delivery Model:** [ordering_strategy]
**Total Development Days:** [n] ([n] weeks)
**Total Delivery Days:** [n] (including post-dev phases)
**Project Size:** [Small / Large] ([reason if large])
**QA Rounds:** [n] × [qa_days_per_round] days each
**Production Deploy:** [YYYY-MM-DD]
**Project Start:** [YYYY-MM-DD]

**Checks:**
✓ All [n] milestones included
✓ Dependency order respected
✓ Duration conversions applied
[✓ / ✗] estimated_days added to milestones.yaml
[✓ / ✗] QA rounds match user-specified value ([n] rounds)
[✓ / ✗] All workback dates land on weekdays
[✓ / ✗] post-signoff completion_date = production_deploy_date

**Issues:** [none / list issues]

**Recommendations:** [none / list recommendations]

If issues are found, ask:

"I found the following timeline issues:

• [Issue 1]
• [Issue 2]

Would you like to:

1. Fix these issues now
2. Proceed with the timeline as-is
3. Manually adjust the estimates before generating"