Skip to content

Release Notes v0.2.0

Released: 2026-11-01

Ties the chain from activities to impact to the numbers people steer by and are told. A program or product can name a North Star and the guardrails that watch it, each audience can lead with its own short list of numbers, and 18 new lint rules check that the chain is filled in. The logic model can now be drawn as columns with a real arrow wherever one thing leads to another.

This release has one breaking change: the intermediate outcome level is now medium_term. See Upgrading.

Highlights

  • Headline metrics. A North Star, an optional one metric that matters, and guardrails for each program or product. A short, ordered, worded headline list for each audience, drawn from the same indicators, so the board, funders, and members can lead with different numbers and still see the same figure.
  • A checked chain. 66 lint rules, 18 of them new, that look for an activity that leads nowhere, a link and intervention that disagree, an audience told about outcomes but given no numbers, and a North Star that is an output or sits above the ceiling of accountability.
  • A layered logic model diagram. Columns from inputs to impact, a box for each item, and arrows that follow the theory. Written as D2 and as Mermaid.
  • Composed indicators. A number such as cost per applied change is worked out from the latest value of its parts, and an estimate is shown as an estimate.
  • One series of levels. Short, medium, and long term, with medium_term replacing intermediate.

New Features

Headline metrics

  • North Star. A pathway's focus names the indicator it steers by (northStarId), an optional oneMetricId, the guardrailIds that watch what chasing it could harm, and a rationale. A pathway can now be a program or a product.
  • Headline lists. An audience's headline is an ordered list of indicators, each with an optional label and note worded for that reader.
  • Mission and vision. context.mission and context.vision state purpose without making it part of the causal chain.
  • Tiers. What an indicator measures decides its tier (activity, output, outcome, or impact). Document.IndicatorTier, IndicatorServes, and IndicatorPathways answer it once for every rule and report.
  • Commands. pathway set takes --north-star, --one-metric, and --guardrails, and an audience's headline list is set with --set headline=.... Removing an indicator with rm --cascade also removes it from every headline list and focus that names it.

Lint

18 new rules, 66 in all:

  • The chain (TOC-INT-003 to TOC-INT-007): every intervention says what it produces, leads to an impact, agrees with the links that name it, is measured, and states its resources.
  • Headline lists (TOC-AUD-002, TOC-HLN-001 to TOC-HLN-004): an audience told about outcomes is also given numbers, and a headline list is short, is reported to its audience, can be produced, and is chosen when there are many indicators.
  • North Stars (TOC-NSM-001 to TOC-NSM-007): a North Star measures an outcome at or below the ceiling of accountability, has a baseline, a target, and a guardrail, belongs to its own pathway, and is not also a guardrail.
  • Framing (TOC-CTX-001): the theory states its mission or vision.

Every new rule is a warning or advice, so a theory that was GO stays GO.

Reports and decks

  • headline shows what each audience is told, with the latest figure, status, claim, notes, and caveats, and a matrix of who is told what. --audience narrows it.
  • metric-tree shows, for each pathway, its North Star and guardrails and then its indicators from activity to impact, as a table and a diagram. --pathway narrows it.
  • logic-model-layered and logic-model-d2 draw the logic model as columns. See below.
  • Estimates. An estimated value reads "estimate, on 2026-09-30" in every report, with its observation note.
  • Story report and deck. They tell an audience its whole headline list, in its order and wording. They no longer take the first five indicators in file order.
  • Workshop deck. Each logic model table is followed by a slide that draws the same logic model as columns with arrows.

The layered logic model diagram

An input leads to the activities that use it, an activity to the outputs it lists and then to the outcomes it targets, and an outcome to the outcomes its causal links point to, so one box can lead to several and several can lead to one. Within a column, boxes are ordered to keep arrows from crossing. A link that runs back to an earlier stage is feedback. It is listed under the diagram and not drawn across the boxes in between.

logic-model-layered writes Mermaid. logic-model-d2 writes D2, and its grid keeps every stage in its own column:

theoryofchange report logic-model-d2 theory.yaml --pathway pw-learning > lm.d2
d2 lm.d2 lm.svg

The existing logic-model table and --diagram are unchanged. The diagram is written through d2vision's diagram spec.

Composed indicators

An indicator can be worked out from others with composedOf: a ratio, difference, product, or sum, such as a cost divided by the changes it paid for. When the indicator has no observation of its own, its value comes from the latest value of each part, and it is marked as an estimate if any part is. A missing part or a zero divisor gives no value, so a partial figure is never passed off as complete. Validation checks the operation, the number of parts, that the parts exist, and that the arithmetic is not circular. It is arithmetic and not a causal link. indicator set takes --composed-op and --composed-of.

Examples

The membership network example now has a mission and vision, a North Star and guardrail for three of its program areas, and headline lists for the board, funders, and members.

Documentation

Installation

go install github.com/ProductBuildersHQ/impact-model/cmd/[email protected]

Go 1.26.5 or later. The optional programs are the same as in v0.1.0: marp for decks, mmdc for diagrams, and pandoc for Word and PowerPoint. To draw the D2 diagram you also need the d2 tool, and the command that writes D2 does not.

Upgrading

intermediate is now medium_term

The level is renamed so that short, medium, and long term read as one series. There is no alias. A theory that still says level: intermediate fails validation, once for each such outcome:

error VAL-SCH-001 /outcomes/6/level: value must be one of 'impact', 'long_term', 'medium_term', 'short_term', 'output'

Replace level: intermediate with level: medium_term in YAML, or "level": "intermediate" with "level": "medium_term" in JSON. Other places that change with it:

  • Reports and diagrams say "Medium-term outcomes" where they said "Intermediate outcomes", and a Mermaid subgraph is lv_medium_term.
  • In Go, toc.LevelIntermediate is toc.LevelMediumTerm.
  • The embedded theory-of-change JSON Schema lists medium_term.

More lint findings

A theory that was clean can now show new warnings and advice, such as TOC-INT-003 for an intervention that does not say what it produces, and TOC-NSM-007 for a program with no North Star. None is an error, so the result is still GO. Use lint --disable to skip a rule you do not want yet.

Compatibility

Files still carry specVersion: "0.1". This version reads any 0.x, so a document written for v0.1.0 is read, and only its intermediate levels need to change. Every new field is optional. Exit codes are unchanged.

Known Limitations

  • Inputs are text. The diagram's inputs come from an intervention's free-text resources, so one funding source cannot yet feed several activities by ID.
  • Wide diagrams. With seven stages and long labels the layered diagram is wide, and text on a slide is small. Labels are not wrapped.
  • Feedback is listed, not drawn. A link that runs back to an earlier stage appears in a list under the diagram.
  • Mermaid places its own columns. Only the D2 form keeps each stage in a column.
  • Panels. A slide with panels for background, goal, issues, assumptions, and critical success factors around the diagram is not built.
  • The limitations of v0.1.0 for Google sharing, the USM and UFM contract, rendering tools, and judging still apply.