Build Goal Milestone Progress Chart Data Points

Provide the starting value, latest value, target, and the milestone percentages you want to display. The result reports true progress, a chart-safe clamped position, the milestones already reached, the next milestone when one remains, and ordered points for drawing a progress line. It works equally well for goals that rise toward a target and goals that must fall, such as reducing defects, expenses, or response time.

Define the goal with an explicit starting point

A useful progress percentage needs three values, not merely a current value and a target. The start value establishes zero percent, the target establishes one hundred percent, and the current value shows where the goal stands now. This distinction matters whenever work begins from a nonzero baseline. For example, increasing a score from 20 to 100 is halfway complete at 60, not sixty percent complete. Submit those values as numbers and provide at least one milestone percentage between zero and one hundred. Milestones may arrive in any order, and repeated percentages are consolidated so the chart receives a clean ascending series. The target must differ from the start because a zero-length range has no meaningful progress ratio. When they are equal, the capability returns a typed input error instead of producing infinity, an arbitrary percentage, or chart data that only appears valid. Up to one hundred supplied milestone items are accepted in a request, which keeps the output and execution bounded while covering detailed plans comfortably.

Interpret increasing and decreasing goals consistently

The same formula handles both directions: progress is the distance traveled from the start divided by the full distance from start to target. If the target is larger than the start, the result identifies an increasing goal. If the target is smaller, it identifies a decreasing goal, so moving from 100 incidents toward a target of 20 incidents counts as forward progress rather than a negative result. The returned progress percentage is intentionally not clamped. A value below zero reveals regression beyond the starting position, while a value above one hundred records overachievement beyond the target. For presentation, chart_progress_percentage and the current point's chart_percentage are separately limited to the zero-to-one-hundred plotting range. Milestone reach decisions use the true, unclamped progress. Each normalized milestone includes its percentage, the corresponding value along the start-to-target range, and a reached flag. The output also includes the number and percentages of reached milestones, plus the next milestone when unfinished milestones remain. Once every requested milestone is reached, that optional next-milestone field is omitted rather than returned as null.

Feed the returned points into charts and status views

The chart_points array provides an ordered start point, one point for each normalized milestone, and a target point. Every record carries a kind, percentage, value, and reached state, making it suitable for line charts, progress tracks, timeline markers, and accessible textual summaries. The separate current_point preserves the actual current value and raw progress while also supplying the clamped chart coordinate. This separation lets a dashboard plot a marker safely at the edge when a goal is behind or ahead, while still displaying the honest figure in a label or tooltip. Use reached_milestone_percentages for badges, celebrations, or audit events, and use next_milestone to explain what comes next without searching the milestone array again. The calculation is deterministic and uses no network, time, stored state, or random values, so identical inputs produce identical output across repeated jobs. You can run it free in the browser for interactive planning, or call the API for $0.002 per request when generating reports, updating dashboards, or processing goal records in an automated workflow.