research.md

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.

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 visionlog. A decision earned here becomes a contract recorded as an ADR in visionlog, which ike.md then executes against. A decision skipped here is a contract that was never earned.