Phlogiston/Guide to Phlogiston Reports

This page describes all of the reports in Phlogiston, what data is on the charts, and how to interpret it. It is intended to be used as a reference while looking at live Phlogiston reports. For more information about what Phlogiston is and how to use it, see Phlogiston. For more information about how the data is calculated, see Phlogiston/Forecasting Model.

Each Phlogiston report is generally related to one team or person. Each report covers a scope of work, which is a set of tasks, both open and resolved, that are relevant to that team. Each report is presented twice, by points on the left side and by count on the right side.

Information about the report

Middle Column

Most Recent Data is the date of the newest task or task edit in this scope. This is helpful for ensuring that the Phlogiston report is fresh. Phlogiston accesses Phabricator data around 3 am UTC every day, so it is normal for Phlogiston data to be up to 24 hours behind Phabricator.
Report Date is the date that the report was generated. Reports normally run daily, so if this date is earlier than yesterday then the daily report did not run on time or at all.
These charts include .... The report includes all Phabricator tasks that belong to any of the Phabricator projects listed here. This is the scope of the report.

Right Column

These links provide data for configuring and debugging how tasks are categorized (more information).

Forecast

The Forecast charts provide a single view of all work in the project, resolved and open, by category. In a "perfectly" planned, estimated, tracked, and executed project, all work is correctly categorized, finished work is promptly marked Resolved in Phabricator, the categories are prioritized appropriately, and planned work can be completed in the expected timeframe. This will appear on this chart as:

Completed categories appear as a diagonal line of black diamonds starting in the top left corner. This reflects work completed in the past, categories of work 100% finished, in the order that it was intended to be completed.
Categories of work intended to be finished in the upcoming quarter appear as horizontal bars, reflecting a forecast range from most to least optimistic, and a date reflecting the nominal forecast; part of the bar and the date should fit within the light-shaded rectangle indicating the current quarter.
Note: Planning work to fit within quarters is one planning paradigm; this paradigm can be flipped around into one of planning out a multi-quarter sequence of work with intermediate milestones. Phlogiston is intended to support both paradigms.

The X axis of this chart is time, including some months in the past, the complete current quarter, and some months in the future.

The Y axis of the chart is category of work, including all categories manually defined for this report.

The chart shows all of the following:

Chart Area, Current Quarter, and Today

The current quarter is indicated with a lighter-shaded rectangle. Today's date (the date the report was last run on) is indicated with a vertical blue line.

Size of category

The size of each category is shown via a number at the left of the plot for each category. This is the total number of tasks for the category; the number is shown zoomed in proportion to its log. For point-based charts, a dot is shown instead of a number, with the area of the dot proportional to the total number of points.

Completion Date

If a category has been completed, as defined by having no open tasks and some resolved tasks, the date that happened in shown with a black diamond and label. This may not be accurate if the category has been completed more than once.

If a category has open tasks, this chart shows a forecast of when the category will be complete, based on historical changes to the amount of open tasks and the rate of resolution. The error bar shows the range from optimistic for pessimistic forecast, and the hollow diamond and date label show the nominal forecast. All forecast dates are in terms of weeks relative to the date the chart was last generated.

Current Status

For all incomplete categories, the percentage of tasks (or points) completed is shown in blue along the Now line.

Combined Burnup

This chart shows

This chart shows the total amount of work in scope, with resolved work above the X axis and open work below. Categories are sorted with the top riority closest to the axis. This chart shows the relative size of different categories of work, the ratio of completed to incomplete work for each category, and the changes in this information over time.

An increase above the X axis means that more work has been completed. An increase below the X axis means that more work has been added. If a category grows above the axis while staying relatively flat below the axis, that means that the category is growing in size as fast as it is being completed.

Unzoomed Burnup

The Combined Burnup chart usually excludes several categories of work that are not relevant to current planning: work that was completed in the past, and work that is not actively being considered, such as "freezer" or "unplanned backlog" work. The "Unzoomed" link below each Zoomed Combined Burnup chart shows the same chart including all categories. This is typically useful for comparison to the zoomed chart, to see the relative size and trend in relevant and irrelevant work.

Per-category charts

Phlogiston generates additional charts for each category. These are presented as hidden tabs in the "Per-Category Burnups" section:

Clicking on any Category title shows three types of category-specific chart, each presented for both points and count:

Per-Category Burnup

The Per-Category Burnup shows the total amount of work for a category as a shaded area over time, and the amount of resolved work as a solid black line. The future growth of the backlog is forecast with three gray lines; the dotted gray lines show the pessimistic (top) and optimistic (bottom) forecasts for backlog growth based on past growth and the thicker, dashed gray line shows the nominal forecast. The future amount of completed work is forecast with three black lines, the dotted black lines showing optimistic (top) and pessimistic (bottom) forecasts and the thicker, dashed line the nominal case.

Reading the burnup forecast

The point at which the steepest dotted black line touches the lowest dotted gray line is the earliest date this category is likely to finish, assuming changes to backlog and completion are consistent with past changes.

If the bottom black dotted line doesn't converge with the top dotted gray line, there is a reasonable possibility that the category will never finish. I.e., the pessimistic forecast is never. This is true in the example above.
If the thicker dashed lines are parallel or diverging, it is unlikely that the project will finish because the backlog is growing faster than it is being completed. Unless backlog growth is halted or velocity is increased, the project will not finish. I.e., the nominal forecast is never. Example:

If the top black dotted line doesn't converge with the bottom dotted gray line, there is essentially no chance the project will finish if current trends continue. The optimistic forecast is never. Example:

Note that the per-category charts are slightly more pessimistic than the overall forecast chart, which uses a minimum velocity of 1 point or task per week.

Velocity

This category-specific chart shows the historical trend and retrocast in velocity. The example shown directly correlates to the first example in the Burnup section above.

The black bars show the total velocity for the category; this is the change in completed work week to week. This considers only changes in completed work, not changes in total work; i.e., this does not incorporate information about how much work remains. The colored lines show retrocasts for velocity. The top, green line is the optimistic retrocast, the middle, gray line nominal, and the bottom, red line pessimistic. Pessimistic velocity cannot drop below zero; this limit prevents artifacts in the chart caused by retroactively recategorizing work.

Interpreting the velocity chart

The velocity chart can indicate how reliable the current velocity forecast is. If the velocity retrocasts have been consistent for weeks or months, then the current velocity forecast is more likely. If the velocity retrocasts are very volatile, then the most recent value, which is used for forecasts, should be considered unreliable.

TODO: examples of different common patterns.

Forecast

This category-specific chart shows the historical trend in the forecast. The example shown directly correlates to the first example in the Burnup section above, and to the first example in the Velocity section above.

The overall category forecast is based on the velocity forecast, minus the backlog forecast. The colored lines show the forecast as retrocasts (i.e., the most recent value is the forecast and all previous values are retrocasts). The top, green line is the optimistic retrocast, the middle, gray line nominal, and the bottom, red line pessimistic. Any value above 14 weeks (3 months) is capped at 3 months, in order to keep the chart readable and also to differentiate between very pessimistic retrocasts (shown pegged at 14 weeks) and situations without enough information to make any retrocast (no line shown).

Reading the forecast chart

The forecast chart can indicate the reliability of the current forecast. In a perfect forecast, the forecast should drop by one week for each week that passes. In the example above, the optimistic forecast has been stuck at 2 weeks for a month, indicating that the project may be stuck. The nominal forecast only dropped to less than 14 weeks for one week out of the last quarter, and the pessimistic forecast has never been under 14 weeks. Therefore, although the optimistic forecast is currently 2 weeks, it is unlikely with current trends that the true forecast is less than 14 weeks.

TODO: examples of different common patterns.

Combined Velocity

The combined velocity chart shows the velocity (change in resolved work, by point or count) for all tasks for all Phabricator projects in scope of the report, week by week. If this scope aligns closely to the total work done by a team of people, and that team tracks most of their work in Phabricator, and uses consistent task sizes or consistent pointing, and uses tasks small enough that each team member closes tasks roughly every week or more frequently, and the team composition or availability has not changed dramatically, this chart may accurately show trends in productivity. It may also show how productivity changes with changes in team availability or composition.

Completed Work

This chart shows the total amount of completed work (by points and count) within scope, week by week. Work is sorted and color-coded by category. The highest category is bottom in the chart and darkest green. This chart shows how well the distribution of work actually being completed in Phabricator correlates with the prioritization of the categories; a dark green chart means that a team is working on its top priorities, and a lighter green chart shows that a team is not working in the top-priority categories as much.

Open Tasks

This report shows one row for each task in the scope of the report with status of open.

Date Added refers to the date the task was first made visible in the report, so this could be the date the task was created in Phabricator, or it could be the date that a previously existing task was added to a project that is in scope for this report.

Date Last Changed is the date the project membership, column, or status of the task changed. This seems to catch tasks being merged in as well.

Status Report

This report shows one row for each task that was in scope at the beginning or end of the status reporting period.

Scope

If a task was in scope and 'resolved' or 'open' at the beginning of the reporting period, and is in scope at the end of the reporting period, then it is In-Scope.
If a task was not in scope at the beginning of the reporting period, but its parent (ancestor) task was, then it is Elaborated.
I task was not in scope at the beginning of the reporting period, and neither was its parent task (if any), then it is Screep (scope creep).
Otherwise a task is of scope Unknown.

Status

If a task was in scope at the begininng of the reporting period and is not in scope at the end of the reporting period, it is Cut.
If a task was resolved at the start of the reporting period and is now open, it is Reopened.
If a task was resolved at the end of the reporting period, it is Resolved.
If a task was open at the end of the reporting period, it is Open.