Chapter Roadmap (1 of 2)

• 12.1 What decision needs a measure?
  • A measurement contract, and a synthetic issue history.
• 12.2 Estimates revisited: what they can and cannot tell us
• 12.3 Velocity and its limits
  • Velocity versus throughput; conditional forecasts.
• 12.4 Burn-down and burn-up: reading the lines
  • Reconciling scope additions and removals.
• 12.5 How long do things take? Lead time, cycle time, throughput, WIP
  • And real repository evidence.

Chapter Roadmap (2 of 2)

• 12.6 Technical health, and how metrics get misused
• 12.7 A changed requirement, and what it touches
  • CR-12: visiting-researcher reservations.
• 12.8 Checking an AI’s explanation, not its confidence check the explanation, not its confidence.
• 12.9 Measurement habits that mislead
• 12.10 Try it yourself: measure, interpret and prepare the change
• 12.11 Questions to think with, and a transfer challenge
• What to take away, and what comes next
  • Chapter 13: implement CR-12 and deliver it.

Learning Outcomes (1 of 2)

After this chapter, you should be able to:

1. Define a measurement boundary and calculate lead time, cycle time, throughput, work in progress and work-item age.
2. Distinguish velocity from item throughput and explain why neither ranks individual contribution.
3. Reconcile burn-down and burn-up observations with additions, removals and completed work.

Learning Outcomes (2 of 2)

4. Use a small body of evidence to frame a conditional forecast and identify missing information.
5. Evaluate a technical-health or debt claim without confusing activity with quality or causation.
6. Prepare acceptance examples, an impact analysis and an ordered response to a changed requirement.

Where This Chapter Fits and Where You Start

• Supports LO5 and LO6. Required reading: the descriptor’s Martin (2002) planning review; recommended: selected chapters of Accelerate.
• The required practical activity includes repository-metrics analysis.
• The requirement change is introduced in this chapter, implemented and verified in Chapter 13 (Milestone 4), and evaluated during handover in Chapter 14.
• The module leader releases your team’s assessed variant. The book’s worked change does not replace it.
• Version: Chapter 11’s verified Java project. This chapter adds an isolated metrics exercise and planning records. It does not implement the feature.

How to Use This Chapter

• Core: 12.1 to 12.7, with the measurement contract and the worked change specification.
• Minimum lab: reproduce the synthetic calculations; inspect actual repository evidence; challenge the AI summary; preserve the pre-change version with a change-impact note.
• Working knowledge: the supplied Java calculator and the repository extraction method.
• Optional: richer visualisation, larger cohorts, probabilistic forecasting (after obtaining suitable data).

Opening Problem: The Line Went Up

• The lending team has completed several changes, yet the remaining-work line has risen.
• One item spent two days waiting for a directory decision. Another was removed from scope.
• A team member says more commits prove the team is faster. An AI summary says the blocked item proves the architecture is poor.
• The history is synthetic teaching data, not recovered history and not evidence about a real student team.

And a New Request

• Visiting researchers should be able to reserve selected equipment after sponsor approval, with a shorter loan limit.
• Can the team finish it next iteration? Which existing rules will it affect? What evidence would justify starting immediately rather than resolving an uncertainty first?
• A metric cannot make these decisions. It can make part of the situation visible, if its unit, boundary and limitations are clear.

Begin With a Question That Could Change an Action

• “Collect more metrics” is a weak objective.
• “Should we finish the two open items before pulling the sponsor-approval story?” points to a decision.
• We need: which items remain, how long they have been open, whether they are blocked, how comparable they are with past work. A commit count cannot answer all that.

State the Contract for Each Measure

• The question, population, unit, time window, intended response.
• Keep a note of the source and extraction date.
• If a number cannot influence a decision or test an assumption, consider whether collecting it is useful.
• For a small student project, a clear table often teaches more than a dashboard of unexplained indicators.
• Compare definitions before comparing numbers: other teams may choose different boundaries.

The Measurement Contract (1 of 3)

The Measurement Contract (2 of 3)

The Measurement Contract (3 of 3)

• The half-open interval includes completions at the starting instant and excludes the ending instant: adjacent windows cannot count the same completion twice.
• A snapshot is different: a completion exactly at its timestamp has already left work in progress.
• These are reporting choices, not new reservation-period rules.

The Complete Issue History (1 of 2)

The Complete Issue History (2 of 2)

• Every date is October 2026 at 00:00 UTC. A dash means the event has not occurred, not a duration of zero.

Reading the History as a Timeline

Context and Caution

• B is recorded as blocked from 03 to 05 October while a mapping question is answered: supplied as synthetic context, not inferred from inactivity in Git.
• G and H are scope additions; F is a removal.
• The labels describe an imagined iteration; they do not assert that earlier files were created on these dates.

Data and Interpretation Are Different

• A sound observation: “B spent four elapsed days between Started and Done.”
• A possible explanation: “waiting for the mapping decision contributed to B’s delay.”
• A stronger claim such as “the directory adapter caused all delays” needs evidence this table does not contain.

What an Estimate Is

• A planning judgement made with incomplete knowledge.
• Useful when it exposes uncertainty or supports a choice between smaller and larger slices.
• Misleading when treated as a measured physical property of the work.
• The points are a local relative scale: not hours, not an exchange rate between teams.

Points Are Not Days

• B’s five points and C’s two express the team’s relative judgement before delivery.
• B taking four days does not establish that one point equals 0.8 days: the duration includes waiting, and another item has different risks.
• Do not rewrite old estimates after seeing durations to make history look consistent. If a team genuinely revises one, preserve the earlier value and record the event.

Split by Useful Behaviour

• For the approval change, start with a concrete example: a recognised visitor requests CAM1 for two days with matching approval.
• Compare that slice with the failure case where the approval register is unavailable: shared code, a distinct delivery risk.
• Splitting by useful behaviour makes uncertainty easier to discuss than “write classes, write tests, write documentation”.

When Estimates Differ

• Ask what each person assumed. One may expect an existing approval file; another a new sponsor-facing website.
• The solution is to clarify scope, not average incompatible assumptions. The worked change uses a small local approval register and excludes an approval-management interface.
• Capacity matters: a week with a midterm or an absent teammate is not interchangeable with an earlier week. Record the constraint without turning people into point-producing units.
• A time-bounded investigation should have an output: a sample approval record and a checked parsing/failure contract.

Velocity and Throughput

• Velocity (for a team using points): the sum of estimates of items completed within a defined iteration. A, B, C, D, G: 3 + 5 + 2 + 3 + 3 = 16 points.
• Throughput counts completed items: five items in this ten-day interval.
• Sixteen points and five items describe the same completions with different units. Calling 16 “throughput” would confuse the comparison.

What Does Not Count

• E and H contribute no completed points yet. Calling E “80% done” does not add four points.
• F contributes nothing: removing an optional item can be a sensible scope decision without becoming delivery.
• Discussing progress on E is fine, but is not a reason to redefine Done.

Velocity Has Limits

• It can help one team inspect its own planning history when the estimation scale, Definition of Done and work mix are consistent enough.
• It cannot fairly rank teams that estimate differently.
• It cannot reveal an individual’s contribution: reviewing a colleague’s difficult change may raise team completion with no story or commit under the reviewer’s name.
• A burn chart is not a substitute for inspecting actual results.

Make Forecasts Conditional

• Two remaining items totalling seven points: 7 / 16 = 0.4375 iterations.
• That arithmetic does not establish a delivery date. It assumes comparable work, capacity, dependencies, scope and completion behaviour.
• One observed iteration says little about variation; unfinished work may be exactly the work with unresolved risk.

A Defensible Planning Statement

We have completed five items in ten elapsed days in this synthetic example. E and H remain open. We will inspect their blockers and size the approval slice before committing to a date.

• If later comparable history supports two to three items per five-day window, two remaining items might fit one window under unchanged conditions: a scenario, not a calibrated probability or guarantee.
• Preserve forecasts as dated predictions and compare them with outcomes. Do not fit a confident percentile to a tiny classroom sample.

Definitions

• A burn-down shows remaining work.
• A burn-up shows completed work, normally alongside the current scope total.
• With points fixed and removed items never Done: remaining = current scope − completed.
• Initial scope 20 points. Adding G and H: 25. Removing F: 23. At the end 16 complete, 7 remain.

The Daily Snapshots (1 of 2)

