Research Project Memory

Maintain project memory as a layered system, not a flat notes file. This skill gives agents a shared protocol for remembering what a research project is trying to prove, what evidence exists, what risks remain, and which component owns each next action.

Use this skill when:

• a project needs cross-session memory beyond remote execution state
• the user wants memory across paper/, code/, worktrees, slides/, reviewer simulation, or rebuttal
• claims, experiments, figures, paper sections, reviewer risks, and actions need to stay aligned
• a session materially changes project direction, evidence, writing, review risks, or planned experiments
• a new agent session needs bootstrap context before acting
• the user asks for a memory system, project state graph, claim/evidence board, worktree memory, or closeout protocol

This is a coordination skill. It does not replace remote-project-control, experiment-design-planner, conference-writing-adapter, paper-reviewer-simulator, or rebuttal-strategist; it tells them where and how to persist trusted project state.

Skill Directory Layout

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── closeout-protocol.md
│   ├── consistency-checks.md
│   ├── memory-architecture.md
│   ├── object-schemas.md
│   └── writeback-protocol.md
└── templates/
    ├── component/
    │   ├── component-status.md
    │   └── worktree-status.md
    └── memory/
        ├── action-board.md
        ├── claim-board.md
        ├── component-index.yaml
        ├── current-status.md
        ├── decision-log.md
        ├── evidence-board.md
        ├── project.yaml
        └── risk-board.md

Progressive Loading

• Always read references/memory-architecture.md, references/object-schemas.md, and references/writeback-protocol.md.
• Read references/consistency-checks.md when asked to audit project state, prepare a milestone, submit, write, review, or rebut.
• Read references/closeout-protocol.md before ending a substantial session or updating memory after meaningful work.
• Use templates/ as the source of truth when bootstrapping missing memory files.

Core Principles

• Memory is coordination context, not execution truth.
• Stable claims, decisions, risks, and component mappings belong in repo memory.
• Volatile facts such as dirty git state, queue state, active jobs, and file existence must be re-verified.
• Every important claim should link to evidence, a paper location, and current risks.
• Every reviewer or rebuttal risk should link to an action, a decision to accept the risk, or a reason it is out of scope.
• Every worktree should have a purpose and an exit condition: merge, continue, park, or kill.
• Mark certainty: observed, user-stated, inferred, stale, or needs-verification.
• Write memory at the most specific layer that will help the next session.

Step 1 - Locate the Project and Existing Memory

Detect the project root:

git rev-parse --show-toplevel 2>/dev/null || pwd

Then inspect likely memory files:

• memory/project.yaml
• memory/component-index.yaml
• memory/current-status.md
• memory/decision-log.md
• memory/claim-board.md
• memory/evidence-board.md
• memory/risk-board.md
• memory/action-board.md
• paper/.agent/
• code/.agent/
• slides/.agent/
• reviewer/.agent/
• rebuttal/.agent/

If the project uses another layout, adapt the component paths but keep the same memory roles.

Step 2 - Bootstrap Missing Memory

If the user asks to initialize memory, or if memory is missing and the task depends on it, create the minimum useful files from templates:

• templates/memory/project.yaml -> memory/project.yaml
• templates/memory/component-index.yaml -> memory/component-index.yaml
• templates/memory/current-status.md -> memory/current-status.md
• templates/memory/decision-log.md -> memory/decision-log.md
• templates/memory/claim-board.md -> memory/claim-board.md
• templates/memory/evidence-board.md -> memory/evidence-board.md
• templates/memory/risk-board.md -> memory/risk-board.md
• templates/memory/action-board.md -> memory/action-board.md
• templates/component/component-status.md -> <component>/.agent/<component>-status.md
• templates/component/worktree-status.md -> <code-worktree>/.agent/worktree-status.md when a worktree needs its own memory

Ask only for fields that cannot be inferred safely:

• project name
• project root
• component paths
• current research question
• current target venue or milestone, if any
• whether memory files should be committed

Step 3 - Build the Bootstrap Summary

Before substantial work, summarize:

• project name and root
• current research question and positioning
• target venue or milestone
• active components and paths
• current claim IDs
• current evidence IDs and latest reliable result
• top risks and blockers
• active actions and owners
• stale or missing memory
• facts that must be verified before acting

Keep the summary compact. Do not paste entire boards unless the user asks.

Step 4 - Write to the Right Layer

Read references/writeback-protocol.md.

Use this routing:

• whole-project identity, target venue, component paths, memory policy -> memory/project.yaml
• current focus, active milestone, next session entry point -> memory/current-status.md
• durable project decisions and why -> memory/decision-log.md
• paper claims and their status -> memory/claim-board.md
• experiments, analyses, proofs, citations, and figures that support claims -> memory/evidence-board.md
• reviewer, novelty, baseline, writing, execution, and rebuttal risks -> memory/risk-board.md
• concrete next tasks and owners -> memory/action-board.md
• component-specific state -> <component>/.agent/<component>-status.md
• code worktree purpose and exit condition -> <worktree>/.agent/worktree-status.md

When in doubt, write a short pointer at the project layer and details in the component layer.

Step 5 - Maintain the Claim-Evidence-Risk-Action Graph

Read references/object-schemas.md.

Use stable IDs:

• CLM-###: claim
• EVD-###: evidence item
• EXP-###: experiment or run family
• FIG-###: figure or table
• RSK-###: risk
• ACT-###: action
• DEC-###: decision
• WTR-###: worktree
• REV-###: review or rebuttal issue

Every major update should preserve links:

CLM-001 -> supported_by EVD-003 -> visualized_by FIG-002 -> threatened_by RSK-004 -> resolved_by ACT-007

Avoid orphan objects. If a claim has no evidence, mark it as planned, unsupported, or cut.

Step 6 - Run Consistency Checks

Read references/consistency-checks.md when auditing memory.

Check for:

• paper claims without evidence
• evidence without a claim or paper location
• reviewer risks without actions
• rebuttal promises without paper/code follow-up
• worktrees without exit condition
• stale results still used in writing
• slides that contradict paper status
• volatile state recorded as stable truth

Report mismatches as project risks or actions.

Step 7 - Close Out the Session

Read references/closeout-protocol.md.

Before ending a substantial session, update:

• memory/current-status.md
• any changed claim/evidence/risk/action board
• relevant component status file
• worktree status file if code branch direction changed
• memory/decision-log.md if a durable decision was made

Closeout should answer: what changed, what is trustworthy, what is stale, what should the next agent verify, and what is the next concrete action.

Final Sanity Check

Before finalizing:

• stable and volatile facts are separated
• new claims link to evidence or are marked unsupported
• new evidence links to a claim, component, and source path
• new risks link to actions or accepted-risk decisions
• worktree memory has a purpose and exit condition
• current-status gives the next session a clear starting point
• no private local path or credential is written into shared memory unless the user explicitly wants it