# Research Hypothesis Reflection

> Review a ResearchCase v1 after evidence or experiment feedback arrives. Use when a research workflow must detect supporting-versus-challenging evidence conflicts, negative/null/invalid results, dependent evidence, or stalled inquiry; preserve prior hypotheses in a versioned ReflectionMemo; and choose only continue, reroute, rollback, human_review, or stop_unresolved.

- Skill: `lx050/research-hypothesis-reflection` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add lx050/research-hypothesis-reflection`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lx050/research-hypothesis-reflection/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: Lx050 (https://skillmd.com/u/lx050)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lx050/research-hypothesis-reflection

---


# Research Hypothesis Reflection

Reflect on structured research state without rewriting the input case or hiding adverse results.

Contract identity:

- `skill_id`: `research-hypothesis-reflection`
- `skill_version`: `1.2.0`
- ReflectionMemo schema: `1.1` ([references/reflection-memo-v1.1.schema.json](references/reflection-memo-v1.1.schema.json))
- Frozen predecessor: memo schema `1.0` from Skill `1.0.0`/`1.1.0` ([references/reflection-memo-v1.0.schema.json](references/reflection-memo-v1.0.schema.json)); documents written under it keep validating unchanged.

## Run

Use Python 3 and the standard library:

```bash
python3 scripts/reflect.py \
  --case /path/to/research-case.json \
  --output-dir /path/to/reflections \
  --write-updated-case
```

The command creates `CASE--reflection-vNNN.json` and, when requested, `CASE--case-after-reflection-vNNN.json`. It selects the next unused revision and refuses to overwrite either the input or an existing output.

## Workflow

1. Validate the required ResearchCase v1 structure.
2. Link feedback and experiments through hypothesis, evidence, and experiment IDs.
3. Detect support/challenge conflicts, negative/null/invalid outcomes, missing or unusable evidence, non-independent positive support, and repeated no-information outcomes.
4. Select an action with deterministic priority: conflict → `human_review`; invalid method → `rollback`; exhausted evidence → `stop_unresolved`; negative/dependent/stalled evidence → `reroute`; otherwise → `continue`.
5. Store every original hypothesis as `before_snapshot` in the memo.
6. Propose revisions separately. Increment a hypothesis revision only when its state or confidence changes.
7. Optionally write a deep-copied ResearchCase with the proposals, a new decision, and an orchestrator-compatible `extensions.latest_decision_state` marker. Never overwrite the source case.

## Interpretation rules

- Treat evidence as usable only when it is not `HYP`, is not rejected, and is machine-checked, human-checked, or explicitly conflicted.
- Count independence by distinct `independence_group`, not evidence-row count.
- When feedback targets a completed experiment and repeats that experiment's outcome, treat it as the experiment result's report and count the outcome once. Continue to count feedback that is independent of the experiment.
- Do not upgrade a hypothesis from positive feedback supported by fewer than two independent groups.
- Treat `null` as inconclusive and `invalid` as a method failure, not evidence against the hypothesis.
- Preserve missing references and rejected evidence as warnings; never silently drop them.
- Restrict actions to `continue`, `reroute`, `rollback`, `human_review`, and `stop_unresolved`.
- Never stop without saying what could come next. When a hypothesis has no
  usable supporting and no usable challenging evidence, record
  `proposed_next_actions`: a literature lookup naming the unadjudicated Han
  character candidates found in usable, non-`HYP` evidence (or the open
  question when there are none), and, while a raw image material is still
  registered, a wider re-derivation of the observed region.
- Every proposed action carries `authorization: proposal-only`. A memo names
  work for a human to choose; it never authorizes execution, changes a
  hypothesis, or relaxes a gate. Only an orchestrator route may make a Skill
  executable, and it refuses to while a gate blocks.

## Outputs

The ReflectionMemo contains `skill_id`, `skill_version`, a unique per-invocation `run_id`, its schema version, case ID, revision, timestamp, input SHA-256, feedback counts, triggered rules, evidence-independence summaries, complete before/after hypothesis snapshots, action, rationale, `proposed_next_actions`, and an input-preservation statement. The CLI summary repeats the same three invocation fields.

When `--write-updated-case` is used, the updated case retains the appended decision and records `extensions.latest_decision_state` with:

- `decision_id` for the latest decision.
- `decision_sha256`, computed from that decision as sorted, indented UTF-8 JSON with a trailing newline.
- `input_case_sha256`, bound to the original input file bytes.
- `activated_at`, equal to the updated case's `updated_at`.
- `collection_counts` for the updated `materials`, `hypotheses`, `experiments`, `evidence`, `claims`, `uncertainties`, `feedback`, and `decisions` arrays.

The marker is fresh only while its activation time and all collection counts still match the case. Existing extension fields are preserved. A `human_review` decision remains appended with `gate_status: block`; the marker does not bypass that gate.

Run tests with:

```bash
python3 -m unittest discover -s tests -v
```