Research — Full Lifecycle Guide

Before your output, print ## RESEARCH_FINDING on its own line — a marker some setups use to pull findings into a records dashboard automatically. If you don't have anything reading that marker, it's harmless to print anyway.

Overview

This is a structured research lifecycle: check what's already known, write down the hypothesis before you start, gather evidence, and record the verdict. The record itself lives wherever you've told it to — your own API if you built one, or a local file by default.

If you've set up your own API for this (see /alignment-harness:harness-setup), use whatever CRUD endpoints and auth you configured there. Otherwise (default): each finding is a JSON file under the folder alignment-harness records research prints, named <slug-of-the-title>.json or a short id you assign yourself.

---

Research Rigor Standard

Conclude nothing without rigor and evidence. Build from ideation to evidence without skipping over conflation of "looks like" with "means."

Every research product must distinguish between:

• Observed data — what the numbers actually show (measurement)
• Correlation — two things that move together (pattern, not causation)
• Causal claim — X caused Y (requires mechanism + controlled comparison)

"Looks like" is an observation. "Means" is a conclusion. Never bridge from one to the other without stating the evidence chain that justifies the leap. If the chain has gaps, say so — gaps are valuable, not shameful.

---

Step 1: Check Existing Knowledge First

Before creating a new finding, search for prior research on the topic.

# If you've set up institutional-memory search (/alignment-harness:harness-setup, checkpoint
# "memory-search"), use it first — it searches your past sessions and this repo's notes:
<your configured memorySearchCommand> "your research topic here"

# Otherwise, grep works fine:
grep -ril "your research topic" $(alignment-harness records research)

# If you have your own research-findings API, search it too:
curl -s "<your-api>/research-findings/search?query=YOUR_TOPIC" \
  -H "x-api-key: $YOUR_API_KEY" | jq '.data[] | {id, title, verdict, confidence}'

If nothing is set up yet, say so plainly and proceed — don't silently skip the step or pretend it found nothing when it never actually looked anywhere.

If existing research covers your question, build on it instead of starting fresh. Link to it (see "linked findings" below).

---

Step 2: Create a Finding

Create a finding with your hypothesis BEFORE conducting the research. This makes the research trackable from the start — a hypothesis written down before you know the answer is worth more than one reconstructed afterward to fit the data.

Local file (default):

DIR="$(alignment-harness records research)"
FILE="$DIR/<short-slug-for-this-finding>.json"
cat > "$FILE" <<'EOF'
{
  "title": "Descriptive title of what you are investigating",
  "subtitle": "One-line context",
  "researchType": "metric-analysis",
  "hypothesis": "We believe X because Y, and expect to see Z",
  "metricKey": "example_metric_name",
  "dataSource": "wherever this project's data actually lives",
  "tags": ["example", "tags"],
  "verdict": "in-progress"
}
EOF
echo "$FILE"

If you have your own API:

curl -s -X POST "<your-api>/research-findings" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $YOUR_API_KEY" \
  -d '{ ... same fields as above ... }'

Save the returned id — you'll need it for all subsequent updates.

Research Type Options

Type	When to use
metric-analysis	Analyzing a metric, conversion rate, or behavioral pattern
ux-regression	Investigating a UX degradation or regression
decision-audit	Reviewing whether a past decision had its intended effect
cohort-analysis	Comparing user cohorts (by signup date, plan, behavior)
funnel-analysis	Analyzing drop-off in a conversion funnel
ab-test-review	Reviewing results of an A/B experiment
system-health	System performance, error rates, infrastructure
other	Anything that does not fit the above

---

Step 3: Conduct the Research

Web research

If you have a web-research tool (a search/scrape CLI, a browser tool, etc.), use it for anything that requires looking outside your own codebase and data. If you don't have one set up, say so and reason from what's available — code, docs, and your own data.

Your own data

Query wherever your project's real data actually lives — a database, an analytics tool, log files, a metrics dashboard. This varies by project; don't assume a specific stack. If you don't know where it lives, ask: "To research this properly I'd want to look at your own data — where does it live?"

Codebase research

# If you've set up institutional-memory search, use it for "has this pattern
# come up before" questions. Otherwise, plain code search:
# Use Grep and Read tools as normal.

---

Step 4: Record Findings

Update the finding with your methodology and results.

Local file: re-open the same JSON file and add/update these fields:

{
  "methodology": "What you actually did — e.g. queried the data for a date range, compared before/after a specific change",
  "findings": "## Key Findings\n\n1. ...\n2. ...\n3. ...",
  "conclusion": "The plain-language conclusion, stated at the confidence level the evidence supports",
  "timeRange": { "from": "2026-03-01T00:00:00Z", "to": "2026-03-15T00:00:00Z" }
}

If you have your own API: PUT those same fields to the finding's endpoint.

---

Step 5: Add Measurements

Attach quantitative data points to track the metric over time — add entries to a measurements array in the same file (or POST them to your API if you have one):

{ "date": "2026-03-10T00:00:00Z", "value": 4.2, "label": "what this number is", "notes": "context for this data point" }

Add multiple measurements to build a time series. If you have a viewer, render these as a chart; otherwise the array itself is the record.

---

Step 6: Link Decisions

Connect code changes or decisions that caused the observed effect — add entries to a linkedDecisions array:

{ "commitHash": "abc123def", "date": "2026-03-08T00:00:00Z", "description": "What changed", "impact": "negative" }

Impact options: positive, negative, neutral, unknown

---

Step 7: Set Verdict and Confidence

When research is complete, set the final verdict — update the same fields, locally or via your API:

{
  "verdict": "confirmed",
  "confidence": 85,
  "actionRecommendation": "What to actually do about this",
  "status": "actionable"
}

Verdict options:

Verdict	Meaning
in-progress	Research is ongoing
confirmed	Hypothesis validated by evidence
refuted	Hypothesis disproven by evidence
inconclusive	Evidence does not clearly support or refute
needs-more-data	Insufficient data to reach a conclusion

Confidence: 0-100 continuous score. Never bucket it. 85 means exactly 85.

Status options: backlog, actionable, in-progress, reviewed, done, in-production, archived

---

Quick Reference: local files vs your own API

Action	Local default	If you have your own API
List all	ls $(alignment-harness records research)	GET /research-findings
Search	grep -ril "<query>" $(alignment-harness records research)	GET /research-findings/search?query=X
Get one	cat <file>.json	GET /research-findings/:id
Create	write the JSON file (Step 2)	POST /research-findings
Update	edit the JSON file	PUT /research-findings/:id
Delete	delete the file	DELETE /research-findings/:id
Add measurement	append to measurements[]	POST /research-findings/:id/measurements
Add linked decision	append to linkedDecisions[]	POST /research-findings/:id/linked-decisions

Quick Reference: Related Skills

Skill	When to use
/agentic-artifact-cache	Reading/managing cached research artifacts, if shipped
a web-research tool, if you have one	Web scraping and deep research
a metrics/analytics skill, if you have one	KPI analysis and conversion-rate research
your own telemetry/eval skills, if you have them	Quality or performance investigation specific to your product

None of the above need to exist for this skill to work — they're where to reach for extra leverage if you've built them.