Skip to content

Orchestra-Research/AI-Research-SKILLs / 22-agent-native-research-artifact/research-manager

ara-research-manager

Verified

Records research provenance as a post-task epilogue, scanning conversation history at the end of a coding or research session to extract decisions, experiments, dead ends, claims, heuristics, and pivots, and writing them into the ara/ directory with user-vs-AI provenance tags. Use as a session epilogue — never during execution — to maintain a faithful, auditable trace of how a research project actually evolved.

FileKindSize
SKILL.mdskill md12.3 KB
references/event-taxonomy.mdmarkdown4.9 KB
references/provenance-tags.mdmarkdown6.0 KB
references/session-protocol.mdmarkdown5.8 KB

references/event-taxonomy.md

View on GitHub
# Event Taxonomy & Routing Rules

## Event Classification

When you observe activity in the coding session, classify it into one of these event types.
Use the **signals** column to identify events from conversation and code context.

### Research Events (Route to `trace/exploration_tree.yaml`)

| Type | Signals | Example |
|------|---------|---------|
| **question** | User asks "what if...", "should we...", "how does..." about research direction | "Should we use attention or convolution for the encoder?" |
| **decision** | User chooses between alternatives, commits to a direction | "Let's go with GQA instead of MHA — lower memory footprint" |
| **experiment** | Code runs a test/benchmark, user reports results | "The learning rate sweep shows 3e-4 is optimal" |
| **dead_end** | Approach abandoned, hypothesis falsified, "this doesn't work" | "Tried FP16 but the loss diverges after 1k steps" |
| **pivot** | Major direction change triggered by evidence | "The attention approach is too slow — switching to state space models" |

### Knowledge Events (Route to `logic/`)

| Type | Signals | Routes To |
|------|---------|-----------|
| **claim** | "I believe...", "The system achieves...", assertion about capability/property | `logic/claims.md` |
| **heuristic** | "The trick is...", "You need to...", implementation insight | `logic/solution/heuristics.md` |
| **concept** | New term defined, disambiguation needed | `logic/concepts.md` |
| **constraint** | "This only works when...", boundary condition | `logic/solution/constraints.md` |
| **architecture** | System design, component relationships | `logic/solution/architecture.md` |

### Evidence Events (Route to `evidence/`)

| Type | Signals | Routes To |
|------|---------|-----------|
| **result_table** | Tabular data, benchmark numbers, comparison matrix | `evidence/tables/table{N}.md` |
| **result_figure** | Plot data, visualization, chart values | `evidence/figures/fig{N}.md` |
| **metric** | Single quantitative measurement | Inline in experiment node or evidence file |

### Process Events (Route to `trace/sessions/`)

| Type | Signals | Routes To |
|------|---------|-----------|
| **ai-action** | Agent wrote code, ran command, created file | Session record |
| **ai-suggestion** | Agent proposed direction, hypothesis, approach | Session record (ai_suggestions_pending) |
| **user-direction** | User gives high-level instruction or corrects | Session record (events_logged with provenance: user) |

### Staging Events (Route to `staging/`)

| Type | Signals | Routes To |
|------|---------|-----------|
| **observation** | Doesn't clearly fit above categories; interesting but unstructured | `staging/observations.yaml` |

## Routing Decision Tree

```
Is it about a choice between alternatives?
  → YES: decision (trace)
  → NO: ↓

Is it a quantitative result or experimental outcome?
  → YES: experiment (trace) + evidence data (evidence/)
  → NO: ↓

Is it an abandoned approach with a reason?
  → YES: dead_end (trace)
  → NO: ↓

Is it a falsifiable assertion about the system/method?
  → YES: claim (logic/claims.md)
  → NO: ↓

Is it an implementation trick with rationale?
  → YES: heuristic (logic/solution/heuristics.md)
  → NO: ↓

Is it a major direction change?
  → YES: pivot (trace)
  → NO: ↓

Is it a research question being explored?
  → YES: question (trace)
  → NO: → observation (staging)
```

## Provenance Assignment

```
Who generated this information?

User said it directly (typed it, stated it, confirmed it)
  → provenance: user

AI inferred it from code, output, or conversation context
  → provenance: ai-suggested

AI performed an action (wrote code, ran test, made edit)
  → provenance: ai-executed

User modified an AI suggestion ("no, actually..." / "more like...")
  → provenance: user-revised
```

## ID Conventions

| Type | Prefix | Example | Scope |
|------|--------|---------|-------|
| Exploration node | N | N01, N02 | Global (across all sessions) |
| Claim | C | C01, C02 | Global |
| Heuristic | H | H01, H02 | Global |
| Experiment plan | E | E01, E02 | Global |
| Observation | O | O01, O02 | Global |
| Session | date_seq | 2026-03-11_001 | Unique by date |

**Auto-increment**: Always read the existing file to find the highest ID before creating a new one.

## Forensic Binding Checklist

When logging any event, establish these bindings immediately:

- [ ] **Claim → Proof**: If a claim is created, what evidence would prove/disprove it? Set `Proof: [pending]` if no evidence yet.
- [ ] **Experiment → Claim**: Which claims does this experiment test? Link via `Claims tested:`.
- [ ] **Heuristic → Code**: Where in the codebase is this implemented? Set `Code ref:`.
- [ ] **Decision → Evidence**: What evidence or reasoning drove this decision?
- [ ] **Dead End → Lesson**: What was learned? Could this knowledge prevent future mistakes?

If a binding can't be established now, add a `<!-- TODO: bind to {target} -->` comment as a trackable obligation.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 196kUpdated Claude CodeCodexVerifiedInstall