research-manager

name	research-manager
description	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).
user-invocable	true
argument-hint	[optional: hint about what happened this turn]
allowed-tools	Read, Write, Edit, Glob, Grep
metadata	{"author":"ara-commons","version":"2.1.0","tags":["research","process-recording","provenance","progressive-crystallization","knowledge-management"]}

Live Research Project Manager (Live PM)

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.

The Four-Stage Pipeline

┌──────────────────┐  ┌──────────────┐  ┌──────────────────┐  ┌──────────────────────┐
│Context Harvester │->│ Event Router │->│ Maturity Tracker │->│  Logic Layer         │
│ (extract what    │  │ (classify +  │  │ (crystallize on  │  │  Reconciliation      │
│  happened)       │  │  route)      │  │  closure signal) │  │  (reconcile current  │
│                  │  │              │  │                  │  │   state w/ this turn)│
└──────────────────┘  └──────────────┘  └──────────────────┘  └──────────────────────┘

Stage 1 — Context Harvester

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.
• Researcher directions expressed or confirmed: hypotheses, design choices, abandoned approaches, questions, affirmations, revisions.

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:

1. 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.

2. 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.

3. 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.

4. 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.

Crystallization procedure

When a signal fires for O{XX}:

1. Read O{XX}'s content, context, potential_type, provenance, bound_to.
2. Allocate the next ID for the target layer (read the target file first).
3. Construct a typed entry using the schema (see Schemas below). Carry forward provenance. Verbal-affirmation upgrades ai-suggested → user-revised (or user if reproduced verbatim). The other three signals do not upgrade provenance.
4. Add fields: Crystallized via: <signal>, From staging: O{XX}.
5. Establish forensic bindings (claim→proof, heuristic→code, decision→evidence). Use [pending] + TODO if a binding cannot be made now.
6. 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.

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 unresolved decision 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.

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

The logic layer (ara/logic/) is the current best understanding of the project — a clean specification of what we currently believe, not an archaeological record. Stage 4 reconciles it with this turn's events so it stays internally consistent and faithful to present evidence.

The trace layer (ara/trace/, ara/staging/) is append-only and immutable. All history of how the logic layer evolved — prior statements, status transitions, revision reasons — lives there. The logic file itself carries only the current snapshot plus a Last revised pointer back to the trace.

This stage operates only on already-crystallized entries in logic/. Staged observations belong to Stage 3.

What Stage 4 may do

1. Status updates — flip a claim's Status field when evidence warrants.
2. Content revisions — rewrite a Statement, Rationale, or definition when new evidence narrows scope, terminology changed, or wording no longer matches what's actually supported.
3. Structural changes — split a claim into two, merge duplicates, repair dependencies, rename ids when concepts are renamed.
4. Consistency pass — scan for broken cross-references (claim cites C05 which no longer exists), terminology mismatch with concepts.md, dependency loops.

Allowed status transitions

hypothesis ──► testing ──► supported
     │            │            ▲
     │            └──► weakened┘
     ├────────────────► refuted    (terminal, empirical)
     ├────────────────► withdrawn  (terminal, non-empirical)
     └─ any ─────────► revised    (Statement rewritten; reset to testing/hypothesis)

• 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:

1. 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
2. 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.
3. 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.
4. 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.
5. Terminology drift — a new concept added to concepts.md this turn refines or renames a term the entry uses. Update the wording for consistency.
6. 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):

1. 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.
2. Update - **Last revised**: YYYY-MM-DD (turn-id) on the entry.
3. For status flips, also update - **Status**: to the new value.
4. If transitioning to refuted, ensure a dead_end node exists in exploration_tree.yaml referencing the entry (create one if not).
5. 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.
6. 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.
7. 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 for current state (next IDs, claims, tree, staging).
2. Stage 1 — Context Harvester: scan this turn → list of candidate events.
3. Stage 2 — Event Router: for each candidate, per references/event-taxonomy.md:
     classify type, assign provenance, distill payload
     direct-route → write to target layer immediately
     staged-route → append to staging/observations.yaml
4. Stage 3 — Maturity Tracker:
     for each staged observation: check closure signals → crystallize if fired
     for each entry: check contradictions with this turn's events → flag if found
     for long-staged observations (3+ days idle): mark stale: true
5. Stage 4 — Logic Layer Reconciliation:
     for each crystallized entry in logic/ (claims, heuristics, concepts):
       check status signals → edit Status line if fired
       check content signals → rewrite Statement / Rationale / definition if reconciliation demanded
       check structural signals → split, merge, repair dependencies, fix terminology drift
     run cross-reference consistency pass (broken refs, renamed ids, terminology mismatch)
     record before/after of every change in today's session record (the logic file does not retain history)
     log near-miss signals (considered but rejected) to pm_reasoning_log.yaml
6. Append turn events to today's session record.
7. Update or append today's entry in trace/sessions/session_index.yaml.
8. Append a brief reasoning entry to trace/pm_reasoning_log.yaml (self-continuity).
9. 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)
    problem.md
    claims.md                       #   Falsifiable assertions + proof refs (current snapshot only)
    concepts.md
    experiments.md
    solution/
      architecture.md
      algorithm.md
      constraints.md
      heuristics.md                 #   Tricks + rationale + sensitivity
    related_work.md
  src/                              # How (code artifacts)
    configs/
    kernel/
    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
    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.

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
    children:
      - { ... }

