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)
• Frozen predecessor: memo schema 1.0 from Skill 1.0.0/1.1.0 (references/reflection-memo-v1.0.schema.json); documents written under it keep validating unchanged.

Run

Use Python 3 and the standard library:

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:

python3 -m unittest discover -s tests -v