Decisions

research.md

Evidence-graded, phase-gated, peer-reviewed decisions. The research is the receipt.

pip install research-md

View on GitHub v0.5.1 May 14, 2026

What it does

research.md is the decision forge. When a question has consequences — architecture choices, technology selections, strategic bets — you run it through research.md so the evidence is recorded, the criteria are locked, and the decision is reviewable by any future agent or human.

What earning a decision looks like

Consequential decisions — the database, the auth model, the deploy target — get made casually in chat, and then quietly re-litigated every quarter because nobody remembers the tradeoffs. Research.md is the forge that earns the decision: candidates, locked criteria, graded evidence, peer review. The output is an ADR Governor can enforce and Docket can cite. The research is the receipt.

1. The drift case — a decision made "in chat"

agent · chat

  # question: "should we pick Postgres or DynamoDB for the new service?" agent "both work, let's go with Postgres — we know it."  › research status --project checkout-store NO_RECORD no candidates, no criteria, no scoring, no ADR governor 0 ADRs for this choice · future agents will re-ask it  why: this decision will be re-litigated in 3 months.  earn it — run it through research.md.   

2. The earned decision — phase-gated, scored, adopted

agent · research.md

  › research candidate create "Postgres" && candidate create "DynamoDB" › research criteria lock weighted: RLS=3 · scalability=2 · ops-cost=2 · dx=1 locked 4 criteria · no further changes without a supersede  › research candidate score --scores-from evidence/  Postgres RLS 9 · scale 7 · ops 8 · dx 9 → 7.8  DynamoDB RLS 4 · scale 9 · ops 7 · dx 5 → 6.2 peer_review_log 2 reviewers signed off · no open objections  › research project decide --winner Postgres DECIDED Postgres · ADR-017 authored into Governor  docket: future tasks cite ADR-017; re-litigation requires supersede.   

research.md feeds Governor; Governor feeds Docket. The flow is one-way — a decision skipped here is a contract that was never earned, and becomes the thing a future agent re-opens at the worst possible time.

Key features

Phase-gated workflow — candidates → criteria lock → scoring → decision
Evidence grading — claims backed by data, not assumptions
Scoring matrix — weighted criteria, transparent scoring
Peer review — log reviews before finalizing
Decision briefs — auto-generated summary of what was decided and why
MCP server — agents drive the entire research workflow through tool calls

Install

pip install research-md

Quick start

# Initialize a research project
research init --name "Choose a database"

# Add candidates
research candidate create --title "PostgreSQL"
research candidate create --title "SQLite"

# Lock criteria (no more changes after this)
research criteria lock

# Score candidates
research candidate score --candidate "PostgreSQL" --scores 'scalability=9,simplicity=6'

# Decide
research project decide --winner "PostgreSQL" --rationale "Needs multi-tenant RLS"

The trilogy

research.md feeds Governor. A decision earned here becomes a contract recorded as an ADR in Governor, which Docket then executes against. A decision skipped here is a contract that was never earned.