The Daily Snapshots (2 of 2)

The Burn-Up

Read the Events, Not Only the Line

• Day 04: the remaining line rises from 17 to 18 despite C’s two-point completion: three points arrived as G.
• Day 08: it falls by five, but only three came from D’s completion; two came from removing F.
• Without the scope events, both changes are easy to misread.
• The scope history must stay visible if we want to explain the line.

Ideal Lines Are Not Evidence

• An ideal diagonal burn-down is a reference for a fixed initial scope. It is not evidence that real work should finish in equal daily increments.
• Review, integration and acceptance produce uneven completions.
• Do not move Done timestamps to make a curve attractive.
• Ask whether the team can explain the change and whether the remaining work still serves the goal.

Definitions for This History

• Lead time: Accepted to Done.
• Cycle time: Started to Done.
• The difference is the recorded wait before starting.
• Neither measures hands-on effort.
• The calculations use the completion cohort, not every row in the backlog.

The Finished Items

The Arithmetic

• Lead: 23 / 5 = 4.6 elapsed days. Cycle: 14 / 5 = 2.8.
• Median cycle: sort 1, 2, 3, 4, 4 and take the middle: three days.
• Wait: 9 / 5 = 1.8, consistent with 4.6 − 2.8.
• B’s two blocked days stay inside its four-day cycle. Subtracting them answers a different question (mean 2.4) and still would not establish active coding time.

Open Items Have Ages

• At the final snapshot E and H are started but unfinished: WIP is two.
• Their ages are four and three days. They have no completed cycle time yet.
• Excluding them from the mean is correct for a completed-item statistic, but forgetting them in the interpretation creates a misleadingly favourable account.
• Report the completed cohort alongside open-item age.

Throughput by Window

• [01, 06): two items, A and C.
• [06, 11): three, B, D and G.
• B belongs only to the second window, because it completes exactly at that window’s starting instant.
• These are five-day windows, not claims about official Sprints.
• Whole interval: five items in ten days, or 0.5 per elapsed day.

Equal Throughput, Different Delay

• Two five-day periods, each finishing two items.
• In one, both started one day before completion; in the other, both started seven days before and were carried in.
• Throughput is two in both; completed cycle times are one and seven days.
• Counting completions does not reveal how long recipients waited.

Use Actual Repository Events Carefully

• The lab supplements the example data with real issue or PR history, using Repository Metrics Method RM-12 v1.0, exact timestamps and the supplied Java 17 calculator.
• In the PR route: Started = PR opened; Done = merged; unit = a PR. Call the result PR open-to-merge elapsed time.
• It is not issue cycle time, developer effort, deployment lead time or time since coding began.

Choose the Population Before the Result

• For throughput, enumerate every qualifying merge in the chosen repository, target branch and interval, including all result pages.
• A convenient sample of five PRs supports a sample-duration description, not the repository’s throughput.
• Include PRs already open at the start; record open PRs at the final snapshot if reporting WIP.
• State the inclusion rule for bots and dependency updates.

Keep Provenance

• Keep URLs or IDs, original timestamps and the extraction date.
• Local Git can cross-check commit identity, but author and committer dates are not substitutes for PR-open or server merge events; squashing and rebasing change the relationship.
• If only Git history is available, report what it actually measures and obtain real PR/issue timestamps.
• Synthetic rehearsal alone does not complete this part of the lab.

The Calculator

mkdir -p out
javac --release 17 -d out FlowMetrics.java FlowMetricsChecks.java
java -cp out FlowMetricsChecks
java -cp out FlowMetrics issues.tsv 2026-10-01T00:00:00Z 2026-10-11T00:00:00Z --scope

Completions in [from, until): 5
Completed points: 16
Mean lead days: 4.60
Mean cycle days: 2.80
Median cycle days: 3.00
WIP at until (after events at that instant): 2
Age E: 4.00 days
Age H: 3.00 days

RM-12 Route A: PR Open-to-Merge Duration

1. Choose a source and rule: repository URL, target branch, fixed UTC interval, extraction timestamp, inclusion rule. Select the first five qualifying merged PRs by merge time and then PR number.
2. Keep provenance for each PR: URL or ID, opened timestamp, merged timestamp, branch. Do not guess midnight if the UI shows only relative dates.
3. Map the data: accepted and started both to the PR opened instant; done to the merged instant; leave points and removed blank.
4. Calculate, then manually verify the longest duration.
5. Interpret and review: coding may begin before a PR opens; draft and review waiting stay in.

