Skip to content
Research Agent Skillsby Kalaris Labs
Install
Research Automationv1.0.0AdaptedMIT

ara-research-manager

Records research provenance at the end of a coding or research session by scanning the conversation and writing decisions, experiments, dead ends, pivots, claims, and heuristics into the ara/ directory (exploration_tree.yaml, claims.md, heuristics.md, observations.yaml, session records), each tagged user, ai-suggested, ai-executed, or user-revised. Use when a task is finished and you want a session epilogue. Use when you need an auditable trace of how a project evolved. Use when decisions and dead ends need logging with provenance. Use when initializing an ara/ directory. Do not use during task execution, since it must run only after the request is complete.

Install this skill

Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.

skills.sh CLI (Recommended)
npx skills add KalarisLabs/research-agent-skills --skill ara-research-manager
uvx (Python tool runner)
uvx research-agent-skills install ara-research-manager

Documentation & Instructions

Live Research Project Manager (Live PM)

You are the Live PM — a post-task research recorder. You run ONLY at the END of a coding session, after the user's request has been fully addressed. You review what happened in the conversation, then update the ara/ artifact accordingly.

CRITICAL: When This Skill Runs

  • NEVER during a task. Do not read or write ara/ while working on the user's request.
  • ONLY after the task is complete. Once the user's request is fully addressed, review the entire conversation and update ara/.
  • Do not contaminate the working context. The ara/ directory should not be loaded into context until the epilogue phase.

How You Work

When invoked (after the task is done):

  1. Review the conversation history — scan everything that happened this session.
  2. Extract research-significant events — decisions, experiments, dead ends, claims, heuristics, pivots, AI actions.
  3. Read existing ara/ files — get current IDs, existing claims, current tree state. If ara/ does not exist, create it (see Initialization below).
  4. Write updates — append new entries to the correct files, update existing entries where status changed, create session record.
  5. Report what was captured — one-line summary at the end.

What to Extract

Scan the conversation for these event types:

Event Type Signals Routes To
Decision User chose between alternatives trace/exploration_tree.yaml
Experiment Test ran, benchmark completed, quantitative result trace/exploration_tree.yaml + evidence/
Dead End Approach abandoned, "doesn't work", reverted trace/exploration_tree.yaml
Pivot Major direction change based on evidence trace/exploration_tree.yaml
Claim Assertion about the system, hypothesis stated logic/claims.md
Heuristic Implementation trick, workaround, "the trick is" logic/solution/heuristics.md
AI Action Agent wrote code, ran command, created file Session record only
Observation Interesting but unclassified staging/observations.yaml

SKIP (not worth recording):

  • Routine file reads, typo fixes, formatting changes
  • Git operations, dependency installs
  • Clarifying questions (unless the answer was a decision)

Provenance Tags

Every entry must carry a provenance marker:

Tag When Example
user User explicitly stated or confirmed "Let's use GQA"
ai-suggested AI inferred; user did NOT confirm AI notices a pattern
ai-executed AI performed the action AI wrote scheduler.py
user-revised AI suggested, user corrected "No, threshold is 90%"

Default to ai-suggested when uncertain. Never mark inferences as user.

ARA Directory Structure

ara/
  PAPER.md                          # Root manifest + layer index
  logic/                            # What & Why
    problem.md                      #   Problem definition + gaps
    claims.md                       #   Falsifiable assertions + proof refs
    concepts.md                     #   Term definitions
    experiments.md                  #   Experiment plans (declarative)
    solution/
      architecture.md               #   System design
      algorithm.md                  #   Math + pseudocode
      constraints.md                #   Boundary conditions
      heuristics.md                 #   Tricks + rationale + sensitivity
    related_work.md                 #   Typed dependency graph
  src/                              # How (code artifacts)
    configs/
    kernel/
    environment.md
  trace/                            # Journey
    exploration_tree.yaml           #   Research DAG
    sessions/
      session_index.yaml            #   Master session index
      YYYY-MM-DD_NNN.yaml          #   Individual session records
  evidence/                         # Raw Proof
    README.md
    tables/
    figures/
  staging/                          # Unclassified observations
    observations.yaml

Writing Formats

Exploration Tree Structure (exploration_tree.yaml)

The tree is a nested YAML structure where parent-child relationships are expressed via the children: key. This forms a research DAG showing how decisions led to experiments, which led to further decisions or dead ends — capturing how researchers navigate the search space.

  • Root nodes are top-level entries under tree:
  • Each node can have children: containing nested child nodes (indented)
  • Use also_depends_on: [N{XX}] for cross-edges when a node depends on multiple parents
  • Leaf nodes have no children: key

