| name | research-ledger |
| description | Proactively record a research project into Promptus as work happens — append a unit after every decision, run, observation, dead-end, or finding via kb-add (never freehand). Teaches the recording habit so the ledger fills itself instead of being reconstructed later. The script owns timestamp, id, and placement. Pairs with the promptus-checkpoint workflow. |
research-ledger — record as you go
Portable path rule: in commands below, replace <plugin-root> with the absolute plugin root
two directories above this SKILL.md. Resolve it from the loaded skill path; do not assume a
host-specific environment variable exists in the project shell.
A research ledger is the lab notebook for a long investigation: what you tried, what
happened, what broke, what you fixed, what you abandoned and why. It makes the work
compounding and compaction-safe — a fresh (or post-compaction) session resumes from
the file alone with nothing important lost. It is in the spirit of Karpathy's llm-wiki (raw sources + an LLM-maintained wiki +
an AGENTS.md "schema", plus an append-only log), adapted as a lab notebook where the
append-only log is the spine and the wiki is distilled from it at checkpoint — a
deliberate inversion of the gist's coequal layers, ours and not Karpathy's own ordering.
Two parts of the ledger
.promptus/ledger/RESEARCH-LEDGER.md has a small NOW-header (always rewritten to stay current —
the compaction-safe core a resuming agent reads instead of the whole file) and an
append-only Log below a <!-- kb:append-point --> sentinel.
The recording reflex — append through the gate, never freehand
During real work, watch for the moments worth keeping and write each the moment it happens:
echo "<prose body>" | bun "<plugin-root>/scripts/kb-add.ts" \
--substrate ledger --kind <KIND> --status <STATUS> --title "<short imperative title>" [--links "a,b"] [--supersedes <id>]
The script stamps the local ### [YYYY-MM-DD HH:MM:SS] KIND/STATUS — title header from the
system clock, mints the id, inserts above the sentinel, and refreshes the catalog. Never
hand-type a ### [ts] line — hand-typed timestamps drift (that is how a past ledger lost a
day). The checkpoint refreshes the NOW-header through kb-now, never by freehand ledger editing.
Three facets: KIND, STATUS, RELATION
Keep them distinct — KIND is the act, STATUS is the claim's epistemic state, RELATION is a
typed link to another unit. The header reads KIND/STATUS.
KIND (--kind) — core: PLAN · EXP · RESULT · FINDING · DECISION · RESEARCH ·
RESUME; blessed extensions: IDEA · MISTAKE · FIX · DEADEND. Negative results are
first-class: a DEADEND or MISTAKE earns the same care as a RESULT — why something failed
is often worth more than what worked.
STATUS (--status) — core: CONJECTURED / VALIDATED / REFUTED / CONFOUNDED
(renders ⚠CONFOUNDED; an observation with more than one explanation) / SUPERSEDED; blessed
extensions: OPEN / RESOLVED / WONTFIX. Promote to VALIDATED only with the evidence named
(a passing test, a proof, a measured delta vs a control). The ledger is permissive — an
off-vocab status is warned about but still written, so you never lose a thought to the gate; add
it to .promptus/schema/kb-vocab.json if it's here to stay. (finding / lit / memory stay strict.)
RELATION (--rel <type>:<id>, or --supersedes <id>) — typed edges between units:
supersedes (marks the target SUPERSEDED — this is the correction mechanism), refutes,
challenges, supports, extends, fixes. They export to CiTO / PROV-O via
bun "<plugin-root>/scripts/kb-export.ts". Example headers: RESULT/VALIDATED, DEADEND/REFUTED, RESULT/CONFOUNDED.
A research effort has three homes — the digest is the one that gets skipped
A deep-research (your own, or an agent team's report) is not stored when its event is:
| what | home | via |
|---|
| that it happened, what was decided | ledger | kb-add --substrate ledger (as you go) |
| the sources it read | lit | kb-add --substrate lit --source … (one per source) |
| what we now know — the digested reasoning | finding | kb-add --substrate finding |
The first two happen naturally; the third is the one a real project went dark on for a
week (ledger events and 44 lit units accumulating, zero new findings). An in-conversation
research report is perishable — compaction keeps the conclusion but destroys the
reasoning, the alternatives weighed, and the methodology. If a report earned tokens,
digest it into a finding unit in the same session: terse, linky ([[lit-slugs]]),
stating what was adopted, what was rejected and why, and where any shipped artifact of it
lives. The ledger entry then records only the event, as it should.
Disciplines that make it worth keeping
- Artifact-coupling. Every
RESULT names a reproducible artifact (path or run-id) and
quotes the key number inline, so a reader can spot-check without opening it.
- Failure-first honesty. Record what broke and why. The
DEADEND trail is the most
valuable part of the file.
- Attribution. Say what produced a claim (a run, a proof, a model, the operator).
- Backward links. New entries reference what they build on or overturn (
[ts], [[link]]),
so the file reads as a causal chain, not a pile.
- No justification-free constants. When you introduce a threshold, record why in the same entry.
Keeping it readable (the bloat rule)
The NOW-header stays small and current — it is what gets read. At checkpoint, distill recent
entries into docs/ finding pages (one concept per file, [[linked]], via kb-add --substrate finding). When the Log passes a few thousand lines, archive older sections to
ledger/archive/<YYYY-MM>.md and leave a one-line pointer — history preserved, never rewritten.
Standing cadence (put this in the project's AGENTS.md)
Maintain the research ledger: append a unit after every completed unit of work — including
mistakes, fixes, dead-ends, and brainstorms, not only successes — with
bun "<plugin-root>/scripts/kb-add.ts" --substrate ledger … (never hand-type ### [ts]). Refresh the
NOW-header and run the promptus-checkpoint workflow before compaction.
