# Research Profile

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-jinleiphys-research-llm-wiki-research-profile`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jinleiphys](https://agentstack.voostack.com/s/jinleiphys)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jinleiphys](https://github.com/jinleiphys)
- **Source:** https://github.com/jinleiphys/research_LLM_wiki/tree/main/research-profile

## Install

```sh
agentstack add skill-jinleiphys-research-llm-wiki-research-profile
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Research Profile Maintenance (Schema v2)

This file is the canonical operational protocol. It is harness-neutral. The skill ships parallel `SKILL.md` (Claude Code entry) and `AGENTS.md` (Codex CLI entry) bodies that mirror each other; if you edit one, edit the other.

**Schema v2 (current)** introduces controlled vocabulary, tag-driven indexing, AUTO-marker profile sections, and an explicit `migrate` path from v1. See [Migration from v1](#7-migrate--bring-existing-pages-up-to-current-schema) below if you have a v1 wiki.

**v2.1 addition**: bi-temporal `timeline:` frontmatter for tracked facts that change over time (see "Bi-temporal facts" below). Existing pages adopt it lazily, on the first change to a tracked fact.

## Why this skill exists

Memory of "what the user has worked on" should not live only in the user's head and in scattered drafts. It should be a curated, persistent, **machine-queryable** artifact that:

1. Auto-loads into every new agent session, so the assistant starts with full context.
2. Captures **failures with reasons** — research's most common scarring is doing the same dead-end twice. The wiki remembers so the user doesn't have to.
3. Makes cross-cutting queries cheap. "What have I done on topic X?" should not require manual grep across years of notes; tag-driven indices answer it in one read.

This is the **factual record** of what the user has done, not a personality simulator.

## Wiki location

Resolution order on every invocation:

1. `RESEARCH_PROFILE_PATH` env var.
2. `~/.research-profile-path` (single-line absolute path).
3. Default: `~/research-wiki-personal/`.

This wiki is **private**. Treat the path with notebook-grade care. Recommend a local + private remote git repo. If the directory does not exist, ask before creating.

## The auto-load mechanism

The single most important file is `/profile.md` — a one-page summary structured to fit in /profile.md` (absolute path) to `~/.claude/CLAUDE.md` (user-level) or `/CLAUDE.md` (project-scoped).
2. First import shows an external-import approval dialog; approve once.
3. Every new session in scope has profile.md content at session start.

### On Codex CLI (uses `~/.codex/AGENTS.md` symlink)

Codex does not support `@import` ([openai/codex#17401](https://github.com/openai/codex/issues/17401)). Use Codex's documented global agent doc directly:

```bash
ln -sfn /profile.md ~/.codex/AGENTS.md
```

If `~/.codex/AGENTS.md` already has content, merge it into profile.md's "Working preferences" section first, then symlink. Per-project alternative: `cd  && ln -sfn /profile.md AGENTS.md`.

`project_doc_fallback_filenames` does NOT work for `~/.codex/profile.md` — that mechanism only walks the project tree, never `~/.codex/`. The `~/.codex/AGENTS.md` symlink is the only reliable global path.

## Controlled vocabulary (the v2 contract)

Tag drift breaks indexing. To prevent it, all tag values come from a controlled vocabulary stored in `/CLAUDE.md` (the per-wiki schema file the skill respects). The vocabulary defines six axes:

| Axis | What it tracks | Examples |
|---|---|---|
| `methods` | analytical / numerical / experimental methods | `cdcc`, `iav-cdcc`, `monte-carlo`, `ab-initio` |
| `observables` | physical quantities computed or measured | `breakup-cs`, `fusion-suppression-factor`, `polarization` |
| `codes` | code packages used | `fresco`, `ncsm`, `julia-nucleartoolkit` |
| `topics` | physics themes / open questions | `icf`, `cf-suppression`, `weakly-bound`, `halo-nuclei` |
| `systems` | specific reactions or nuclei | `d+93Nb`, `6Li+209Bi`, `11Li` |
| `collaborators` | people the user works with | `moro`, `phillips`, `furnstahl` |

### Vocabulary file format

Each axis is a YAML map of `slug → entry`:

```yaml
vocabulary:
  methods:
    cdcc:
      canonical: "Continuum-Discretized Coupled Channels"
      aliases: [CDCC, "continuum-discretized", "continuum discretized coupled channels"]
    iav-cdcc:
      canonical: "Ichimura-Austern-Vincent CDCC for transfer/breakup"
      aliases: [IAV-CDCC, "IAV CDCC"]
      parent: cdcc           # iav-cdcc IMPLIES cdcc; index propagates upward
  topics:
    icf:
      canonical: "Incomplete fusion"
      aliases: [ICF, 不完全融合]
  ...
```

- `canonical` — human-readable name. Required.
- `aliases` — alternate spellings (case-insensitive, multi-language). The agent normalizes any alias to the slug. Optional.
- `parent` — hierarchical inclusion. A page tagged with the child slug is auto-included in indices for the parent. Optional.

A starter `templates/CLAUDE.md` ships with the skill; copy it to `/CLAUDE.md` on `init` and grow as papers are added.

### Vocabulary discipline

When the agent adds tags during any `log` operation:

1. **Look up** each candidate value against the vocabulary file. Use case-insensitive alias-aware matching.
2. **If known**: use the canonical slug (NOT the user's spelling).
3. **If unknown**: STOP. Propose a vocabulary diff to the user with a definition and suggested aliases. Apply only after explicit approval. Then update the page.

This is non-negotiable. **Never invent a tag silently.** The cost of a stop-and-ask is small; the cost of a polluted vocabulary compounds for years.

Escape hatch: an `uncategorized` slug is reserved across all axes for genuinely-novel content where the user wants to defer categorization. `lint` will report when uncategorized usage exceeds 30% of any axis (signal that taxonomy needs work).

## Wiki layout

```
/
├── CLAUDE.md / AGENTS.md      # ⭐ vocabulary + per-wiki style overrides
├── profile.md                 # ⭐ auto-loaded one-pager (AUTO + manual sections)
├── index.md                   # navigation hub (manual; links into index/ tree)
├── log.md                     # chronological append-only log
├── projects/{active,paused,done}/
├── papers/{published,submitted,drafts,rejected}/
│   └── *.md + *.private.md    # ALWAYS paired: public stub + private companion
├── ideas/{promising,parked,killed}/
├── methods-mine/
├── failures/                  # ⭐ what didn't work and why
├── collaborators/
├── talks/  reviews/  snapshots/  funding/
└── index/                     # ⭐ AUTO-generated by update-index, do not hand-edit AUTO blocks
    ├── by-method/.md
    ├── by-observable/.md
    ├── by-codes/.md
    ├── by-topic/.md     ← also serves as your "research line" page
    ├── by-system/.md
    └── by-collaborator/.md
```

**Important**: `index/by-topic/.md` and `index/by-method/.md` doubly serve as **research-line pages**. They have a hand-written preamble (motivation, key insight, current state, "is this line still alive?") above the AUTO block, which lists papers / ideas / failures / methods carrying that tag. There is no separate `lines/` page type — a topic that has 3+ papers IS a research line.

## Common frontmatter

Every non-profile page carries:

```yaml
---
type: project | paper | idea | failure | method | collaborator | talk | review | funding
status: 
created: YYYY-MM-DD
last_updated: YYYY-MM-DD
sensitivity: public | private | embargoed   # default private

# Tag axes (use vocabulary canonical slugs only; ask before adding new vocab)
methods: []
observables: []
codes: []
topics: []
systems: []
collaborators: []

# Lineage (papers / projects / ideas; optional otherwise)
predecessor: [[other-page]]
successor: [[other-page]]
companion: [[other-page]]

# Profile featuring (optional override)
featured: false   # if true, force this onto profile.md regardless of activity heuristics

# Cross-link into literature-wiki (when relevant)
literature: [[../research-wiki/methods/]]

# Bi-temporal history (v2.1; append-only; omit until a tracked fact first changes)
timeline:
  - fact: "what was true"
    from: YYYY-MM-DD            # event time: when it became true
    until: YYYY-MM-DD | present
    learned: YYYY-MM-DD         # transaction time: when the wiki learned it
    source: "user 2026-05-19 | [[log.md entry]] | email | referee report"
---
```

### Bi-temporal facts (v2.1)

When a tracked fact on an existing page changes, never overwrite it and never record the change only as a prose patch. Tracked facts are the ones that flip over a career: collaborator role / institution / retirement, paper status and revision stance, method maintenance status, project state.

Rules:

1. **Top-level frontmatter always reflects the CURRENT state** (`status:`, `role:`, `institution:`, ...). Queries against current state stay one-field cheap.
2. **The history goes into `timeline:`**, append-only, with both event time (`from`/`until`) and transaction time (`learned`) plus `source:` provenance. **`fact` is written as `key: value`** (e.g. `"status: submitted"`, `"institution: SCNT"`, `"revision_stance: multi-gpu accepted"`) so lint can group entries into fact families mechanically instead of guessing from free text. Approximate dates carry an inline `# approx` comment; never fabricate precision.
3. On the first change to a page that has no `timeline:` yet, create the block with TWO entries: the old state (reconstruct `from` as well as you can; `learned` may be the page's `created` date) and the new one.
4. Prose may still narrate the change (the "story" belongs in the body), but the timeline entry is the queryable record, not the prose.

Why bi-temporal: it distinguishes "the fact changed" from "two pages contradict each other" (different facts at different times are not a contradiction), it answers "what did I believe when, and why did it change" (e.g. a revision stance reversed after a referee round), and it survives profile refreshes that rewrite prose. (Pattern borrowed from obsidian-second-brain's bi-temporal facts rule.)

## Per-page schemas

### project (active | paused | done)

- Path: `projects//.md`
- Frontmatter: common + tag axes
- Required body:
  - `## Goal` — one paragraph
  - `## Methods used` — links to vocabulary slugs and `methods-mine/`
  - `## Current state` — what works, what doesn't, what's blocking
  - `## Code/repo` — absolute paths, including server (e.g. `heliumx:/scratch/jin/...`)
  - `## Collaborators` — slugs (vocabulary-controlled) + role each
  - `## Related literature` — links to `research-wiki/sources/` if literature-wiki installed
- Affects profile.md: yes if status=active OR featured=true.

### paper (published | submitted | drafts | rejected) — schema v2

The paper schema is the most-revised in v2. Key principle: **if a section can be reconstructed from the abstract a year from now, do not include it**. The wiki page captures what the abstract cannot.

- Path: `papers//.md` (public, safe to commit) **paired with** `papers//.private.md` (always created, gitignored by `*.private.md`).
- Frontmatter (paper-specific extras on top of common):
  - `title:`, `authors: [list, lead first]`
  - `submitted:` `first_decision:` `accepted:` `published:` (YYYY-MM-DD; optional per state)
  - `doi:`, `arxiv:`, `venue:`
  - tag axes (mandatory — at least one method, one topic, one system)
  - `predecessor:` / `companion:` / `successor:` lineage links
- Required body sections in `.md` (public):
  1. **`## Key claim`** — one sentence DEEPER than the abstract. The abstract has the claim; this is the claim with the actual hedge or qualifier the abstract glossed over.
  2. **`## My contribution`** — CRediT-style breakdown. Required structure: Conceptualization / Methodology / Software / Formal analysis / Writing — original draft / Writing — review. Mark each as "Lead | Equal | Contributing | Not involved" with the responsible co-author named for the lead-other items.
  3. **`## Code and data location`** — absolute paths including server hostname (e.g. `heliumx:/scratch/jin/cdcc-19/run42/`). Future-you will need this within 18 months.
  4. **`## Lineage`** — prose narrative of how this paper extends predecessor and what the next step is. Frontmatter has the links; body has the story.
  5. **`## Key numbers worth remembering`** — specific numerical results with their context (e.g. "epsilon = 0.27 ± 0.03 at Ec.m. = 38 MeV; matches m_pi/Lambda_chi = 0.28 (Sec. III.B)").
  6. **`## What I'd do differently now`** — future-self letter. Often becomes the seed of the successor paper.
- `.private.md` (companion, embargoed): see schema below.
- Affects profile.md: yes if status=published (last 24 months) OR status=submitted OR featured=true.

### paper.private (always create alongside paper)

- Path: `papers//.private.md`
- Frontmatter: `sensitivity: embargoed`, `paper: [[]]`
- Optional body sections (write as needed; the file slot is always created on `log paper`):
  - `## Reviewer N` — incoming reports, with date, journal, decision, verbatim quotes
  - `## Response drafts` — your reply text in progress
  - `## Internal correspondence` — slack/email summaries with co-authors about the paper
  - `## Co-author disagreements` — frank notes, who pushed back on what
- The public `.md` should cross-link with: `See [[.private]] for embargoed material.`
- **Never auto-quoted** to outputs that could leak (chat with non-private MCPs, public artifacts) without explicit user OK.

### idea (promising | parked | killed)

- Path: `ideas//.md`
- Frontmatter: common + tag axes
- Required body:
  - `## Seed thought` — what triggered it
  - One of `## Why promising` | `## Why parked` | `## Why killed` (matching status)
  - `## What would unblock it` (for promising/parked)
  - `## Relevant literature` — links into research-wiki when applicable
- **Killed ideas MUST include `## Why killed`** with concrete reason. Highest-value field for AI context: it prevents the agent from suggesting paths the user has already burned.
- Affects profile.md: killed ideas are surfaced under the auto "Strong opinions / dead ends" section; promising ideas surface only if `featured=true`.

### failure

- Path: `failures/.md`
- Frontmatter: common + tag axes (mandatory at least one method, one topic, one system — failures need to be findable by the same axes as papers)
- Required body:
  - `## What was tried`
  - `## Why it should have worked` — your prior belief
  - `## What actually happened` — observation
  - `## What was ruled out` — corollary findings
  - `## Conditions that might revive it` — when to revisit
- Affects profile.md: top 5 most informative are auto-surfaced under "Strong opinions / dead ends".

### method (mine)

- Path: `methods-mine/.md`
- Frontmatter: common + tag axes + `language` + `code_repo` + `license`
- Required body:
  - `## What it does` — one paragraph
  - `## Key API surface`
  - `## Gotchas`
  - `## Papers using it` — wikilinks (kept manually as a sanity check; auto-index also generates by-codes/.md)
- Affects profile.md: yes if status=active OR maintained.

### collaborator / talk / review (outgoing) / funding

(Compact; same shape as v1, with tag axes added.)

- **collaborator**: `collaborators/.md`. Frontmatter extras: `role: close|occasional|past`, `institution`, `expertise: [tags]`, `sensitivity: private` default. Body: `## How we met`, `## Common projects`, `## Communication preferences`, optional `## Frank notes` (sensitivity-gated). Role / institution / retirement changes append a `timeline:` entry (bi-temporal rule), never overwrite-only.
- **talk**: `talks/-.md`. Frontmatter extras: `venue`, `date`, `audience_level`, `public_url`. Body: `## Topic`, `## Key slides/figures`, `## What I'd change next time`.
- **review (outgoing)**: `reviews/-.md`. Always `sensitivity: embargoed`. Body: `## Paper summary`, `## My verdict`, `## Key concerns`, `## Lessons`.
- **funding**: `funding/-.md`. Frontmatter extras: `agency`, `status: submitted|awarded|rejected`, `amount`, `period`, `role`. Body: `## Project summary`, `## Key claims`, `## Deadlines`.

## Operations

### 1. `init` — first-time setup

Privileged-write operation; each side effect gated by confirmation.

1. **Resolve and confirm wiki path.** Default `~/research-wiki-personal/`. Stop if user declines.
2. **Create directory skeleton.** Copy `templates/profile.md` → `/profile.md`, `templates/.gi

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jinleiphys](https://github.com/jinleiphys)
- **Source:** [jinleiphys/research_LLM_wiki](https://github.com/jinleiphys/research_LLM_wiki)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jinleiphys-research-llm-wiki-research-profile
- Seller: https://agentstack.voostack.com/s/jinleiphys
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.