Orchestra-Research/AI-Research-SKILLs / 22-agent-native-research-artifact/research-manager
ara-research-manager
VerifiedRecords 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.3 KB |
| references/event-taxonomy.md | markdown | 4.9 KB |
| references/provenance-tags.md | markdown | 6.0 KB |
| references/session-protocol.md | markdown | 5.8 KB |
references/session-protocol.md
View on GitHub# Session Protocol (Always-On)
The Live PM runs automatically. No commands needed. This document details the
internal procedures the skill follows at each phase of a conversation.
## Session Start (automatic)
### If `ara/` exists
1. **Read state silently**:
- `ara/trace/sessions/session_index.yaml` → last session date, summary, open threads
- `ara/logic/claims.md` → count by status
- `ara/staging/observations.yaml` → pending count, promotion candidates
2. **Deliver briefing contextually**:
- If user jumps straight into a task → weave context into your first response:
"Before we dive in — last session you were testing C04, result was 92%. Two open threads."
- If user asks what's going on / where we left off → give full briefing
- Never lead with the briefing if the user clearly has a specific task in mind
3. **Create session record**:
```
ara/trace/sessions/YYYY-MM-DD_NNN.yaml
```
Initialize with start time and empty events list.
### If `ara/` does not exist
- Don't create it unprompted on the very first interaction
- If you detect research-significant discussion (decisions, hypotheses, experiments),
ask once: "Want me to track this project's research process? I'll set up `ara/`."
- On confirmation → initialize full directory structure + bootstrap from current conversation
## During Session (continuous, invisible)
### Event Detection Loop
After every substantive exchange, evaluate:
```
1. Decision made? → write to exploration_tree.yaml
2. Result observed? → write to exploration_tree.yaml + evidence/
3. Approach failed? → write dead_end to exploration_tree.yaml
4. Claim stated? → write to claims.md
5. Trick discovered? → write to heuristics.md
6. Direction changed? → write pivot to exploration_tree.yaml
7. AI wrote code? → log to session record (ai_actions)
8. Interesting note? → write to staging/observations.yaml
```
### Writing Protocol
1. **Read the target file first** to get the next available ID
2. **Append** new entries — never overwrite existing content
3. **Establish bindings immediately**: claim→proof, heuristic→code_ref, decision→evidence
4. **Use correct provenance tag** based on who generated the information
5. **Keep YAML valid** — verify structure mentally before writing
6. **Be silent about it** — don't mention the logging unless asked
### Provenance Decision Tree
```
User typed/said it explicitly?
→ provenance: user
AI ran code/test/command that produced this?
→ provenance: ai-executed
AI noticed pattern, inferred meaning, proposed interpretation?
→ provenance: ai-suggested
User corrected an AI suggestion?
→ provenance: user-revised
Uncertain?
→ provenance: ai-suggested (conservative default)
```
### What Gets Logged to Session Record
The running session record (`trace/sessions/YYYY-MM-DD_NNN.yaml`) accumulates:
- Every event written to any ARA file (type, id, provenance, one-line summary)
- AI actions: code written, commands run, files created/modified
- Claims touched: which claims were created, advanced, weakened, confirmed
- Open threads: unresolved questions or incomplete work
- AI suggestions pending: things AI proposed that user hasn't confirmed
### Conflict Detection
When writing a new entry, check for conflicts:
- New claim contradicts existing claim → add `<!-- CONFLICT: see C{XX} -->` to both
- New evidence weakens existing claim → update claim status to `weakened`
- New decision reverses previous decision → log as `pivot` linking to original decision
## Session End (automatic)
### Triggers
Session end is detected when:
- Conversation is clearly wrapping up ("thanks", "that's all", user goes quiet)
- Context window is getting compressed (system is summarizing old messages)
- User explicitly says goodbye or indicates end of work
### Procedure
1. **Finalize session record**:
- Set `ended` timestamp
- Write summary (one line capturing the session's main outcome)
- Ensure all buffered events are flushed to ARA files
2. **Update session index**:
Append entry to `ara/trace/sessions/session_index.yaml`:
```yaml
- id: "YYYY-MM-DD_NNN"
date: "YYYY-MM-DD"
summary: "{main outcome}"
events_count: {N}
claims_touched: [C{XX}, ...]
open_threads: {N}
```
3. **Maturity check** on staging:
- 3+ observations on same topic → auto-promote (with `ai-suggested` provenance)
- Observation with evidence → promote to `evidence/`
- Stale entries (3+ sessions old) → flag with `stale: true`
4. **Brief session close note** (keep to one line):
```
[PM] Session captured: 3 decisions, 1 experiment, 2 claims advanced. 1 open thread.
```
## Cross-Session Continuity
### How Memory Persists
The agent has no built-in cross-session memory. The ARA itself IS the memory:
- `session_index.yaml` → what happened when
- `claims.md` → what's known vs. unknown
- `exploration_tree.yaml` → the full research trajectory
- `staging/observations.yaml` → loose threads
- Individual session records → detailed per-session history
### Session Start Reconstruction
At the start of each conversation, reading these files reconstructs full project context.
The agent effectively "remembers" everything through the artifact it built.
### Open Thread Tracking
Open threads carry forward automatically:
- Each session record lists `open_threads`
- At session start, the latest session's open threads are surfaced
- When a thread is resolved in a later session, note it in that session's events
## Emergency / Abrupt End
If conversation ends without proper session close:
- Events already written to ARA files are safe (written incrementally)
- Session record may be incomplete — next session should detect this and note it
- No data is lost because writes happen in real-time, not batched at end
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |