---
name: project_timeline_planning
description: Build project timelines and Gantt style plans with task breakdown, dependency mapping, critical path calculation, milestone setting, and buffer placement. Use when planning a project schedule, estimating a finish date, building a Gantt chart, checking what a slip does to a deadline, or replanning after dates move.
---

# Project Timeline Planning

## Purpose
Turn a list of work into a timeline that can be checked, not just looked at. The plan names every task, its owner, its duration, and what it depends on. From that logic the skill computes early and late dates, float, and the critical path, then places milestones and buffers in plain sight. When dates slip, the same logic shows how much of the slip reaches the end date and what options exist, with their cost and risk stated before anyone picks one.

## Workflow
1. Frame the plan before listing tasks. Write down the goal in one sentence, the start date, any hard deadline and what drives it, and the calendar. State whether durations are elapsed days or working days, and list holidays and blackout dates. Pick a status date for this version of the plan. A timeline without a calendar is a guess with bars on it.
2. Break the work down from deliverables. Start from the deliverables the project must produce, split each one into work packages, then split packages into tasks. Stop splitting when each task has one owner and a done test that another person could check. Split any task longer than about two weeks before estimating it. Check coverage at the end: every deliverable is covered, and no task exists that serves no deliverable. Use the template in `references/plan-template.md`.
3. Estimate each task with a basis. Record a single duration for settled, repeated work. For uncertain work record three numbers: optimistic, most likely, and pessimistic. The script converts them with the PERT formula E = (O + 4M + P) / 6. Write one line per task saying where the estimate came from: past actuals, a count times a rate, a vendor quote, or a guess. Label guesses as guesses. Prefer records from the last similar jobs over fresh memory.
4. Map dependencies, and only real ones. For each task ask two questions: what must be true before this can start, and what must be true before this can finish. Default to finish-to-start. Use start-to-start only for real overlap, finish-to-finish only when two streams must land together, and check any start-to-finish link twice because it is often a modelling error. Add a lag only for a real wait such as a review window or cure time, and write down why it exists. Every lead or lag without a reason gets deleted. Full type definitions are in `references/methods.md`.
5. Run the pass and read the critical path. Save the plan as JSON in the format shown in `references/example-plan.json` and run `python3 scripts/timeline.py <plan.json>`. The script runs a forward pass for early start and early finish, a backward pass for late start and late finish, and reports float per task plus the critical path. Read the output in this order: total duration, critical tasks, near critical tasks with 1 to 3 days of float, then everything else. Fix logic errors first. The script rejects cycles, unknown predecessors, negative durations, and milestones with nonzero duration, and each rejection means the plan logic is wrong, not that the tool is fussy.
6. Set milestones as outcomes. Place one milestone per phase or major deliverable, plus project start and project finish. Each milestone has zero duration, an acceptance test, and a named acceptor. Name it as an outcome, for example "API accepted by partner", not as work in progress. If a date has no acceptance test, call it a target date in the plan, not a milestone.
7. Place buffers where they protect the promise. Do not pad individual tasks. Keep task dates at the most likely or PERT expected value, then add a project buffer between the end of the critical chain and the promised date. Add a feeding buffer where a non critical chain joins the critical chain. Add a resource warning, not extra time, ahead of critical tasks that need a scarce person or resource. When three point estimates exist for every critical task, the script reports one standard deviation of the critical chain spread as a buffer sizing aid. Round it up and check it against the risk list. When no spread data exists, size the buffer from the listed risks and the days each one costs, and write the reasoning in the plan. The sizing rules are in `references/methods.md`.
8. Check resources before calling the plan real. List who does each task and add up the load per person per week. A plan that needs one person in two places at once has a hidden dependency, and that hidden link is part of the true critical chain. Level the plan by moving tasks inside their float first. If leveling moves the end date, say so and show the new date. Do not publish a timeline that only works with double booked people.
9. Draw the Gantt view last. Run `python3 scripts/timeline.py <plan.json> --format mermaid --start <YYYY-MM-DD>` for a Mermaid Gantt block, or use the text Gantt in the default output for a quick check. Order rows by deliverable or by dependency flow, mark critical tasks, and show milestones as points. The chart is a communication view of the computed plan. Never edit dates in the chart by hand. Change the task data and rerun the script.
10. Baseline it, then status against the baseline. Once the plan is approved, freeze that version as the baseline and keep it unchanged. Each status cycle, record actual starts, actual finishes, and a fresh forecast for work in progress. Rerun the script on the forecast plan. Report three dates side by side: baseline finish, current forecast finish, and promised finish, plus remaining project buffer. A forecast that quietly replaces the baseline hides the variance the team needs to see.
11. Handle a slip the day it is known. When a critical task slips, work the options in order and price each one: use remaining float, spend project buffer, resequence or overlap where the overlap is safe, crash the cheapest critical days first by adding resources, then renegotiate scope or date as an explicit decision. Fast tracking adds risk and rework exposure. Crashing adds cost and often stops helping quickly. Compressing a task with float buys nothing until the float is gone. After any move, rerun the pass, because the critical path often changes. Full rules are in `references/methods.md`.

## Worked example
The file `references/example-plan.json` holds a partner page launch with seven rows. Requirements take 3 days, design takes 4 days after requirements, the frontend build takes 6 days and the API build takes 5 days, both after design, end to end testing takes 3 days after both builds, deploy takes 1 day, and a zero duration launch milestone follows deploy. Running the script gives a 17 day duration. The critical tasks are A, B, C, E, F, and M1. Task D, the API build, has 1 day of float: it can slip 1 day for free, and a 2 day slip makes it critical and moves the launch date unless buffer is spent or the plan changes. Those numbers come from a verified run of the script on that file.

## Output Contract
Deliver a timeline pack, not just a chart:
- The task table: ID, task, owner, duration or O / M / P estimates with basis, predecessors with type and lag, and a done test per task
- The computed schedule: duration, early and late dates per task, float per task, and the critical path named as a list of task IDs
- The milestone table: milestone, planned date, acceptance test, acceptor
- The buffer statement: project buffer size and how it was sized, each feeding buffer, each resource warning, and the top schedule risks tied to task IDs
- The Gantt view: Mermaid block or text Gantt generated from the computed plan, with critical tasks marked
- The slip log and change log from the template, current as of the status date
- One plain sentence the reader can repeat: the forecast finish date, the promised date, and how much buffer sits between them

## Operating Rules
- Compute dates from logic, never from hope. If a date in the output cannot be traced to durations and dependencies, it does not ship.
- Keep the baseline frozen. Forecasts move, baselines change only through an approved change that gets a change log entry.
- Report float honestly. A task with float is not late when it moves inside its float, and a critical task is late the first day it slips. Use the right word for each case.
- Never hide a pad inside a task and a buffer at the end at the same time. Pick pooled buffers, state them, and track how much of them has been spent against work completed.
- A date that has moved three times triggers a cause review of the estimate, the dependencies, and the resource assumption. Do not issue a fourth date from the same broken inputs.
- Keep milestones at zero duration with an acceptance test. Work belongs in tasks, events belong in milestones.
- Say what is unknown. If durations came from guesses, if the calendar ignores a known holiday, or if a dependency rests on an outside party with no confirmed date, list it in the pack under risks instead of letting the chart imply certainty the plan does not have.
- Verify before reporting done. A timeline is done when the script runs clean on the final plan file and the output numbers match the numbers quoted in the pack.