RM-12 Route B: Throughput and Open Work

• Enumerate all qualifying merged PRs in [from, until); check pagination and filters; record counts and exclusions.
• Do not filter by opened date: that loses carried-in work.
• For WIP at until, also include every qualifying PR opened by then that had neither merged nor closed. A PR merged after until was still open at until.
• A PR closed without merging maps to removed, not done.
• Only a complete population supports full-window claims.

Combine a Risk, Evidence and a Response

• “There are 159 passing tests in the Chapter 11 version” records a build result.
• It does not say every rule is correct, every important boundary has a test, or more tests would produce a better design.
• Chapter 11 supports one narrow claim: the selected tests detect a deliberately changed equality boundary.
• A high line-coverage percentage can identify unexecuted areas but cannot tell whether assertions distinguish correct from incorrect outcomes.

Debt Needs an Expected Future Cost

• The report’s duplicated selection rule had a plausible maintenance cost; the refactoring removed the duplication.
• We have not measured hours saved or production defects avoided.
• The sequential snapshot join may matter if concurrency enters scope, but a feature deliberately excluded from a teaching application is not automatically debt.
• Use the debt idea to examine why a design decision was made, not to label all untidy code alike.

Claims and Cautious Responses (1 of 2)

Claims and Cautious Responses (2 of 2)

Goodhart’s Law

• Pressure to maximise a proxy can weaken its connection to the goal.
• A target for commit counts can encourage unnecessary splitting; a target for velocity can encourage inflated estimates.
• Neither improves the borrower’s experience by itself.
• Research on developer productivity warns against reducing it to a single activity measure.

Use Measures for Learning

• Team learning and system improvement, not individual rankings.
• A review, a careful deletion or help given to another person may be valuable without increasing the chosen count.
• Pair numbers with a short account of what happened.
• Investigate suspicious numbers without assuming misconduct, and do not present a tiny correlation as a causal explanation.

From Metrics to a Changed Requirement

• The first six sections taught how to read evidence about a team’s work.
• Now the same habits go to a new request: say what it must do, what it touches and what evidence will show it works.
• It is the visiting-researcher change from the opening problem: Chapter 13 implements it and Chapter 14 reviews it.

The Book Exercise Contract

A recognised visiting researcher may request CAM1 or CAM2 for one to three calendar days when a trusted sponsor-approval record matches that borrower, item and exact loan period and is still valid at request time. Missing, rejected, mismatched, expired or unavailable approval must not create a reservation or send a confirmation. Student and staff behaviour must remain unchanged.

What CR-12 Is and Is Not

• A precise book exercise, chosen for teaching. Not an approved institutional policy. Teams apply their own released requirement variant.
• Approval comes from a local read-only data register, not a sponsor website. In Chapter 13 it becomes a genuine file-reading boundary, tested with temporary files as well as doubles.
• Training a model, predicting trust and calling a live approval service are outside the exercise.
• It gives the project another concrete contract and failure boundary.

Trace the Change Through the Design

• BorrowerCategory has STUDENT and STAFF; the directory knows S and T; the coordinator requires a policy for every enum value.
• Adding a category affects more than one enum: directory mapping, composition, exhaustive test setups and the visitor path must agree.
• BorrowingPolicy.mayRequest(count, days) answers only count and duration: no identity, item, approval or clock.
• Passing approval data through hidden global state would defeat that contract.

An Inherited Convention to Preserve

• The coordinator counts every retained reservation for a borrower, despite the variable name activeCount. Returning a loan does not remove its reservation.
• CR-12 preserves this convention. The companion records it as a separate question, SD-12.
• Do not silently replace it with an active-loan count while adding visitors.

Planned Impact (1 of 2)

Planned Impact (2 of 2)

Rejection vs. Operational Failure

• A missing approval is an expected rejection.
• An unreadable or malformed register is an operational failure.
• Both prevent a new visitor reservation, but the response should not falsely say a sponsor rejected something when no valid decision could be read.
• Keep these outcomes visible in the application contract.

