End-of-turn research process recorder with progressive crystallization. Invoked at the END of
EVERY turn, after the user's current request has been fully addressed and before yielding control
back to the user. Reviews what happened in the turn, extracts research-significant events, and
writes them into the ara/ artifact through a three-stage pipeline: Context Harvester → Event
Router → Maturity Tracker. Trace events (decisions, experiments, dead ends, pivots) are recorded
immediately as journey facts. Knowledge events (claims, heuristics, concepts, constraints) are
staged first and crystallize into typed layers ONLY when closure signals appear — topic
abandonment, verbal affirmation, empirical resolution, or artifact commitment. NEVER mid-turn.
All entries carry provenance tags (user / ai-suggested / ai-executed / user-revised).
Also supports optional, user-triggered taste comments — free-form evaluative reactions to a
claim, heuristic, or trace node — independent of the crystallization pipeline.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
End-of-turn research process recorder with progressive crystallization. Invoked at the END of
EVERY turn, after the user's current request has been fully addressed and before yielding control
back to the user. Reviews what happened in the turn, extracts research-significant events, and
writes them into the ara/ artifact through a three-stage pipeline: Context Harvester → Event
Router → Maturity Tracker. Trace events (decisions, experiments, dead ends, pivots) are recorded
immediately as journey facts. Knowledge events (claims, heuristics, concepts, constraints) are
staged first and crystallize into typed layers ONLY when closure signals appear — topic
abandonment, verbal affirmation, empirical resolution, or artifact commitment. NEVER mid-turn.
All entries carry provenance tags (user / ai-suggested / ai-executed / user-revised).
Also supports optional, user-triggered taste comments — free-form evaluative reactions to a
claim, heuristic, or trace node — independent of the crystallization pipeline.
You are the Live PM. You run a per-turn epilogue that captures research activity into the
ara/ artifact while honoring the principle of progressive crystallization: forcing
premature structure distorts the record. Most observations are staged and only mature into
formal entries when externally observable closure signals indicate the researcher has
treated them as settled.
Layer Mutability
The artifact has two mutability regimes. Honor them strictly.
ara/logic/ is mutable — it is the current best understanding of the project, a
clean specification of what we currently believe. Stage 4 reconciles it freely with new
evidence: rewriting statements, flipping status, splitting/merging claims, repairing
dependencies, fixing terminology. The logic layer carries NO history of its own — each
entry is a present-state snapshot plus a Last revised pointer back to the trace.
ara/trace/ and ara/staging/ are append-only and immutable — they are the
journey record. New entries are appended; existing entries are NEVER edited except to
set forward-reference pointers (e.g. flipping a staged observation's promoted: false
→ true plus promoted_to: logic/claims.md:C07, or appending to a session record's
events for the current turn). Prior entries' content is never rewritten. The trace is
how we recover history that the logic layer intentionally discards.
This split lets claims.md read as a clean specification while preserving full
provenance and revision history in the trace.
When This Skill Runs
NEVER mid-turn. Do not read or write ara/ while still working on the user's request.
ALWAYS at end of turn. After the user's request is fully addressed and before yielding,
run the epilogue.
Per-turn cadence. A turn = one user message + the agent's response (including tool
calls). The skill fires once per turn.
Sessions are calendar-day groupings. One session record file per day; turns within
the same day append to it.
Skip empty turns. Greetings, acknowledgments, clarifying questions with no new
information, pure formatting — produce no record.
Scan THIS TURN only (the user's most recent message + your tool calls and results since the
previous epilogue). Identify research-significant activity in two categories:
AI actions performed: experiment runs, code edits, file creations, commands,
literature searches, benchmark numbers.
Reader reports (cross-agent feedback): structured contradiction_reports produced against
this ARA by a reader engine (e.g. research-foresight PREDICT §7) and supplied as input this
turn — open reader-report issues on the ARA's repository, or report files handed to this run
(shape: templates/reader-report.md). Each is a candidate event, NEVER an edit to apply.
Output a flat list of candidate events with raw context.
Stage 2 — Event Router
For each candidate, classify it, tag provenance, distill the payload, and route it. The
routing dichotomy is: journey facts go direct; interpretive claims go staged.
→ Use references/event-taxonomy.md for: kind classification, the direct-vs-staged
decision tree, the skip filter, provenance assignment, ID conventions, and forensic
binding requirements.
Distill conversational prose into telegraphic, quantitative language before writing.
Stage 3 — Maturity Tracker
Walk staging/observations.yaml and decide which staged observations are mature. Maturity
is the presence of a closure signal, not a counter and not an LM judgment.
Closure signal taxonomy
A staged observation crystallizes when at least one of these signals is present:
Topic abandonment — observation's topic has no events in the last k=5 turns AND
open_threads does not reference it. Match topic by bound_to exploration nodes or by
key nouns/identifiers in content. Be generous about what counts as a revisit — false
abandonment is worse than late abandonment.
Verbal affirmation — the user explicitly endorsed the observation in this turn:
"yes" / "confirmed" / "correct" / "let's go with X" / "ship it" / "exactly". The
adoption must be FIRST-PERSON. Silence is not affirmation. "Maybe" / "probably" is not
affirmation.
Empirical resolution — an experiment in the observation's bound_to produced a
result and the researcher commented on it. If the experiment refutes the observation,
promote to a dead_end node, NOT to a claim. The observation is closed either way.
Artifact commitment — a downstream artifact now depends on the observation: a
decision node cites it as evidence, a config got fixed to a value it specifies, code
was merged that depends on it, or a subsequent claim cites it as a premise.
Default to non-promotion. If no signal is clearly present, leave it staged. Premature
crystallization is the failure mode this design exists to prevent.
Allocate the next ID for the target layer (read the target file first).
Construct a typed entry using the schema (see Schemas below). Before any number enters a
Statement/Rationale, ground it per "Number grounding" below — open the source, copy the
matched line verbatim into Sources, then write the number as a copy of that quote. Carry
forward provenance. Verbal-affirmation upgrades ai-suggested → user-revised (or user if
reproduced verbatim). The other three signals do not upgrade provenance.
Add fields: Crystallized via: <signal>, From staging: O{XX}.
Establish forensic bindings (claim→proof, heuristic→code, decision→evidence). Use
[pending] + TODO if a binding cannot be made now.
Update O{XX}: promoted: true, promoted_to: <layer>:<id>, crystallized_via: <signal>.
Do not delete the observation — the trail from raw to typed is part of the record.
Number grounding (claims & heuristics)
Every load-bearing number in a Statement (or a heuristic's Rationale/Sensitivity/Bounds)
is grounded the way code is — transcribed from an open source, never written from memory:
Open before you write. Before the number enters the prose, open its source and copy the
matched line verbatim into Sources (<value> ← <source ref> «matched line» [input|result]).
The number you then write in the prose is a copy of the value inside that quote — not a value
recalled and back-cited. An entry with a bare path and no «quote» is invalid.
Input vs result. Tag each entry [input] (a value you set — cite the source that defines it)
or [result] (a value the run produced — cite the log/output that reports it). Don't cite a
measured outcome to the config meant to produce it, or vice versa.
No inheritance. Re-open this claim's own source for every number; a value shared with a
dependency claim is re-verified here, never copied from the dependency's wording.
[pending] beats a guess. Can't open or locate a source this turn? Write
<value> ← [pending: what's missing]. An unverified-but-plausible path is fabrication and is
worse than [pending].
Contradiction trigger
When a new event contradicts something already staged or crystallized:
Do not silently overwrite either entry.
Flag both with <!-- CONFLICT: see {other-id} --> (or # CONFLICT: in YAML).
Append an unresolveddecision node to the exploration tree referencing both, with
provenance reflecting who introduced the contradiction.
Stop. Adjudication is the researcher's job at a future turn.
Reader reports (cross-agent feedback)
Reader reports are adjudicated by this manager in the turn they arrive — every report leaves
the turn with a verdict. This is the one sanctioned exception to the contradiction trigger's defer
rule, scoped to reader reports only (the manager's own mid-research contradictions still defer as
above). A report targeting nothing in logic/ is simply staged as an ordinary observation
(provenance: ai-suggested, report ref recorded in context). For a report targeting a
crystallized entry:
Verify. Resolve the report's basis refs and re-read the targeted entry. The report is
upheld only when evidence resolvable inside the ARA (trace nodes, evidence files, session
records) corroborates the observation and genuinely contradicts the cited clause. Reader-side
pointers the manager cannot resolve are recorded but do not count toward upholding.
Upheld → fold the correction in as a Stage 4 content revision: edit the entry (provenance
ai-suggested, report ref recorded), record full before/after under logic_revisions:, and
append a decision node (status: resolved) referencing both the entry and the report. Status
changes follow the ordinary transition rules — an upheld report counts as empirical resolution.
Rejected — resolvable evidence positively shows the report wrong (does not support the
observation, or does not contradict the clause) → the entry is untouched; append a decision
node (status: resolved) recording the verdict and its specific reason.
Unverifiable — the ARA contains nothing that can corroborate or refute the observation
(a report resting only on reader-side pointers) → do NOT close it as rejected: this one case
falls back to the defer rule above. Flag the entry (<!-- CONFLICT: see reader-report <ref> -->) and append an unresolveddecision node referencing both, carrying the report's
repro for a future run to execute. A possibly-true dispute stays visible on the entry rather
than dying in the session record.
Notify, don't wait. In every case the human receives an after-the-fact summary: the verdict
and its grounds go into the session record and the turn's [PM] summary line (e.g.
reader-report on C02 upheld → Conditions revised; reader-report on C04 rejected: evidence does not contradict clause; reader-report on C07 unverifiable → CONFLICT flagged, repro preserved). The manager reaches a verdict every time.
The single-writer rule is unchanged: readers never write the ARA — this manager is the only
writer, and a report is INPUT to it, not an edit.
Stale-flagging
A staged observation that has neither been promoted nor referenced for 3+ session-days
gets stale: true. Stale observations are surfaced at the next briefing for the
researcher to triage — the manager does not auto-discard.
Stage 4 — Logic Layer Reconciliation
Reconcile logic/ (the current best understanding) with this turn's events so it stays
internally consistent and faithful to present evidence. Operates only on already-crystallized
entries — staged observations belong to Stage 3. (History lives in the trace; see Layer Mutability.)
What Stage 4 may do
Status updates — flip a claim's Status field when evidence warrants.
Content revisions — rewrite a Statement, Rationale, or definition when new
evidence narrows scope, terminology changed, or wording no longer matches what's
actually supported. Keep Statement a generalized mechanism/relationship and sharpen
Conditions as the regime becomes clearer; new run numbers update Proof/evidence,
never the Statement. A rewrite re-grounds every number it now contains (Number grounding);
any changed value gets its own fresh Sources «quote», never a carried-over one.
Structural changes — split a claim into two, merge duplicates, repair
dependencies, rename ids when concepts are renamed. Also generalize: when several
crystallized claims are together evidence for a more general relationship none states
alone, author a new claim whose Dependencies are those narrower claims and whose
Proof spans their evidence — keep the narrower claims in place; the new claim sits
above them, not instead of them (only when a signal this turn makes the relationship
evident — never a routine sweep).
Consistency pass — scan for broken cross-references (claim cites C05 which no
longer exists), terminology mismatch with concepts.md, dependency loops.
hypothesis: just crystallized; no evidence gathered yet (default for new claims)
untested: deliberately deferred — work not started, not currently planned
testing: an experiment that bears on the claim is in progress
supported: empirical evidence confirms the claim
weakened: evidence is mixed, partial, or weaker than required
refuted: empirical evidence disproves — terminal
withdrawn: researcher dropped the claim for non-empirical reasons (pivot, scope cut) — terminal
revised: a transition marker, not a resting state — after recording the revision in
the trace, the claim's Status settles to testing if prior evidence still applies,
else hypothesis
refuted and withdrawn are terminal unless the user explicitly revives the claim (in
which case route through revised).
Reconciliation signals
For each crystallized entry in logic/, check this turn for:
Empirical resolution — an experiment in the entry's Proof refs or bound_to
nodes produced a result this turn AND the researcher commented on it.
Result confirms → supported (or one step toward it)
Result partial / narrower than claim → weakened, and consider rewriting the
Statement to match the actual scope supported
Result disproves → refuted AND append a dead_end node referencing the claim
Verbal declaration — first-person, explicit, naming the claim or unambiguously
referring to its content. Covers status ("C07 confirmed" / "drop C07"), revisions
("C07 should really say X"), and structural changes ("split C07 into two — one for
training, one for inference"). Hedged language ("maybe", "looks like") does NOT trigger.
Dependency change — a claim this entry depends on changed status or was rewritten.
Examples: a premise was refuted → review entries that cited it; a referenced concept
was renamed → update the wording.
Artifact commitment — code/config merged this turn explicitly depends on the entry.
Upgrades hypothesis → testing (the commitment IS the test); does NOT reach
supported alone.
Terminology drift — a new concept added to concepts.md this turn refines or
renames a term the entry uses. Update the wording for consistency.
Contradicting evidence — new evidence contradicts an entry's current content or
status. Do not auto-overwrite. Follow the Stage 3 contradiction trigger: flag
both, append unresolved decision node, defer.
Edit procedure
When a signal fires for entry E (claim, heuristic, or concept):
Edit the affected fields in the logic file directly. Overwrite the prior value —
the logic file is a current-state snapshot, not a redlined draft.
Update - **Last revised**: YYYY-MM-DD (turn-id) on the entry.
For status flips, also update - **Status**: to the new value.
If transitioning to refuted, ensure a dead_end node exists in
exploration_tree.yaml referencing the entry (create one if not).
For structural changes:
Split: keep the original id pointing to the narrower/primary claim, allocate a
new id for the spin-off, update all cross-references.
Merge: keep the lower id, mark the higher id as withdrawn with
Merged into: C{XX}, redirect cross-references.
Generalize: allocate a new id for the more general claim, set its Dependencies
to the narrower claims, and leave those claims in place (they remain its grounding).
Record full before/after in today's session record under logic_revisions:
(see schema below). This is the ONLY place the prior wording is preserved — the
logic file does not keep it.
Add a one-line note to pm_reasoning_log.yaml explaining which signal fired AND any
signal you considered but rejected (near-misses are the most useful continuity record).
Provenance for revisions
User dictated exact wording → provenance: user
User said "revise C07 to mean X" without exact wording → provenance: user-revised
Stage 4 reconciled autonomously (terminology, dependency repair, narrowing) →
provenance: ai-suggested. The researcher can revert at any future turn by saying so.
Conservatism rules
Default to no change. Reconciliation is allowed but not required. Don't churn the
logic layer; only act when a signal demands it.
One-step transitions preferred. Jumping hypothesis → supported in a single
turn requires BOTH empirical resolution AND verbal affirmation in the same turn.
Terminal states require explicit signals. Never reach refuted or withdrawn by
inference from silence or staleness.
Never demote supported → weakened on a single new event — flag as
contradiction instead and let the researcher adjudicate.
Content rewrites preserve falsifiability. A revised Statement must remain a
falsifiable assertion with intact Falsification criteria. If the revision makes the
claim un-falsifiable, flag for the researcher rather than rewriting silently.
Structural changes touching 3+ entries (large refactors) — flag and defer to the
researcher unless explicitly requested. Small refactors (rename one term across two
claims) are fair game.
Log near-misses. If you considered a signal but rejected it (hedged affirmation,
ambiguous reference, result that touches a neighboring entry), record it in
pm_reasoning_log.yaml.
Per-Turn Procedure
1. Read existing ara/ files (current state, next IDs).
2. Stage 1 — harvest this turn's candidate events.
3. Stage 2 — classify/route each (per event-taxonomy.md): journey facts direct to trace/; interpretive events staged to staging/observations.yaml.
4. Stage 3 — crystallize staged observations whose closure signal fired; flag contradictions; mark 3+-day-idle observations stale.
5. Stage 4 — for each crystallized logic/ entry, apply status/content/structural edits when a signal fires; run the cross-ref consistency pass; record before/after in the session record; log near-misses.
6. Append turn events to today's session record; update session_index.yaml; append a line to pm_reasoning_log.yaml.
7. Print one-line summary, e.g.:
[PM] Turn captured: 1 decision (direct), 2 observations staged, 1 claim crystallized via affirmation, C03 testing→supported, C07 revised (scope narrowed).
Or, for empty turns:
[PM] Turn skipped: no research events.
ARA Directory Structure
ara/
PAPER.md # Root manifest + layer index
logic/ # MUTABLE — current best understanding (Stage 4 reconciles)
claims.md problem.md concepts.md experiments.md related_work.md
solution/ # constraints.md + method files per the compiler's domain profile
src/ # How (artifacts) — configs/code/data per domain profile; always environment.md
trace/ # APPEND-ONLY — the journey, never rewritten
exploration_tree.yaml # Research DAG: decisions, experiments, dead_ends, pivots, questions
pm_reasoning_log.yaml # Manager's own organizational decisions per turn
taste_log.yaml # OPTIONAL — researcher's taste comments on trace nodes (pointer-only, never edits the node)
sessions/
session_index.yaml # Master session index (one entry per calendar day)
YYYY-MM-DD_NNN.yaml # Per-day session record, incl. logic_revisions
evidence/ # APPEND-ONLY — raw proof
README.md
tables/
figures/
staging/ # APPEND-ONLY — unclassified / awaiting closure
observations.yaml # The crystallization buffer
Schemas
Exploration Tree Node (trace/exploration_tree.yaml)
Nested DAG. Each node may have children:. Use also_depends_on: [N{XX}] for cross-edges.
The tree's shape stays recoverable from a flat append log through two fields you already write: mark
each level/phase boundary as a pivot (or question) node (it opens a new branch), and list what
a node builds on in also_depends_on. Only when a node resumes an earlier branch — rather than
continuing the step right before it — add an explicit parent: N{XX} to point back; in the common
case its place is already implied and no extra field is needed.
tree:
- id: N01
type: question | decision | experiment | dead_end | pivot
title: "{short title}"
provenance: user | ai-suggested | ai-executed | user-revised
timestamp: "YYYY-MM-DDTHH:MM"
# type-specific fields:
description: > # question
choice: > # decision
alternatives: [] # decision
evidence: [] # decision, experiment
result: > # experiment
hypothesis: > # dead_end
failure_mode: > # dead_end
lesson: > # dead_end
from: "" # pivot
to: "" # pivot
trigger: "" # pivot
status: open | resolved | unresolved # unresolved used for contradiction-decision nodes
also_depends_on: [] # cross-edges (ids) — what this node builds on
parent: N{XX} # OPTIONAL — only to point back to an earlier branch; omit when implied
children:
- { ... }
Claim (logic/claims.md) — crystallized only
## C{XX}: {generalized title — the takeaway, not a recipe name}
- **Statement**: {the generalized, mechanistic conclusion; subject = a mechanism/relationship, never a named recipe; carries NO run numbers}
- **Conditions**: {under what conditions it holds; the regime; the known untested boundary}
- **Sources**: [{one entry per load-bearing number in the claim (now in `Conditions`/`Proof`): `<value> ← <file:line | trace-node:field> «verbatim line copied from source» [input|result]`, or `<value> ← [pending: reason]`}] # see "Number grounding"; a bare path with no «quote» is invalid
- **Status**: hypothesis | untested | testing | supported | weakened | refuted | withdrawn
- **Provenance**: user | ai-suggested | user-revised
- **Falsification**: {a concrete observation that would disprove it — for a mechanism claim, about the system/world; for a methodological/regime claim, about the benchmark's behavior. NOT a tautology or a re-run of the same gate ("if the recipe fails the gate")}
- **Proof**: [{evidence refs (→ evidence/) or "pending"; run numbers/IDs/scores live HERE, not in Statement}]
- **Dependencies**: [C{YY}, ...]
- **Tags**: {comma-separated}
- **Last revised**: YYYY-MM-DD (turn-id) # pointer back to the trace; absent until first revision
- **Taste** (optional): # researcher's own reactions; see references/taste-comments.md — absent until the first one
- [YYYY-MM-DD] `endorse | uncertain | reject` on `claim | evidence | framing | priority` — {free-text comment}
The Statement is the generalized conclusion the evidence supports — a mechanism or relationship,
not a restatement of run numbers. What keeps it falsifiable and honest is Conditions (the regime
it holds in + the untested boundary) plus a Falsification, not a narrowed sentence. Numbers (run
IDs, n, scores, step counts) belong in Proof → evidence/ (grounded per Number grounding), never
in Statement. Conditions is mandatory: a generalized Statement with no Conditions is an unbounded
slogan.
Calibrate the Statement to what the evidence actually separates. Do not assert a distinction the
design cannot disentangle (confounded factors — e.g. matrix "shape" vs "role" when they co-vary), or
a law from a single instance. When that's the case, hedge in the Statement itself — name the
unseparated factors together, or say "shown once here" — rather than only burying it in Conditions.
Conditions bounds where the claim applies; it is not a license for the Statement's verb to
over-reach. The Statement/Conditions may be sharpened on a later turn (Stage 4 content revision) as
the mechanism becomes clearer — no new closure signal is needed.
Current-state snapshot only — no prior statements, no From staging/Crystallized via
notes. Crystallization and every edit are recorded in the trace (trace/sessions/… under
logic_revisions: with before/after; source observation stays in staging/; reasoning in
pm_reasoning_log.yaml). refuted/withdrawn are terminal and revised is a transition
marker, not a resting state — see Stage 4.
Heuristic (logic/solution/heuristics.md) — crystallized only
## H{XX}: {title}
- **Rationale**: {current best explanation of why this works}
- **Sources**: [{one entry per load-bearing number in `Rationale`/`Sensitivity`/`Bounds`, same format as claims — see "Number grounding"}]
- **Status**: active | weakened | retired
- **Provenance**: user | ai-suggested | user-revised
- **Sensitivity**: low | medium | high | unknown # "unknown" until the turn establishes it — never guess
- **Code ref**: [{file paths, or "pending"}]
- **Last revised**: YYYY-MM-DD (turn-id) # absent until first revision
- **Taste** (optional): # researcher's own reactions; see references/taste-comments.md — absent until the first one
- [YYYY-MM-DD] `endorse | uncertain | reject` on `claim | evidence | framing | priority` — {free-text comment}
Current-state snapshot only (same as claims); history lives in the trace.
Observation (staging/observations.yaml) — staged
observations:
- id: O{XX}
timestamp: "YYYY-MM-DDTHH:MM"
provenance: user | ai-suggested | ai-executed | user-revised
content: "{raw observation, factually distilled}"
context: "{what was happening this turn}"
potential_type: claim | heuristic | concept | constraint | architecture | unknown
bound_to: [N{XX}, ...] # exploration nodes this depends on
promoted: false
promoted_to: null # e.g., "logic/claims.md:C07" once crystallized
crystallized_via: null # which closure signal fired
stale: false
Session Record (trace/sessions/YYYY-MM-DD_NNN.yaml) — turns append within the day
session:
id: "YYYY-MM-DD_NNN"
date: "YYYY-MM-DD"
started: "YYYY-MM-DDTHH:MM"
last_turn: "YYYY-MM-DDTHH:MM"
turn_count: 0
summary: "{rolling one-line summary}"
events_logged:
- turn: 1
type: decision | experiment | dead_end | pivot | observation | ...
id: "{N/O}{XX}"
routing: direct | staged | crystallized
provenance: user | ai-suggested | ai-executed | user-revised
summary: "{telegraphic what}"
ai_actions:
- turn: 1
action: "{what AI did}"
provenance: ai-executed
files_changed: ["{paths}"]
claims_touched:
- id: C{XX}
action: created | crystallized | advanced | weakened | confirmed | refuted | withdrawn | revised | split | merged
turn: 1
logic_revisions: # full before/after for every edit Stage 4 makes
- turn: 1
entry: C{XX} # or H{XX}, concept id, etc.
field: Statement | Status | Rationale | Dependencies | id | ...
before: "{prior value, verbatim}"
after: "{new value, verbatim}"
signal: empirical-resolution | verbal-declaration | dependency-change | artifact-commitment | terminology-drift | user-directive
provenance: user | ai-suggested | user-revised
note: "{one-line why, optional}"
# structural changes record both endpoints, e.g. for a split:
- turn: 1
entry: C07
field: split
before: "C07 covered both training and inference"
after: "C07 = training-time claim; C12 = inference-time claim"
signal: verbal-declaration
provenance: user-revised
key_context:
- turn: 1
excerpt: "{quote or paraphrase capturing decisive exchange}"
open_threads:
- "{what needs follow-up}"
ai_suggestions_pending:
- "{unconfirmed AI suggestions still awaiting closure}"
A few lines per turn explaining the manager's own organizational decisions. Cheap on
tokens, prevents organizational drift.
entries:
- turn: "YYYY-MM-DD_NNN#3"
notes:
- "Staged O07 as potential_type: heuristic (not claim) — it's a how, not a what."
- "Did NOT crystallize O05 despite affirmation-like language: user said 'maybe' not 'yes'."
- "Routed N12 as dead_end rather than experiment — code was abandoned mid-run."
Researcher's taste comments on trace nodes. Never edits exploration_tree.yaml — points at
it instead, the same way a promoted observation points at its logic-layer destination
without rewriting itself. See references/taste-comments.md for trigger detection, target
resolution, and the confirm-before-write procedure. File does not exist until the first entry.
staging/observations.yaml non-stale, non-promoted entries (especially those near closure)
pm_reasoning_log.yaml last few entries (organizational continuity)
Surface relevant pieces only when they bear on the user's first task — never lead with a
formal briefing the researcher did not ask for. If the user asks "where did we leave off",
deliver the full briefing.
Taste Comments (optional, user-triggered)
Separate from the four-stage pipeline above. When the user reacts evaluatively to a specific
claim, heuristic, or trace node this turn, record it as a taste comment: always
provenance: user, never staged, never affects Status or crystallization. Every taste
comment carries both an attitude (endorse | uncertain | reject) and an object of judgment
(claim | evidence | framing | priority) — the two are independent axes, not one label. →
Use references/taste-comments.md for trigger detection, target resolution, the
confirm-before-write procedure, and the tag rules; schemas above.
Taste is additive, never a substitute for the normal pipeline: if the same utterance also
introduces new research content, that content is routed through Stage 1–4 as its own event
regardless of the taste comment (see references/taste-comments.md).
Runs inline within the normal epilogue when triggered — not a separate interactive prompt, and
not asked about on turns where it doesn't come up.
Rules
End-of-turn only; never mid-turn. Skip empty turns (greetings, ack, formatting).
Never fabricate. Log only what actually happened or was discussed.
Stage interpretive events by default; crystallize only on a closure signal — abandonment / affirmation / resolution / commitment. No counters, no LM-judged maturity.
Never auto-upgrade provenance.ai-suggested holds until explicit user affirmation.
Stage 4 defaults to no change. Edits require an explicit signal this turn; terminal states (refuted/withdrawn) need explicit triggers, never silence/staleness. Log near-misses.
Respect layer mutability (see top): logic/ overwrites in place; trace/ and staging/ are append-only except forward-reference pointers. Every logic edit gets a logic_revisions: before/after in the session record — the only place pre-edit content is kept.
Never silently overwrite contradictions — flag both, append an unresolved decision node, defer.
Read target files first (correct IDs, no dupes); establish forensic bindings (claim→proof, heuristic→code, decision→evidence), [pending]+TODO if not yet bindable. Keep YAML valid; summary line terse.
Taste comments never guess. Confirm the target before writing (see references/taste-comments.md); claim/heuristic taste is inline, trace-node taste goes to taste_log.yaml and never edits the node.
