research-wiki

Files (1)

• SKILL.md

SKILL.md (first lines)

# Research Wiki: Persistent Research Knowledge Base

Subcommand: **$ARGUMENTS**

## Overview

The research wiki is a persistent, per-project knowledge base that accumulates structured knowledge across the entire ARIS research lifecycle. Unlike one-off literature surveys that are used and forgotten, the wiki **compounds** — every paper read, idea tested, experiment run, and review received makes the wiki smarter.

Inspired by [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): compile knowledge once, keep it current, don't re-derive on every query.

## Core Concepts

### Four Entity Types

| Entity | Directory | Node ID format | What it represents |
|--------|-----------|---------------|--------------------|
| **Paper** | `papers/` | `paper:<slug>` | A published or preprint research paper |
| **Idea** | `ideas/` | `idea:<id>` | A research idea (proposed, tested, or failed) |
| **Experiment** | `experiments/` | `exp:<id>` | A concrete experiment run with results |
| **Claim** | `claims/` | `claim:<id>` | A theorem/headline with an honest PROOF status — born via `/proof-checker` (see Hook 4) |

### Typed Relationships (`graph/edges.jsonl`)

| Edge type | From → To | Meaning |
|-----------|-----------|---------|
| `extends` | paper → paper | Builds on prior work |
| `contradicts` | paper → paper | Disagrees with results/claims |
| `addresses_gap` | paper\|idea → gap | Targets a known field gap |
| `inspired_by` | idea → paper | Idea sourced from this paper |
| `tested_by` | idea\|claim → exp | Tested in this experiment |
| `supports` | exp → claim\|idea | Experiment confirms claim |
| `invalidates` | exp → claim\|idea | Experiment disproves claim |
| `supersedes` | paper → paper | Newer work replaces older |

Edges are stored in `graph/edges.jsonl` only. The `## Connections` section on each page is **auto-generated** from the graph — never hand-edit it.

### Capture hygiene (anti-self-poisoning)

Before persisting an **idea / claim / experiment** note, screen it for
operational noise that would harden into a self-cited falsehood (see
[`shared-references/capture-antipatterns.md`](../shared-references/capture-antipatterns.md)).
Resolve the helper via the canonical chain (integration-contract §2):
`.aris/tools/capture_filter.py` → `tools/capture_filter.py` →
`$ARIS_REPO/tools/capture_filter.py` (warn-and-skip if unresolved). Run
`python3 <capture_filter> -` on the note text; if it flags **env-failure /
transient-error / negative-tool-claim**, do NOT store it as a durable node —
rewrite it to the *fix / missing config / workaround*, or drop it. Never store
"codex/gemini/the reviewer can't do X" — that gets loaded into every future
session and cited against the agent long after the real cause is gone. (The wiki's
"failed ideas → anti-repeat memory" is the GOOD inverse: a class-level *research*
finding, not operational noise.)

## Wiki Directory Structure

```
research-wiki/
  index.md               # categorical index (auto-generated)
  log.md                 # append-only timeline
  gap_map.md             # field gaps with stable IDs (G1, G2, ...)
  query_pack.md          # compressed summary for /idea-creator (auto-generated, max 8000 chars)
  papers/
    <slug>.md            # one page per paper
  ideas/
    <idea_id>.md         # one page per idea
  experiments/
    <exp_id>.md          # one page per experiment
  claims/
    <claim_id>.md        # one page per testable claim
  graph/
    edges.jsonl          # materialized current relationship graph
```

## Subcommands

## Helper resolution (run before any subcommand below)

All wiki operations except plain directory bootstrap go through a single
canonical helper, `tools/research_wiki.py`. Skills that touch the wiki
must resolve `$WIKI_SCRIPT` via the chain below — never hard-code
`python3 tools/research_wiki.py …`. Hard-coding silently fails when
the project does not have `tools/` on disk (the post-`install_aris.sh`
default), which is exactly the failure mode that left a real user's
`research-wiki/` empty for a week.

```bash
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null)}"
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
  ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
WIKI_SCRIPT=".aris/tools/research_wiki.py"
[ -f "$WIKI_SCRIPT" ] || WIKI_SCRIPT="tools/research_wiki.py"
[ -f "$WIKI_SCRIPT" ] || { [ -n "${ARIS_REPO:-}" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"; }
[ -f "$WIKI_SCRIPT" ] || {
  echo "ERROR: research_wiki.py not found at .aris/tools/, tools/, \$ARIS_REPO/tools/, or via ~/.aris/repo." >&2
  echo "       Fix one of:" >&2
  echo "         1. rerun 'bash tools/install_aris.sh' from the ARIS repo (creates .aris/tools symlink, refreshes ~/.aris/repo)" >&2
  echo "         2. rerun 'bash tools/smart_update.sh' (refreshes ~/.aris/repo)" >&2
  echo "         3. export ARIS_REPO=<path-to-ARIS-repo>" >&2
  echo "         4. cp <ARIS-repo>/tools/research_wiki.py tools/" >&2
  exit 1
}
```

`/research-wiki` itself is the wiki tool — if the helper is missing the
skill **hard-fails**. Caller skills that update the wiki as a side
effect (`/idea-creator`, `/result-to-claim`, `/research-lit`, `/arxiv`,
`/alphaxiv`, `/deepxiv`, `/semantic-scholar`, `/exa-search`,
`/firecrawl-search`) use the
same chain but **warn-and-skip** instead of hard-failing — their
primary output (idea list, claim verdict, paper summary) must still be
delivered to the user.

### `/research-wiki init`

Initialize the wiki for the current project. After resolving
`$WIKI_SCRIPT` per the chain above:

```bash

From wanshuiyin/Auto-claude-code-research-in-sleep, MIT.

More from wanshuiyin/Auto-claude-code-research-in-sleep