The Behaviour and Data Decisions (1 of 3)

The Behaviour and Data Decisions (2 of 3)

The Behaviour and Data Decisions (3 of 3)

• The category-taking entry points are trusted teaching APIs, not authentication.

The Approval Register

borrowerId  itemId  start  endExclusive  sponsorId  status  validFrom  validUntil
V1  CAM1  2026-10-20  2026-10-22  S1  APPROVED  2026-10-18T00:00:00Z  2026-10-20T00:00:00Z

• A local UTF-8 TSV with eight columns, tab-separated. Status exactly APPROVED or DENIED.
• Require start < endExclusive and validFrom < validUntil. A malformed register is rejected as a whole; do not silently skip bad rows. Request keys unique per read.
• At 2026-10-19T12:00:00Z this approves V1’s CAM1 request; at 2026-10-20T00:00:00Z it has expired.

The Acceptance Matrix (1 of 3)

The Acceptance Matrix (2 of 3)

The Acceptance Matrix (3 of 3)

Plan the Smallest Checked Response

• Preserve the passing Chapter 11 version first.
• Record the requirement, accepted examples, assumptions and affected files.
• Order: a thin valid visitor path; the genuine register boundary and failure paths; old-path regression; delivery and demo evidence.
• Each item gets an observable exit condition. Resolve the approval-record format early. Do not copy the synthetic history’s points onto these tasks.

The Ordered Backlog (1 of 2)

The Ordered Backlog (2 of 2)

• C12-2 to C12-6 are planned, not implemented. A design note is not a delivered capability, and a green pre-change build is not evidence that the new rule works.

Keep the Version From Before the Change

Baseline: Chapter 11 running project
Source revision or complete-copy location:
Uncommitted/untracked source accounted for:
Java and Maven versions:
Command and actual result:
SD-11: due-today inclusion preserved; policy unresolved
SD-12: retained-reservation count preserved; policy unresolved
CR-12: specified; implementation pending
Reviewer or explicitly labelled solo review:

• A commit ID suffices only if the intended files are committed; otherwise keep a complete copy such as pre-change-ch12.

The Task

• You start with: the eight-row history, the blocked interval, the measurement contract and the chart table.
• Your task: verify every arithmetic or causal claim independently.
• What is in bounds: explain the data and identify questions; do not change timestamps, estimates or requirements to fit the explanation.
• Mark each claim supported, contradicted or not established.

The Ready-Made Example

Author-written fictional AI output.

The team delivered six items and 18 points because F left the backlog. Mean cycle time is two days after subtracting B’s blocked days. The rise on 4 October proves productivity declined, while the fall on 8 October proves five points were delivered. The legacy architecture caused the waiting. At 16 points per iteration, the remaining seven points will definitely finish in 0.44 iterations. Rank team members by commits to remove the bottleneck.

Verdicts (1 of 2)

Verdicts (2 of 2)

• A good next step: inspect E’s unresolved problem and settle the approval data contract. Another AI opinion is not verification.

Mistakes 1 to 4

Mistakes 5 to 7

What You Start With, and the Demonstration

• Supplied: synthetic issue history and blocked-event note; Java calculator and checks; RM-12 v1.0; CR-12 contract and examples; backlog and impact templates; the Chapter 11 version.
• Demonstration: calculate B’s lead and cycle time; explain day 08’s five-point drop; trace the count/duration policy boundary in the current code.
• Guided practice: pairs reconcile the final scope and trace the interval-edge completion.

Steps 1 and 2: Calculate and Interpret

1. The book’s project: calculate. Reproduce the duration table, completed count and points, final WIP and ages. Run the Java exercise and explain one boundary check.
2. The book’s project: interpret. Explain the scope additions and removal. Write a cautious forecast paragraph and reject the unsupported AI claims.

Steps 3 to 5

3. Your team’s project: required repository lab. Apply RM-12 to real PR or issue timestamps, or an instructor-supplied real export. Produce an auditable duration result and, if the population is complete, throughput. State missing evidence honestly. The synthetic table is rehearsal.
4. The book’s project: preserve and plan. Retain the pre-change version; review CR-12’s matrix; order a small backlog for Chapter 13. Do not implement the feature.
5. Your team’s project: transfer. Apply the impact method to your released variant. Record one dependency or policy question and how its answer would change the plan.

