Skip to content

Release Notes v0.1.0

Released: 2026-10-30

The first release. A Go-first model of a Theory of Change, with generated JSON Schemas, a command line, an MCP server, measurement, reports and decks, and a review round trip, all working on one validated document.

Highlights

  • A model you can trust. Outcomes, causal links, precondition groups, interventions, assumptions, indicators, actors, evidence, and pathways, with a provenance for every element: stated, inferred, hypothesis, confirmed, or rejected.
  • Safe editing. One validated, atomic patch engine behind the CLI, the SDK, and the MCP tools. A change that would leave a theory worse is rejected.
  • Quality checks. Seven embedded JSON Schemas, structural validation, 48 deterministic lint rules in three profiles, and a rubric for LLM-as-a-Judge review.
  • Measurement. Indicator, outcome, pathway, link, and assumption status as of a date, with assumption propagation and rule-based confidence.
  • Artifacts for every audience. Logic models, outcome maps, results frameworks, executive and audience reports, four slide decks, and Word, PowerPoint, and CSV export.
  • Review that comes back. Send a packet or sheet out, bring the answers back as proposed changes, and record approval.
  • Agent ready. An MCP server with ten tools and five agent skills.

New Features

Model and schema

  • Five outcome levels, precondition groups (all, any, at_least, nested), causal links with polarity and feedback loops, and a ceiling of accountability.
  • Responsibility for each outcome (own, shared, partner, unaddressed), a problem tree, target groups, audiences, and a story codebook.
  • A shared metric library with aggregation rules, a glossary, a collection plan, and a measurement budget.
  • Seven JSON Schemas generated from the Go types and embedded for editors and agents: theory-of-change, observation-set, theory-of-change-status, status-diff, actor-registry, review-response, and csv-mapping.
  • Parent and child theories, and competing futures that share one actor registry.
  • Canonical YAML and JSON, so the same theory is byte-identical however it is written, and a content hash that is the same in every export.

Editing

  • add, set, and rm for twenty element kinds, and patch for RFC 6902 JSON Patches with @id pointers. Changes are atomic and previewable with --dry-run; rm --cascade removes what cannot survive the removal.
  • diff compares two versions by element ID and can draft a revision record.
  • fmt writes canonical form; init writes a starter theory.

Checks

  • validate for schema and structure, observation sets, children against a parent, and competing futures.
  • lint with 48 rules, profiles draft, standard, and full, and a structured-evaluation report as JSON.
  • graph for upstream and downstream queries, paths, cycles, orphans, dead ends, and levels, with Graphviz output.
  • judge show, record, and summary for a core rubric of 12 categories and a development addendum, with four aggregation modes. The commands make no model calls.

Measurement

  • import observations loads a spreadsheet through a column mapping and reports every row it cannot place.
  • status gives each indicator a status (achieved, on_track, at_risk, off_track, stale, no_data, not_started, baseline_only), rolls indicators up to outcomes and pathways by the precondition logic, caps results by assumption status, and scores confidence. Comparing to an earlier snapshot lists what changed.

Reports, decks, and exports

  • 11 definition reports that need no data, and 12 status reports, including a story report per audience and a learning review. Stories and quotes are shown only with consent, and restricted evidence is never rendered.
  • Four Marp decks (workshop, executive, learning review, audience story) with speaker notes.
  • CSV tables, Word and PowerPoint through mmdc and pandoc, and OKR and outcome-journey JSON for the PRISM tools.

Review round trip

  • export review-packet and export review-sheet send a theory out.
  • import review turns answers into a patch, a list of rows for a person, and a consultation record, and never changes the theory itself.
  • approve records approval with approvers, a version, and a date, and refuses while hypotheses remain open.

MCP server and skills

  • theoryofchange mcp serves ten tools over standard input and output. File paths are confined to a root directory, including symbolic links.
  • Five agent skills: draft a theory from sources, author and edit, refresh status from a spreadsheet, run a learning review, and write an audience story.

Examples

Three fictional, complete examples: a membership network, a market-adoption theory, and three competing futures. The test suite checks that each is valid, in canonical form, and free of real URLs.

Documentation

Installation

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

Go 1.26.5 or later. Three optional programs add output formats: marp for decks, mmdc for diagrams, and pandoc for Word and PowerPoint. A command that needs one that is missing writes nothing and exits with code 3.

Compatibility

This is the first release, so there is nothing to migrate. Document and observation files carry specVersion: "0.1". Exit codes are 0 for success, 1 for invalid input or a rejected change, 2 for a usage or I/O error, and 3 for a missing external tool.

On Windows, keep LF line endings for theory files (* text=auto eol=lf in .gitattributes): the canonical form is byte-exact LF.

Known Limitations

  • Sharing a review through Google Docs and Sheets is not built into this tool. It makes no network calls; the gogoogle command line covers the Google side, and an agent skill that runs the whole workflow is planned.
  • The integration contract for USM and UFM is a draft awaiting review by their owners.
  • Rendering diagrams to PNG, and decks to PPTX, needs mmdc and marp. The test suite skips those paths when the tools are absent.
  • Judging needs a judge. The tool prepares the bundle and combines verdicts but does not call a model.