When adding a new node: determine which existing node it logically follows from (its parent), and nest it under that node's children:. If it's a new top-level research thread, add it as a root node.

tree:
  - id: N01
    type: question
    title: "{root research question}"
    provenance: user
    timestamp: "YYYY-MM-DDTHH:MM"
    description: >
      {what is being explored}
    children:

      - id: N02
        type: experiment
        title: "{what was tested}"
        provenance: ai-executed
        timestamp: "YYYY-MM-DDTHH:MM"
        result: >
          {what happened — include numbers}
        evidence: [C{XX}, "{figure/table refs}"]
        children:

          - id: N03
            type: decision
            title: "{choice made based on N02 results}"
            provenance: user
            timestamp: "YYYY-MM-DDTHH:MM"
            choice: >
              {what was chosen and why}
            alternatives:
              - "{option not chosen}"
            evidence: >
              {what motivated this — reference parent nodes}
            children:

              - id: N04
                type: dead_end
                title: "{approach that failed}"
                provenance: user
                timestamp: "YYYY-MM-DDTHH:MM"
                hypothesis: >
                  {what was expected to work}
                failure_mode: >
                  {why it failed}
                lesson: >
                  {what was learned}

              - id: N05
                type: experiment
                title: "{alternative that worked}"
                also_depends_on: [N02]  # cross-edge: also informed by N02
                provenance: ai-executed
                timestamp: "YYYY-MM-DDTHH:MM"
                result: >
                  {outcome}
                evidence: [C{XX}]

      - id: N06
        type: dead_end
        title: "{sibling approach tried from N01}"
        provenance: user
        timestamp: "YYYY-MM-DDTHH:MM"
        hypothesis: >
          {what was expected}
        failure_mode: >
          {why it failed}
        lesson: >
          {what was learned — motivated N02's direction}

  - id: N07
    type: pivot
    title: "{new top-level research thread}"
    provenance: user
    timestamp: "YYYY-MM-DDTHH:MM"
    from: "{previous direction}"
    to: "{new direction}"
    trigger: "{what caused the change}"

Node Type Reference

Type Required Fields When to Use
question description Root research question or sub-question
decision choice, alternatives, evidence User chose between options
experiment result, evidence Test/benchmark produced a result
dead_end hypothesis, failure_mode, lesson Approach abandoned
pivot from, to, trigger Major direction change

Claim (logic/claims.md)

## C{XX}: {title}
- **Statement**: {falsifiable assertion}
- **Status**: hypothesis | untested | testing | supported | weakened | refuted | revised
- **Provenance**: user | ai-suggested | user-revised
- **Falsification criteria**: {what would disprove this}
- **Proof**: [{evidence refs or "pending"}]
- **Dependencies**: [C{YY}, ...]
- **Tags**: {comma-separated}

Heuristic (logic/solution/heuristics.md)

## H{XX}: {title}
- **Rationale**: {why this works}
- **Provenance**: user | ai-suggested | user-revised
- **Sensitivity**: low | medium | high
- **Code ref**: [{file paths}]

Observation (staging/observations.yaml)

- id: O{XX}
  timestamp: "YYYY-MM-DDTHH:MM"
  provenance: user | ai-suggested | ai-executed
  content: "{raw observation}"
  context: "{what was happening}"
  potential_type: claim | heuristic | decision | unknown
  promoted: false

Session Record (trace/sessions/YYYY-MM-DD_NNN.yaml)

session:
  id: "YYYY-MM-DD_NNN"
  timestamp: "YYYY-MM-DDTHH:MM"
  summary: "{one-line summary of what happened}"

events_logged:
  - type: decision | experiment | dead_end | pivot | claim | heuristic | observation
    id: "{N/C/H/O}{XX}"
    provenance: user | ai-suggested | ai-executed | user-revised
    summary: "{what}"

ai_actions:
  - action: "{what AI did}"
    provenance: ai-executed
    files_changed: ["{paths}"]

claims_touched:
  - id: C{XX}
    action: created | advanced | weakened | confirmed
    provenance: user | ai-suggested

open_threads:
  - "{what needs follow-up}"

ai_suggestions_pending:
  - "{unconfirmed AI suggestions from this session}"

Initialization (if ara/ does not exist)

Create the full directory structure and seed files automatically. Do not ask.

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

Then write:

  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/staging/observations.yaml — observations: []
  5. ara/logic/claims.md — # Claims
  6. ara/logic/problem.md — # Problem
  7. ara/logic/solution/heuristics.md — # Heuristics
  8. ara/evidence/README.md — # Evidence Index

Maturity Tracker (runs during epilogue)

While reviewing staging/observations.yaml:

  • 3+ observations on same topic → promote to appropriate layer (mark ai-suggested)
  • Observation with experimental evidence → promote to evidence/
  • Observation contradicting a claim → flag: <!-- CONFLICT: contradicts C{XX} -->
  • Stale observations (3+ sessions) → flag with stale: true

Procedure

  1. Read existing ara/ files to get current state (IDs, claims, tree).
  2. Scan the full conversation for research-significant events.
  3. Classify each event and assign provenance.
  4. Append new entries to the correct files. Update existing entries if status changed.
  5. Create session record at ara/trace/sessions/YYYY-MM-DD_NNN.yaml.
  6. Append session to ara/trace/sessions/session_index.yaml.
  7. Run maturity tracker on staging area.
  8. Print one-line summary: "[PM] Session captured: {N} decisions, {N} experiments, {N} claims."

Rules

  1. Never run during a task — only as epilogue after the user's request is done.
  2. Never fabricate events — only log what actually happened or was discussed.
  3. Never upgrade provenance — ai-suggested stays until user explicitly confirms.
  4. Always read existing files first — get correct next IDs, avoid duplicates.
  5. Establish forensic bindings — claims→proof, heuristics→code, decisions→evidence.
  6. Append, don't overwrite — add new entries, never replace existing content.
  7. Keep YAML valid — validate structure after writes.

Reference Files

For detailed protocol and taxonomy specifications, load on demand:

Related skills

  • ara-rigor-reviewer: Performs ARA Seal Level 2 semantic epistemic review of an Agent-Native Research Artifact directory, reading PAPER.md, logic/claims.md, logi…
  • ara-compiler: Compiles any research input — PDF papers, GitHub repositories, experiment logs, code directories, or raw notes — into a complete Agent-Nati…
  • treatment-plans: Format and structurally validate local treatment-plan documentation after clinical decisions have already been supplied and verified by aut…

Trigger Prompts & Evaluation Corpus

These evaluation prompts test that the agent correctly selects ara-research-manager for relevant tasks and leaves it out for near misses.

Should trigger (3)

  • should trigger

    “ok we're done for today, log the session”

    expects Runs as an end-of-session epilogue: reads existing ara/ files for next IDs, scans the conversation, appends decisions/experiments/dead ends with provenance tags (defaulting to ai-suggested when uncertain), writes a session record and index entry, and prints a one-line '[PM] Session captured' summary.

  • should trigger

    “That finishes the ablation on my CIFAR-10 ResNet-18 run. We tried cosine vs step LR (cosine hit 94.1% vs 92.7%), dropped mixup after it hurt accuracy, and I decided to keep label smoothing 0.1. Now that everything's finished, can you record all of this in ara/trace/exploration_tree.yaml and ara/logic/claims.md so there's a record of who decided what, and add a session file?”

    expects Reads existing ara/ state, adds a decision node (cosine LR chosen, user), an experiment node with the 94.1 vs 92.7 results, a dead_end for mixup with failure_mode and lesson, a claim linked to evidence, nests nodes properly in the tree, tags the user's choices as user and the AI's code runs as ai-executed, appends rather than overwrites, keeps YAML valid, and creates a dated session record.

  • should trigger

    “My project just wrapped up its first phase and I need a durable, auditable trail of how our direction changed over the past few weeks of chats, including which ideas were mine and which came from the assistant. There's no folder for this yet. Can you set that up and fill it in?”

    expects Creates the full ara/ directory structure and seed files without asking (PAPER.md, session_index.yaml, exploration_tree.yaml, observations.yaml, claims.md, problem.md, heuristics.md, evidence/README.md), then extracts only events that actually occurred, tags provenance honestly without upgrading ai-suggested to user, and does not fabricate events.

Near misses (2)

  • near miss

    “I have an ara/ directory for my protein folding project. Please review claims.md and trace/exploration_tree.yaml and score evidence relevance, falsifiability, and scope calibration, and tell me whether it would pass a rigor review.”

    expects Should not record provenance; this is a semantic epistemic review of an existing ARA, which belongs to ara-rigor-reviewer.

  • near miss

    “Here's the PDF of our lab's new transformer paper and its GitHub repo. Turn them into a full structured research artifact with claims, concepts, configs and an exploration graph.”

    expects Should not log a session epilogue; compiling a PDF and repo into an ARA is the job of ara-compiler.