What You Should End Up With, and When You Are Done

• What you should end up with: calculations; source and contract; cautious interpretation; reviewed AI claims; version reference; updated backlog; change-impact note. Keep real repository evidence separate from the synthetic sample.
• Complete when: the arithmetic reconciles; event boundaries and population are explicit; open items and removals stay visible; repository results have traceable real sources; no individual ranking; new behaviour has acceptance examples; old behaviour and unresolved defects have a preservation plan.
• Optional: compare two complete intervals with the same inclusion rule, or add reopened-item support with a clearly revised data model.

Concept Questions

1. How do lead time and cycle time differ under this chapter’s contract? Why must the boundaries travel with the reported number?
2. How can a burn-down fall without an equivalent amount of work being delivered?
3. Why can equal throughput coexist with different cycle times and different customer experiences?
4. Why does a passing regression suite support preserving old behaviour without proving the new approval requirement?

Diagnosis Questions

5. A dashboard calculates average cycle time only for items both started and finished this week, then claims it represents every item finished this week. What is wrong with the cohort, and which carried-in work could disappear?
6. A developer adds VISITOR to the enum and passes sponsor approval through a static Boolean read by BorrowingPolicy. Identify the contract, test isolation and request-matching risks; propose a clearer boundary without implementing it.

Guidance: Questions 1 to 4

1. Lead (Accepted to Done) includes the pre-start queue; cycle (Started to Done) does not. B: lead five, cycle four. Another team’s lead time may start at a customer request: the number cannot travel without its event definition.
2. Removing F reduces remaining scope by two while delivering nothing; re-estimation could also move a line. Keep a scope event record; use a burn-up.
3. A carried-in seven-day item and a newly completed one-day item count equally. Recipients experience different waiting.
4. The old tests describe existing contracts; they contain no sponsor-approval requirement. Keep them; add new acceptance, unit and integration checks.

Guidance: Questions 5 and 6

5. Filtering on both start and finish within the week excludes long-running carried-in work that finished this week. Define the cohort by the finish event, compute durations from actual start timestamps, and report unfinished-item age separately.
6. Approval belongs to a specific borrower, item and period at a specific time. A static flag loses that identity and leaks across requests and tests, and violates the count/duration contract. Obtain a typed approval decision through an application boundary; validate match and time with explicit inputs before creating the reservation.

Transfer Challenge: ML Model Serving

An ML model-serving team: only approved model versions may be served to external callers. Its dashboard counts successful builds and reports “all requested releases are complete.”

• Define a useful unit and Done event.
• Identify the missing approval and serving evidence.
• Plan a narrow change with an unavailable-registry case.
• Explain why model accuracy, build success and release approval are different observations.
• Synthetic model identifiers only.

Transfer Guidance

• Unit: one requested release of a named model version to a stated serving environment. Done: the approved version is demonstrably served at that boundary with required checks, not a successful build.
• Keep build, approval and activation timestamps separate. An unavailable approval registry must not be treated as permission to serve.
• Plan a valid activation path; mismatched, expired or denied approval; registry failure. Test the genuine registry boundary separately from orchestration doubles.
• Accuracy concerns predictive behaviour; build success construction checks; approval a governance decision. None substitutes for another.

Summary

• A measurement is useful when its definition supports a concrete decision.
• The synthetic history shows why scope, elapsed time, unfinished work and completion counts must be read together.
• Repository evidence adds traceability but does not reveal every cause of delay or every valuable contribution.

Where the Project Stands

• The application remains at the pre-change version.
• CR-12 and the ordered backlog give a precise basis for Chapter 13: implementation, genuine boundary tests and delivery evidence.

Sources and Further Reading

1. Kanban Guides: The Kanban Guide, May 2025.
2. Schwaber and Sutherland: The Scrum Guide, November 2020.
3. Fowler: Technical Debt Quadrant (2009).
4. Forsgren et al.: The SPACE of Developer Productivity, ACM Queue 19(1), 2021.
5. Git Project: git-log documentation. Oracle: Java SE 17 Duration.
6. Martin: Agile Software Development (2002). Forsgren, Humble, Kim: Accelerate (2018).

• Full references and links are in the chapter text.