Claim (logic/claims.md) — crystallized only

## C{XX}: {title}
- **Statement**: {current falsifiable assertion}
- **Status**: hypothesis | untested | testing | supported | weakened | refuted | withdrawn
- **Provenance**: user | ai-suggested | user-revised
- **Falsification criteria**: {what would disprove this}
- **Proof**: [{evidence refs or "pending"}]
- **Dependencies**: [C{YY}, ...]
- **Tags**: {comma-separated}
- **Last revised**: YYYY-MM-DD (turn-id)   # pointer back to the trace; absent until first revision

The claim file is a current-state snapshot. It carries no history — no prior statements, no status transition log, no From staging pointer, no Crystallized via note. All of that lives in the trace:

• Original crystallization: trace/sessions/YYYY-MM-DD_NNN.yaml (turn where the claim was promoted) and staging/observations.yaml (the source observation, still flagged promoted: true).
• Every subsequent edit: trace/sessions/YYYY-MM-DD_NNN.yaml under logic_revisions: with full before/after, signal, and provenance.
• Reasoning for each edit: trace/pm_reasoning_log.yaml.

refuted and withdrawn are terminal — once set, the claim is not edited further except via an explicit revival by the user (which reopens it through a revised transition and settles to testing or hypothesis). revised itself is a transition marker, not a resting state: after the revision is recorded in the trace, Status settles back to a working value.

Heuristic (logic/solution/heuristics.md) — crystallized only

## H{XX}: {title}
- **Rationale**: {current best explanation of why this works}
- **Status**: active | weakened | retired
- **Provenance**: user | ai-suggested | user-revised
- **Sensitivity**: low | medium | high
- **Code ref**: [{file paths}]
- **Last revised**: YYYY-MM-DD (turn-id)   # absent until first revision

Same principle as claims: current-state snapshot only, no From staging or Crystallized via clutter. Crystallization and revision history live 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}"

Session Index (trace/sessions/session_index.yaml)

sessions:
  - id: "YYYY-MM-DD_NNN"
    date: "YYYY-MM-DD"
    summary: "{main outcome}"
    turn_count: {N}
    events_count: {N}
    claims_touched: [C{XX}, ...]
    open_threads: {N}

Reasoning Log (trace/pm_reasoning_log.yaml) — self-continuity

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."

Initialization (if ara/ does not exist)

Create the structure on the first turn that contains research-significant activity. Do not ask unprompted on a purely conversational opener.

mkdir -p ara/{logic/solution,src/{configs,kernel},trace/sessions,evidence/{tables,figures},staging}

Seed:

1. ara/PAPER.md — root manifest (infer title, authors, venue from project context)
2. ara/trace/sessions/session_index.yaml — sessions: []
3. ara/trace/exploration_tree.yaml — tree: []
4. ara/trace/pm_reasoning_log.yaml — entries: []
5. ara/staging/observations.yaml — observations: []
6. ara/logic/claims.md — # Claims
7. ara/logic/problem.md — # Problem
8. ara/logic/solution/heuristics.md — # Heuristics
9. ara/evidence/README.md — # Evidence Index

Then run the per-turn procedure normally.

Briefing (fresh conversation only)

On the first turn of a new conversation (not every turn), silently read:

• latest session record's summary, open_threads, ai_suggestions_pending, key_context
• claims.md status counts
• 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.

Rules

1. Never run mid-turn. Per-turn epilogue only.
2. Never fabricate events. Only log what actually happened or was discussed.
3. Stage by default for interpretive events. Claims, heuristics, concepts, constraints, architecture statements are staged first.
4. Never crystallize without a closure signal. No counter, no LM-judged maturity — only abandonment / affirmation / resolution / commitment.
5. Never auto-upgrade provenance. ai-suggested stays until explicit user affirmation.
6. Stage 4 reconciles the logic layer; default to no change. Status flips, content rewrites, splits/merges, and consistency repairs are allowed but require an explicit signal from this turn. Log near-misses. Terminal states (refuted, withdrawn) need explicit triggers — never reach them by silence or staleness.
7. Logic layer is a current-state snapshot. Each edit overwrites the prior value in logic/. The before/after lives in the trace, not in the logic file. Never carry a Previous statement line or status history in claim entries.
8. Trace and staging are append-only. Never edit prior entries in trace/sessions/, trace/pm_reasoning_log.yaml, trace/exploration_tree.yaml, or staging/observations.yaml except to set forward-reference pointers (e.g. promoted: true, promoted_to:, appending to today's events). Existing content is never rewritten.
9. Never silently overwrite contradictions. Flag both, append unresolved decision node, defer.
10. Always read existing files first. Get correct next IDs, avoid duplicates.
11. Establish forensic bindings. claim→proof, heuristic→code, decision→evidence. Use [pending] + TODO if not yet bindable.
12. Every logic-layer edit gets a logic_revisions: entry in the session record with full before/after. This is the only place pre-edit content is preserved.
13. Skip empty turns. No record for greetings, ack, pure formatting.
14. Keep YAML valid. Validate structure mentally before writes.
15. Be terse in the summary line. One line per turn, factual, no narration.