research-log

research-log

v0.4.0 — your research advisor, not just a diary
Surfaces anti-patterns before you commit, recalls prior solutions when stuck, flags drift from your goals in real time.

   

---

Why: diary → advisor

A research log that only records the past is half the value. research-log acts at three moments where passive logs stay silent:

Moment	When it fires	What it does
M1 — decision guardrail	You propose an architecture, method, or "let's do X"	Reads rules.md, surfaces matching anti-patterns before you commit — automatically, from conversation
M3 — cross-project recall	You are stuck or ask "have I solved this before?"	Semantic search (QMD) over journals + lessons across all registered projects
M4 — real-time drift	You're deep in implementation details	Compares your current work against the ← current focus marker in compass.md and flags divergence

M1 is a behavioral directive baked into the skill: it fires on any approach-choice in any registered project's working directory, without requiring an explicit command.

---

Install

# Add the marketplace and install
claude plugin marketplace add Axect/research-log
claude plugin install research-log

Then register your first project inside Claude Code:

research-log: initialize my project

---

Storage layout

All data lives in a single unified store at ~/.research/:

~/.research/
├── dashboard.md                 # All projects at a glance (derived, regenerated at review)
├── rules.md                     # Promoted Rules — small, always-loaded M1 checklist
├── projects/
│   └── {slug}/
│       ├── compass.md           # Main Goal / Sub-goals % / Why / Biggest Risk / Core Documents
│       ├── state.md             # Session pointer (overwritten on each save)
│       └── journal.md           # Decision Log — append-only, newest-first, verbatim
├── lessons/
│   └── {lesson-id}.md           # First-class Lesson objects (one principle per file)
├── wiki/                        # Thesis narratives, concept definitions, method descriptions
└── .locks/
    └── {slug}.lock              # Per-project flock file (concurrency safety)

Each layer is read differently — design choices follow from that:

Layer	Size	Lifetime	How it is read
Compass	small	always current	always loaded (steering + M4)
State	tiny	overwritten	session restore
Journal	large	append, verbatim	searched, not read whole
Lessons	small/file	accumulating	searched + matched (M1 / M3)
Rules	tiny	accumulating	always loaded (M1 checklist)

---

How to use

research-log is a single skill that routes to the right workflow based on what you ask. There are no separate /log-* commands.

Workflow triggers

Intent	Example phrase
initialize — register a new project	research-log: set up a new project
record — log an experiment or decision	research-log: record today's experiment
save-state — snapshot current session	research-log: save state
recall — find prior lessons or solutions (M3)	research-log: have I solved this kind of instability before?
check — explicitly test a plan against past mistakes (M1)	research-log: check this approach against past errors
review — weekly review, promote lessons, refresh dashboard	research-log: weekly review

The automatic M1 behavior

You do not need to call check for M1 to fire. Whenever you propose an approach in a registered project directory — an architecture choice, a loss function, an experimental design — the skill automatically:

1. Reads ~/.research/rules.md (small; cheap).
2. Checks whether any Rule's trigger matches the proposed action.
3. If a match is found, surfaces it first: "You are about to X — this bit you in [projects]: [Check]."
4. If nothing matches, proceeds silently.

---

Data model

Compass (projects/{slug}/compass.md)

The project's goal tree: Main Goal, Sub-goals with completion percentages, Why This Approach, Biggest Risk, and exactly one ← current focus marker that anchors M4 drift detection. The skill proposes percentage updates; you approve before any write.