Phlogiston/Guide to Phlogiston Reports

For more information about how forecast data is calculated, see Phlogiston/Forecasting Model.

Background/Context
[What is this page about?]

Index

 * Full list of possible categories. This report shows all of the tasks Phlogiston sees for this scope, grouped by the project tag, projectcolumn, and parent Category tags.  It is intended to be used in helping create categorization rules for scopes.
 * Rules for recategorizing tasks This is a link to the github file driving categorization for this scope.
 * Recently closed tasks. This is a link to a list of all tasks resolved in the last two weeks, along with the category that Phlogiston has determined for the task following the recategorization rule.
 * All open tasks, sorted by category. This is a list of all open tasks in this scope, grouped by category.
 * Histogram of stories by points. This is a histogram of the point value of all resolved stories, grouped by Phabricator Priority field. Each row is a different Phabricator priority, from 10 = lowest to 90 = Untriaged and 100 = Unbreak Now!, plus an All Priorities row at the bottom.  It is intended to help determine if a default value of points for unpointed stories is useful.  The current default point value for unpointed stories is also shown; this is taken from the configuration file for this scope.

Report metadata

 * "Most Recent Data" is the date of the most recently changed data for any task in this scope. Data is dumped around 3 am UTC every day, so changes after the dump will not be reflected.
 * "Report Date" is the date that the report was generated. Reports should run daily, so this may be helpful for determining if fresh report generation is stalled.
 * "These charts include ..." is the complete list of Phabricator project names used to generate this report. The report should include all tasks with these project tags.

Forecast
The Forecast charts show all defined categories for a scope of reporting, and for each category show the total amount of work, date completed or forecast completion, and fraction complete as of now.



Categories
All of the categories defined for a scope are listed in descending order by priority. There are two versions of this chart, zoomed and unzoomed; the zoomed version excludes any categories that are hidden (for example, a Product Owner may hide categories that were completed in the past) and the unzoomed version shows all categories.

Chart Area
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 zero open tasks and more than zero resolved tasks, the date that happened in shown with a black diamond and label. If the category is completed, re-opened, and re-completed, this is [not sure, probably the first time that was true?]. 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 story 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.