Release Notes v0.5.0¶

Released: 2026-11-01

The problem tree joins the projections of an impact model. It puts the problem a program exists to solve in the middle, its causes below as roots, and its effects above as branches, and checks that every cause and effect is addressed by an outcome or set aside with a reason. Causes, and the new effects, form a network: each can lead to several others.

AI agents can now produce every PRISM export, and the definitions pack opens with the problem tree.

One change breaks documents: a cause's parent is now parents, a list. Go code that calls report.Definitions also changes. See Upgrading.

Highlights¶

Problem trees. report problem-tree draws the core problem with causes below and effects above, arrows flowing upward from the deepest causes to the furthest effects, and lists what addresses each.
Effects. The problem tree's branches: what the core problem leads to. Outcomes name the effects they relieve with addressesEffects.
A network, not only a tree. A cause can contribute to several others and an effect can follow from several, so parents is a list.
JSON first. The diagram is built as a JSON diagram document, from which D2 and Mermaid are rendered, and report problem-tree-json prints it.
Exports for agents. The MCP tool impact_export writes the OKR, outcome-journey, V2MOM, and DMAIC documents, through the same code as the command line.

New Features¶

Problem tree reports¶

impact-model report problem-tree impact-model.yaml        # Markdown, with a Mermaid diagram
impact-model report problem-tree-d2 impact-model.yaml     # the same, with a D2 diagram
impact-model report problem-tree-json impact-model.yaml   # the diagram document itself

Diagram	In the model
Core problem, in the middle	`context.problemStatement`
Causes (roots), below	`causes`, each leading to its `parents` or to the core problem
Effects (branches), above	`effects`, each following from its `parents` or from the core problem
What addresses a cause	an outcome's `addressesCauses`
What relieves an effect	an outcome's `addressesEffects`

The core problem is in the middle row. A cause is one row below its lowest parent and an effect one row above its highest, so every arrow points up. A cause or effect set aside is drawn faded, and a rejected one is left out. The JSON report is the d2vision diagram spec both renderings come from, written without the Markdown stamp so it stays valid JSON. The problem tree guide explains each part.

Effects¶

effects:
  - id: eff-diabetes
    statement: Diabetes and heart disease
  - id: eff-costs
    statement: Higher health costs
    parents: [eff-diabetes]
outcomes:
  - id: oc-eat-well
    title: People eat well
    level: impact
    addressesEffects: [eff-diabetes]

An effect has a statement, the effects it follows from, affected groups, evidence, an optional out-of-scope reason, and provenance. Validation reports an effect without a statement (VAL-EFF-001), one among its own parents (VAL-EFF-002), a chain of parents that loops (VAL-EFF-003), and one set aside without a reason (VAL-EFF-004). The effect element command adds and changes effects, and outcome set --relieves names the effects an outcome relieves.

Causes as a network¶

A cause's parents are the causes it contributes to, so structural causes feed underlying ones, underlying feed immediate, and immediate causes lead to the core problem. Validation now finds a loop through any branch of the network. Causes also take provenance, so one can be rejected in review like other elements.

Lint¶

Three new rules, 72 in all:

IMP-EFF-001: each effect is relieved by an outcome or set aside with a reason
IMP-EFF-002: effects are relieved by long-term or impact outcomes, not only by earlier ones
IMP-CAU-003: a cause contributes only to causes at its own level or nearer the problem, which catches a link written the wrong way round

The cause rules now skip rejected causes.

The definitions pack opens with the problem tree¶

report definitions, the pack a workshop reviews before any data exists, now starts with the problem tree when the model records causes or effects, ahead of the causal pathways, logic models, outcome maps, logframes, metric definitions, and glossary. A model with no causes or effects gets the same pack as before. The pack's Word, PowerPoint, and Pandoc exports, and the judge bundle's narrative, include it too.

Exports from the MCP server¶

The new impact_export tool takes a model, inline or by path, and an export kind: okr, journey, v2mom, or dmaic. With observations, or a status date, the export carries the latest values and status. It returns the document, and for DMAIC the indicators it left out and why:

{ "kind": "dmaic", "document": { "...": "..." }, "omissions": [{ "indicatorId": "ind-nps", "reason": "it has no numeric target" }] }

A model the format cannot be drawn from is refused with the same message the command line gives, naming what to add. Both now export through service.ExportPRISM, so they cannot drift apart.

Examples¶

The examples linked their causes the wrong way round, from the nearer cause to the deeper one, and now point from deeper causes toward the problem. In the membership network, working alone feeds both of the immediate causes. Both the membership network and the course catalog gain the effects of their core problems, each relieved by a long-term or impact outcome.

Documentation¶

A new problem tree guide.
The authoring, CLI, examples, and getting started guides cover effects and the problem tree, and the concepts page lists it as a projection.
The README and the documentation home list the problem tree among the projections, add the problem, causes, and effects to what an impact model holds, and show the journey, V2MOM, and DMAIC exports. A test keeps the two in step.
The reports guide lists what the definitions pack contains, and the MCP guide lists impact_export.
Credits name problem-tree analysis in the logical framework approach, V2MOM, Six Sigma's DMAIC, and Shewhart's control charts.

Installation¶

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

Go 1.26.5 or later. To draw the D2 diagram you also need the d2 tool.

Upgrading¶

Documents: `parent` is now `parents`¶

A cause that names a parent must name it in a list. Validation refuses the old field:

error VAL-SCH-001 /causes/2: additional properties 'parent' not allowed

# was
causes:
  - id: cause-fast-food
    level: underlying
    parent: cause-busy

# is
causes:
  - id: cause-fast-food
    level: underlying
    parents:
      - cause-busy

In JSON, "parent": "cause-busy" becomes "parents": ["cause-busy"]. Nothing else in a document changes; specVersion stays "0.1".

While you are there, check which way the links point. A cause's parents are the causes it contributes to, nearer the problem. If an immediate cause names an underlying or structural one as its parent, the link is reversed, and IMP-CAU-003 now reports it.

Command line¶

cause add and cause set take --parents, which accepts several IDs, in place of --parent.

Go code¶

impact.Cause.Parent string is now Parents []string.

report.Definitions takes the impact model, to draw its problem tree, and returns an error, since drawing it can fail:

// was
pack := report.Definitions(whole, pathways)

// is
pack, err := report.Definitions(whole, pathways, doc)
if err != nil {
    return err
}

Other changes are additions: impact.Effect, Model.Effects, Outcome.AddressesEffects, Cause.Provenance, the problemtree package with Tree.Empty, and service.ExportPRISM, PRISMExport, PRISMExportKinds, and IsPRISMExport. prismx.Omission gains JSON field names, indicatorId and reason.

Compatibility¶

An API comparison against v0.4.0 reports two incompatible changes, the removal of Cause.Parent and the new signature of report.Definitions, and the additions above as compatible. The command line keeps its exit codes, and a model with no causes or effects is unaffected.

Known Limitations¶

Labels are not wrapped, so a long problem statement makes a wide box. Keep the core problem to a short phrase and put the detail in the narrative.
Row order is file order, so arrows between rows can cross; reorder causes or effects in the file to change it.
Mermaid places rows itself. Only the D2 rendering keeps every row in place.
The limitations of v0.4.0 still apply.