Research Profile

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).

1. First import shows an external-import approval dialog; approve once.
2. 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). Use Codex's documented global agent doc directly:

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:

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:

---
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 mpi/Lambdachi = 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
• Source: jinleiphys/researchLLM_wiki
• License: MIT

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