Skip to content

feat: decision artefacts open with the verdict - #921

Merged
tractorjuice merged 2 commits into
mainfrom
feat/verdict-first-summaries
Oct 8, 2026
Merged

tractorjuice merged 2 commits into
mainfrom
feat/verdict-first-summaries

Conversation

@tractorjuice

Copy link
Copy Markdown
Owner

Summary

Business cases, research findings and design reviews now lead with the decision. Until now each of their Executive Summaries reached its verdict only after the background, the costs or the review set-up. The new order follows Barbara Minto's Pyramid Principle: the verdict first, then the reasons it rests on, then context, risks and next steps.

  • New shared reference references/executive-summary-pattern.md: the verdict comes in the first sentence; give as many reasons as the evidence supports (three is not a quota); risks and next steps go at the end, except that a risk which could change the decision sits next to the verdict; the summary holds no figure the body does not. It also says where the rule does not apply (timelines, runbooks, plans, inconclusive results). Synced to every community plugin and the nested layout.
  • SOBC: the Go/No-Go line, recommended option and rationale open the summary. Before, they came after Purpose, Problem, Solution, Strategic Fit, Investment, Benefits and ROI. "Top 3 benefits" is gone.
  • RSCH: a one-sentence Recommendation now opens Key Findings, with one bullet per category; Research Scope moves to the end of the summary. The research writer may build that sentence only from the per-category verdicts and the TCO totals it renders.
  • HLDR / DLDR: the Executive Summary becomes section 1 and Review Overview section 2. No code or docs cite those section numbers, and the hooks that read the review verdict don't depend on section order.
  • sobc, hld-review, dld-review, the research writer and the research monolith point at the reference. The quality checklist has one new check each for RSCH, SOBC, HLDR and DLDR.
  • ENFORCEMENT.md has a new Tier 2 row for the rule; CHANGELOG has an Unreleased entry.

Prompted by a review of millwright-labs/minto-pyramid-skill (MIT). We don't bundle that skill: it is built for editing a user's own draft, it would overlap with the commands, and its own evals show it fails on Haiku. This PR takes its rules into the templates instead.

Eval

A new verdict-leads-summary grader on sobc-traces-to-stakeholders checks that the summary opens with the Go/No-Go recommendation.

  • Replayed against the 9 recorded runs made before this change (Opus 5.5 and Sonnet 5.5, at high and max), it fails all 9: every one opened with Purpose.
  • Live, one run on Opus 5.5 scores 8/8 ($3.68). The model also put the five-year break-even caveat in the verdict line, as the reference asks for a risk that could change the decision.

The old template was at fault, not the eval case. RSCH and the HLD/DLD reviews have no eval case, so for those templates only the quality checklist checks the new order.

Test plan

  • sync-shared-assets.py --check, sync-claude-plugin-layout.py, converter.py
  • check_references.py, check-quality-checklist-refs.py, check-citation-section-refs.py, check-quality-checklist-ladders.py, check-doc-control-resolution.py, check-guide-parity.py, check-orchestrator-leaks.py
  • pytest tests (2131 + 152 passed)
  • markdownlint on changed files (0 issues)
  • eval-headless.py --replay on 9 recorded runs, and one live run

🤖 Generated with Claude Code

Business cases, research findings and HLD/DLD reviews now put the
decision first in their Executive Summary, following Minto's Pyramid
Principle: verdict, then the reasons it rests on, then context, risks
and next steps.

- New shared reference references/executive-summary-pattern.md,
  synced to every community plugin and the nested layout
- SOBC: Go/No-Go, recommended option and rationale lead the summary;
  benefits no longer fixed at three
- RSCH: a one-sentence recommendation leads Key Findings; Research
  Scope moves to the end of the summary
- HLDR/DLDR: Executive Summary becomes section 1, Review Overview 2
- sobc, hld-review, dld-review, the research writer and monolith
  point at the reference; quality-checklist gains a check per type
- New verdict-leads-summary grader on sobc-traces-to-stakeholders.
  Replayed, it fails all 9 recorded pre-change runs; a fresh live run
  on Opus 5.5 scores 8/8 ($3.68). The old template was wrong, not
  the case.
- ENFORCEMENT.md Tier 2 row; CHANGELOG entry

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tractorjuice tractorjuice added the enhancement New feature or request label Oct 8, 2026
@tractorjuice
tractorjuice merged commit c3637a0 into main Oct 8, 2026
3 checks passed
@tractorjuice
tractorjuice deleted the feat/verdict-first-summaries branch October 8, 2026 18:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant