research-log

What this skill does

# Research Log

Capture completed research explorations to context-hub (chub) for permanent, cross-session access. Unlike decision-log (which records WHAT was decided), research-log stores the FULL exploration — all options evaluated, pros/cons, context, methodology, and findings.

## When to Use

**Explicit triggers:**
- User says "log this research", "document research", "save research", "capture findings"
- User asks to "save" or "document" after substantial research

**Proactive triggers (suggest briefly):**
- After completing multi-step investigation (library comparison, architecture exploration, tool evaluation)
- When research involves 3+ alternatives evaluated
- When findings include significant context or methodology worth preserving
- Briefly suggest: "Worth logging this research to chub?"

**What counts as research:**
- Library/framework comparisons (WebSockets vs SSE vs WebRTC)
- Architecture explorations (microservices vs monolith, database choices)
- Tool evaluations (CI/CD options, deployment platforms)
- Domain deep-dives (authentication patterns, caching strategies)
- Performance analysis (load testing results, optimization findings)

**What does NOT count:**
- Quick API lookups or syntax checks
- Single-source fact-finding ("what's the latest React version?")
- Debugging investigations (use systematic-debugging for those)
- Code reviews or refactoring analysis

## Storage Location

**CRITICAL: Research goes to chub, NOT auto-memory.**

Auto-memory (`~/.claude/projects/-Users-tomerhamam/memory/`) is session-specific and transient. Research needs permanent, cross-session, cross-project access via chub.

**File location:**
```
~/.chub-internal/neuronbox/docs/research-<project>/DOC.md
```

If the doc doesn't exist, create it with this frontmatter:

```markdown
---
name: research-<project>
description: Research explorations for <project> — library comparisons, architecture investigations, tool evaluations, and domain deep-dives with full findings and methodology.
metadata:
  languages: "all"
  versions: "<YYYY.M.DD>"
  revision: 1
  updated-on: "<YYYY-MM-DD>"
  source: research-log-skill
  tags: "research,<project>,exploration"
---

# Research Log: <project>

Accumulated research with full context, alternatives, and findings.
```

## When Information is Missing

**DO NOT ask clarifying questions to fill the template.** Work with what you have from the conversation.

If details are missing:
1. **Use context from conversation** - Research question, methodology, sources are usually evident from the discussion
2. **Make reasonable inferences** - If user discussed docs and GitHub issues, list those as sources
3. **Mark unknowns** - Use "Not captured" or "N/A" for truly missing fields
4. **Prefer action over perfection** - A logged entry with some gaps beats no entry at all

**Example:**
- Research question unclear? Infer from what problem was being solved
- Sources not mentioned? List "Conversation-based research" or "Not explicitly tracked"
- Telemetry estimates uncertain? Use "~2 hours" or "~10 turns" as rough estimates

The goal: Capture what WAS discussed so it's searchable later. Don't block on missing metadata.

## Entry Structure

Append each research session as a new section:

```markdown
---

## RES-<NNN>: <short title>

**Date:** <YYYY-MM-DD>
**Category:** <one of: library | architecture | tooling | domain | performance | security>
**Tags:** <free-form comma-separated tags>
**Status:** completed

### Research Question

<What were we trying to figure out? What problem prompted this investigation? Be specific enough that someone reading this 6 months later understands the landscape.>

### Methodology

<How did you research this? Sources consulted, experiments run, criteria used for evaluation. Example: "Compared official docs, tested sample implementations, consulted Stack Overflow discussions, reviewed GitHub issues for production gotchas.">

### Options Evaluated

| Option | Pros | Cons | Verdict |
|--------|------|------|---------|
| <option A> | ... | ... | <chosen/rejected> |
| <option B> | ... | ... | <chosen/rejected> |
| <option C> | ... | ... | <chosen/rejected> |

### Findings

<Key discoveries and insights. What did we learn? What patterns emerged? What gotchas did we uncover?>

### Recommendation

<What approach is recommended and why? Be specific with rationale tied back to evaluation criteria.>

### Implementation Notes

<Practical details for whoever implements this: setup steps, configuration requirements, dependencies, known issues to watch for.>

### Telemetry

| Field | Value |
|-------|-------|
| project | <project name> |
| working_dir | <cwd> |
| model | <model ID> |
| sources_consulted | <docs, GitHub, Stack Overflow, blog posts, etc.> |
| tools_used | <tools invoked during research> |
| research_duration_est | <rough estimate> |
| conversation_turns | <approximate turn count> |
```

## Numbering

Research IDs are sequential per project. Read the last `RES-<NNN>` entry and increment. If new doc, start at `RES-001`.

## Determining the Project

Infer from context:
1. If working in project directory with CLAUDE.md, use that project name
2. If user mentions specific project/bot (DB, Nook, X, M-Bot), use that
3. If ambiguous, ask: "Which project should I log this under?"

**Common mappings:**
- DB / OpenClaw / Neuron → `openclaw`
- Nook / Letta → `nook`
- X / NanoClaw → `nanoclaw`
- M-Bot / OpenJarvis → `mbot`
- AEGIS → `aegis`

For unknown projects, create new slug using lowercase project name.

## Integration with decision-log

**REQUIRED:** After logging research to chub, invoke decision-log with a concise pointer:

```markdown
## DEC-<NNN>: <decision title>

**Date:** <YYYY-MM-DD>
**Category:** <match research category>
**Tags:** <match research tags>
**Status:** accepted

### Context

Research conducted on <topic>. Full exploration logged to chub.

**Research log:** `RES-<NNN>` in `research-<project>` (accessible via `chub get neuronbox/research-<project>`)

### Decision

<1-2 sentence summary of what was decided>

### Consequences

- **Easier:** <what this enables>
- **Harder:** <what tradeoffs were accepted>
- **Constraints:** <new invariants>

### Telemetry

<standard decision-log telemetry>
```

**Why both?**
- research-log = FULL exploration (all options, methodology, findings)
- decision-log = CONCISE pointer (what was decided, where full research lives)

Decision-log is the index; research-log is the deep archive.

## After Logging

1. Increment `revision` in research doc frontmatter
2. Update `updated-on` date
3. Invoke decision-log with concise pointer (see above)
4. Rebuild chub:
   ```bash
   chub build ~/.chub-internal -o ~/.chub-internal/dist
   ```
5. Confirm: "Logged RES-<NNN> to research-<project>: <title>. Decision pointer: DEC-<NNN> in decisions-<project>."

## Retrieving Past Research

When user asks about past research:
```bash
chub search "research <project>"
```
Then read and surface relevant entries.

Or search decision-log for pointers, then follow to full research.

## Red Flags - STOP and Use This Skill

These thoughts mean you're rationalizing away proper research storage:

| Excuse | Reality |
|--------|---------|
| "Let me ask where to save this" | Chub is the answer. Act, don't ask. |
| "I need more details to fill template" | Work with what you have. Infer from conversation. |
| "Let me clarify before logging" | Context is in the conversation. Extract and log. |
| "I'll save to auto-memory" | Auto-memory is transient. Research needs chub. |
| "User can copy-paste if needed" | Future sessions can't access your response. Use chub. |
| "Just an inline summary is fine" | Structured storage enables retrieval. Use chub. |
| "This is too simple to log" | If 3+ options evaluated, it's research. Log it. |
| "I don't want to create files" | Chub is designed for this. Create the file. |

**All of these mean: Stop. Log to chub. Invoke decision-log.**