@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/research-refine-pipeline/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: "research-refine-pipeline"
+description: "Run an end-to-end workflow that chains `research-refine` and `experiment-plan`. Use when the user wants a one-shot pipeline from vague research direction to focused final proposal plus detailed experiment roadmap, or asks to \"\u4e32\u8d77\u6765\", build a pipeline, do it end-to-end, or generate both the method and experiment plan together."
+---
+
+# Research Refine Pipeline: End-to-End Method and Experiment Planning
+
+Refine and concretize: **$ARGUMENTS**
+
+## Overview
+
+Use this skill when the user does not want to stop at a refined method. The goal is to produce a coherent package that includes:
+
+- a problem-anchored, elegant final proposal
+- the review history explaining why the method is focused
+- a detailed experiment roadmap tied to the paper's claims
+- a compact pipeline summary that says what to run next
+
+This skill composes two existing workflows:
+
+1. `research-refine` for method refinement
+2. `experiment-plan` for claim-driven validation planning
+
+For stage-specific detail, read these sibling skills only when needed:
+
+- `../research-refine/SKILL.md`
+- `../experiment-plan/SKILL.md`
+
+## Core Rule
+
+Do not plan a large experiment suite on top of an unstable method. First stabilize the thesis. Then turn the stable thesis into experiments.
+
+## Default Outputs
+
+- `refine-logs/FINAL_PROPOSAL.md`
+- `refine-logs/REVIEW_SUMMARY.md`
+- `refine-logs/REFINEMENT_REPORT.md`
+- `refine-logs/EXPERIMENT_PLAN.md`
+- `refine-logs/EXPERIMENT_TRACKER.md`
+- `refine-logs/PIPELINE_SUMMARY.md`
+
+## Workflow
+
+### Phase 0: Triage the Starting Point
+
+- Extract the problem, rough approach, constraints, resources, and target venue.
+- Check whether `refine-logs/FINAL_PROPOSAL.md` already exists and still matches the current request.
+- If the proposal is missing, stale, or materially different from the current request, run the full `research-refine` stage.
+- If the proposal is already strong and aligned, reuse it and jump to experiment planning.
+- If in doubt, prefer re-running `research-refine` rather than planning experiments for the wrong method.
+
+### Phase 1: Method Refinement Stage
+
+Run the `research-refine` workflow and keep its V3 philosophy intact:
+
+- preserve the Problem Anchor
+- prefer the smallest adequate mechanism
+- keep one dominant contribution
+- modernize only when it improves the paper
+
+Exit this stage only when these are explicit:
+
+- the final method thesis
+- the dominant contribution
+- the complexity intentionally rejected
+- the key claims and must-run ablations
+- the remaining risks, if any
+
+If the verdict is still `REVISE`, continue into experiment planning only if the remaining weaknesses are clearly documented.
+
+### Phase 2: Planning Gate
+
+Before the experiment stage, write a short gate check:
+
+- What is the final method thesis?
+- What is the dominant contribution?
+- What complexity was intentionally rejected?
+- Which reviewer concerns still matter for validation?
+- Is a frontier primitive central, optional, or absent?
+
+If these answers are not crisp, tighten the final proposal first.
+
+### Phase 3: Experiment Planning Stage
+
+Run the `experiment-plan` workflow grounded in:
+
+- `refine-logs/FINAL_PROPOSAL.md`
+- `refine-logs/REVIEW_SUMMARY.md`
+- `refine-logs/REFINEMENT_REPORT.md`
+
+Ensure the experiment plan covers:
+
+- the main anchor result
+- novelty isolation
+- a simplicity or deletion check
+- a frontier necessity check if applicable
+- run order, budget, and decision gates
+
+### Phase 4: Integration Summary
+
+Write `refine-logs/PIPELINE_SUMMARY.md`:
+
+```markdown
+# Pipeline Summary
+
+**Problem**: [problem]
+**Final Method Thesis**: [one sentence]
+**Final Verdict**: [READY / REVISE / RETHINK]
+**Date**: [today]
+
+## Final Deliverables
+- Proposal: `refine-logs/FINAL_PROPOSAL.md`
+- Review summary: `refine-logs/REVIEW_SUMMARY.md`
+- Experiment plan: `refine-logs/EXPERIMENT_PLAN.md`
+- Experiment tracker: `refine-logs/EXPERIMENT_TRACKER.md`
+
+## Contribution Snapshot
+- Dominant contribution:
+- Optional supporting contribution:
+- Explicitly rejected complexity:
+
+## Must-Prove Claims
+- [Claim 1]
+- [Claim 2]
+
+## First Runs to Launch
+1. [Run]
+2. [Run]
+3. [Run]
+
+## Main Risks
+- [Risk]:
+- [Mitigation]:
+
+## Next Action
+- Proceed to `/run-experiment`
+```
+
+### Phase 5: Present a Brief Summary to the User
+
+```
+Pipeline complete.
+
+Method output:
+- refine-logs/FINAL_PROPOSAL.md
+
+Experiment output:
+- refine-logs/EXPERIMENT_PLAN.md
+- refine-logs/EXPERIMENT_TRACKER.md
+
+Pipeline summary:
+- refine-logs/PIPELINE_SUMMARY.md
+
+Best next step:
+- /run-experiment
+```
+
+## Output Protocols
+
+> Follow these shared protocols for all output files:
+> - **[Output Versioning Protocol](../../shared-references/output-versioning.md)** — write timestamped file first, then copy to fixed name
+> - **[Output Manifest Protocol](../../shared-references/output-manifest.md)** — log every output to MANIFEST.md
+> - **[Output Language Protocol](../../shared-references/output-language.md)** — respect the project's language setting
+
+## Key Rules
+
+- **Large file handling**: If the Write tool fails due to file size, immediately retry using Bash (`cat << 'EOF' > file`) to write in chunks. Do NOT ask the user for permission — just do it silently.
+
+- Do not let the experiment plan override the Problem Anchor.
+- Do not widen the paper story after method refinement unless a missing validation block is truly necessary.
+- Reuse the same claims across `FINAL_PROPOSAL.md`, `EXPERIMENT_PLAN.md`, and `PIPELINE_SUMMARY.md`.
+- Keep the main paper story compact.
+- If the method is intentionally simple, defend that simplicity in the experiment plan rather than adding new components.
+- If the method uses a modern LLM / VLM / Diffusion / RL primitive, make its necessity test explicit.
+- If the method does not need a frontier primitive, say that clearly and avoid forcing one.
+- Prefer the staged skills when the user only needs one stage; use this skill for the integrated flow.
+
+## Composing with Other Skills
+
+```
+/research-refine-pipeline -> one-shot method + experiment planning
+/research-refine   -> method refinement only
+/experiment-plan   -> experiment planning only
+/run-experiment    -> execution
+```
+

package/dist/skills/research-review/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: "research-review"
+description: "Get a deep critical review of research from GPT using a secondary Codex agent. Use when user says \"review my research\", \"help me review\", \"get external review\", or wants critical feedback on research ideas, papers, or experimental results."
+---
+
+# Research Review via a secondary Codex agent (xhigh reasoning)
+
+Get a multi-round critical review of research work from an external LLM with maximum reasoning depth.
+
+## Constants
+
+- REVIEWER_MODEL = `gpt-5.5` — Model used via a secondary Codex agent. Must be an OpenAI model (e.g., `gpt-5.5`, `o3`, `gpt-4o`)
+- **REVIEWER_BACKEND = `codex`** — Default: Codex xhigh reviewer. Use `--reviewer: oracle-pro` only when explicitly requested; if Oracle is unavailable, warn and fall back to Codex xhigh. **Same-family note:** this default reviewer is a second Codex/GPT agent — valid for Type-A completeness/drive review, but not a cross-family Type-B verdict; install a `skills-codex-claude-review` / `skills-codex-gemini-review` overlay for a cross-family acquittal (see `shared-references/reviewer-routing.md`).
+
+## Context: $ARGUMENTS
+
+## Prerequisites
+
+- Use `spawn_agent` and `send_input` when the user has explicitly allowed delegation or subagents.
+- If delegation is not allowed, run the same review loop locally and preserve the same deliverable structure.
+
+## Workflow
+
+### Step 1: Gather Research Context
+Before calling the external reviewer, compile a comprehensive briefing:
+1. Read project narrative documents (e.g., STORY.md, README.md, paper drafts)
+2. Read any memory/notes files for key findings and experiment history
+3. Identify: core claims, methodology, key results, known weaknesses
+
+### Step 2: Initial Review (Round 1)
+Send a detailed prompt with xhigh reasoning:
+
+```
+spawn_agent:
+  reasoning_effort: xhigh
+  message: |
+    [Full research context + specific questions]
+    Please act as a senior ML reviewer (NeurIPS/ICML level). Identify:
+    1. Logical gaps or unjustified claims
+    2. Missing experiments that would strengthen the story
+    3. Narrative weaknesses
+    4. Whether the contribution is sufficient for a top venue
+    Please be brutally honest.
+```
+
+### Step 3: Iterative Dialogue (Rounds 2-N)
+Use `send_input` with the returned agent id to continue the conversation:
+
+```text
+send_input:
+  target: [saved reviewer id from Step 2]
+  message: |
+    Please continue the review using the revised materials below.
+
+    Revised files:
+    - /absolute/path/to/file1
+    - /absolute/path/to/file2
+
+    Focus on unresolved weaknesses and whether the revision actually fixed them.
+```
+
+For each round:
+1. **Respond** to criticisms with evidence/counterarguments
+2. **Ask targeted follow-ups** on the most actionable points
+3. **Request specific deliverables**: experiment designs, paper outlines, claims matrices
+
+Key follow-up patterns:
+- "If we reframe X as Y, does that change your assessment?"
+- "What's the minimum experiment to satisfy concern Z?"
+- "Please design the minimal additional experiment package (highest acceptance lift per GPU week)"
+- "Please write a mock NeurIPS/ICML review with scores"
+- "Give me a results-to-claims matrix for possible experimental outcomes"
+
+### Step 4: Convergence
+Stop iterating when:
+- Both sides agree on the core claims and their evidence requirements
+- A concrete experiment plan is established
+- The narrative structure is settled
+
+### Step 5: Document Everything
+Save the full interaction and conclusions to a review document in the project root:
+- Round-by-round summary of criticisms and responses
+- Final consensus on claims, narrative, and experiments
+- Claims matrix (what claims are allowed under each possible outcome)
+- Prioritized TODO list with estimated compute costs
+- Paper outline if discussed
+
+Update project memory/notes with key review conclusions.
+
+### Step 6: Review Tracing
+
+Save a trace for every `spawn_agent`, `send_input`, or `oracle-pro` review call following `../shared-references/review-tracing.md`. Record the reviewer route, saved agent id, prompt summary, raw response path, decisions, and action items. This preserves the Claude mainline Review Tracing semantics while using Codex-native reviewer calls.
+
+## Key Rules
+
+- ALWAYS use `reasoning_effort: xhigh` for reviews
+- Send comprehensive context in Round 1 — the external model cannot read your files
+- Be honest about weaknesses — hiding them leads to worse feedback
+- Push back on criticisms you disagree with, but accept valid ones
+- Focus on ACTIONABLE feedback — "what experiment would fix this?"
+- Document the agent id for potential future resumption
+- The review document should be self-contained (readable without the conversation)
+
+## Prompt Templates
+
+### For initial review:
+"I'm going to present a complete ML research project for your critical review. Please act as a senior ML reviewer (NeurIPS/ICML level)..."
+
+### For experiment design:
+"Please design the minimal additional experiment package that gives the highest acceptance lift per GPU week. Our compute: [describe]. Be very specific about configurations."
+
+### For paper structure:
+"Please turn this into a concrete paper outline with section-by-section claims and figure plan."
+
+### For claims matrix:
+"Please give me a results-to-claims matrix: what claim is allowed under each possible outcome of experiments X and Y?"
+
+### For mock review:
+"Please write a mock NeurIPS review with: Summary, Strengths, Weaknesses, Questions for Authors, Score, Confidence, and What Would Move Toward Accept."

package/dist/skills/research-wiki/SKILL.md

@@ -0,0 +1,373 @@
+---
+name: research-wiki
+description: "Persistent research knowledge base that accumulates papers, ideas, experiments, claims, and their relationships across the entire research lifecycle. Inspired by Karpathy's LLM Wiki pattern. Use when user says \"知识库\", \"research wiki\", \"add paper\", \"wiki query\", \"查知识库\", or wants to build/query a persistent field map."
+argument-hint: [subcommand: init|ingest|sync|query|update|lint|stats]
+allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, WebSearch, WebFetch
+---
+
+# 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 testable scientific claim with evidence status |
+
+### 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.
+
+## 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
+
+### `/research-wiki init`
+
+Initialize the wiki for the current project:
+
+1. Create `research-wiki/` directory structure
+2. Create empty `index.md`, `log.md`, `gap_map.md`
+3. Create empty `graph/edges.jsonl`
+4. Log: "Wiki initialized"
+
+### `/research-wiki ingest "<paper title>" — arxiv: <id>`
+
+Add a paper to the wiki. This subcommand is thin wrapping around the
+canonical helper `python3 "$ARIS_REPO/tools/research_wiki.py" ingest_paper …`, which
+is the single implementation of paper ingest in ARIS (per
+[`shared-references/integration-contract.md`](../shared-references/integration-contract.md)
+— one helper, no copies). The helper does all of:
+
+1. **Fetch metadata** — queries the arXiv Atom API when `--arxiv-id` is given
+2. **Generate slug** — `<first_author_last_name><year>_<keyword>`
+3. **Check dedup** — skip an existing page unless `--update-on-exist`
+4. **Create page** — `papers/<slug>.md` with the schema below
+5. **Rebuild `index.md`** and `query_pack.md`
+6. **Append `log.md`**
+
+Edge extraction (step 5/8 in the old manual flow) is **not** in
+`ingest_paper`; do it as a follow-up with `add_edge` per relationship
+identified:
+
+```bash
+ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null)}"
+WIKI_SCRIPT=""
+[ -n "$ARIS_REPO" ] && [ -f "$ARIS_REPO/tools/research_wiki.py" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"
+[ -z "$WIKI_SCRIPT" ] && [ -f tools/research_wiki.py ] && WIKI_SCRIPT="tools/research_wiki.py"
+[ -z "$WIKI_SCRIPT" ] && [ -f ~/.codex/skills/research-wiki/research_wiki.py ] && WIKI_SCRIPT="$HOME/.codex/skills/research-wiki/research_wiki.py"
+
+# arXiv-known paper
+[ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
+    --arxiv-id 2501.12345 --thesis "One-line claim from abstract."
+
+# Venue paper with no arXiv mirror
+[ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
+    --title "Attention Is All You Need" \
+    --authors "Ashish Vaswani, Noam Shazeer, …" --year 2017 --venue "NeurIPS"
+
+# Manual edge after ingest
+[ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" add_edge research-wiki/ \
+    --from "paper:vaswani2017_attention_all_you" \
+    --to "paper:chen2025_factorized_gap" \
+    --type "extends" --evidence "Section 3.2: adapts the encoder block …"
+```
+
+Other skills (`/research-lit`, `/arxiv`, `/alphaxiv`, `/deepxiv`,
+`/semantic-scholar`, `/exa-search`) call the same helper directly in
+their own last step — they don't re-route through `/research-wiki
+ingest` as a subcommand, so they don't need an LLM roundtrip.
+
+### `/research-wiki sync — arxiv-ids <id1>,<id2>,...`
+
+Batch backfill: ingest one or more arXiv IDs that were read earlier
+without being ingested (e.g., because `research-wiki/` was set up after
+the reading happened, or a hook didn't fire).
+
+```bash
+# Explicit list
+[ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" sync research-wiki/ \
+    --arxiv-ids 2310.06770,1706.03762
+
+# From a file (one id per line, # comments ok)
+[ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" sync research-wiki/ --from-file ids.txt
+```
+
+Dedup is handled per-id; already-ingested papers are skipped silently.
+This is the recommended **manual repair** step (see integration
+contract §5 Backfill). `sync` does not scan session traces — callers
+declare the ids explicitly.
+
+**Paper page schema** (exactly what `ingest_paper` emits — do not
+handwrite alternative fields; `lint` will flag drift):
+
+```markdown
+---
+type: paper
+node_id: paper:<slug>
+title: "<full title>"
+authors: ["First A. Author", "Second B. Author"]
+year: 2025
+venue: "arXiv"
+external_ids:
+  arxiv: "2501.12345"
+  doi: null
+  s2: null
+tags: ["tag1", "tag2"]
+added: 2026-04-07T10:12:00Z
+---
+
+# <full title>
+
+## One-line thesis
+
+[Single sentence capturing the paper's core contribution]
+
+## Problem / Gap
+
+## Method
+
+## Key Results
+
+## Assumptions
+
+## Limitations / Failure Modes
+
+## Reusable Ingredients
+
+[Techniques, datasets, or insights that could be repurposed]
+
+## Open Questions
+
+## Claims
+
+[Reference claim pages: claim:C1, claim:C2, etc.]
+
+## Connections
+
+[AUTO-GENERATED from graph/edges.jsonl — do not edit manually]
+
+## Relevance to This Project
+
+[Why this paper matters for our specific research direction]
+```
+
+_Additionally, when the paper was ingested via `--arxiv-id` and the arXiv
+API returned an abstract, the helper appends an `## Abstract (original)`
+section after `Relevance to This Project` containing the raw abstract
+text as a blockquote. Manual ingests (no `--arxiv-id`) do not include
+this section._
+
+### `/research-wiki query "<topic>"`
+
+Generate `query_pack.md` — a compressed, context-window-friendly summary:
+
+**Fixed budget (max 8000 chars / ~2000 tokens):**
+
+| Section | Budget | Content |
+|---------|--------|---------|
+| Project direction | 300 chars | From AGENTS.md or RESEARCH_BRIEF.md |
+| Top 5 gaps | 1200 chars | From gap_map.md, ranked by: unresolved + linked ideas + failed experiments |
+| Paper clusters | 1600 chars | 3-5 clusters by tag overlap, 2-3 sentences each |
+| Failed ideas | 1400 chars | **Always included** — highest anti-repetition value |
+| Top papers | 1800 chars | 8-12 pages ranked by: linked gaps, linked ideas, centrality, relevance flag |
+| Active chains | 900 chars | limitation → opportunity relationship chains |
+| Open unknowns | 500 chars | Unresolved questions across the wiki |
+
+**Pruning priority** (when over budget): low-ranked papers > cluster detail > chain detail. **Never prune** failed ideas or top gaps first.
+
+**Key rule:** Read from short fields only (frontmatter, one-line thesis, gap summary, failure note). Do not summarize full page bodies every time.
+
+### `/research-wiki update <node_id> — <field>: <value>`
+
+Update a specific entity:
+
+```
+/research-wiki update paper:chen2025 — relevance: core
+/research-wiki update idea:001 — outcome: negative
+/research-wiki update claim:C1 — status: invalidated
+```
+
+After any update: rebuild `query_pack.md`, update `log.md`.
+
+### `/research-wiki lint`
+
+Health check the wiki:
+
+1. **Orphan pages** — entities with zero edges
+2. **Stale claims** — claims with `status: reported` older than 14 days
+3. **Contradictions** — claims with both `supports` and `invalidates` edges
+4. **Missing connections** — papers sharing 2+ tags but no explicit relationship
+5. **Dead ideas** — `stage: proposed` ideas that were never tested
+6. **Sparse pages** — pages with 3+ empty sections
+
+Output a `LINT_REPORT.md` with suggested fixes.
+
+### `/research-wiki stats`
+
+Quick overview:
+
+```
+📚 Research Wiki Stats
+Papers: 28 (12 core, 10 related, 6 peripheral)
+Ideas: 7 (2 active, 3 failed, 1 partial, 1 succeeded)
+Experiments: 12
+Claims: 15 (5 supported, 3 invalidated, 7 reported)
+Edges: 64
+Gaps: 8 (3 unresolved)
+Last updated: 2026-04-07T10:12:00Z
+```
+
+## Integration with Existing Workflows
+
+All paper-reading skills follow the same **integration contract** (see
+[`shared-references/integration-contract.md`](../shared-references/integration-contract.md)):
+
+- single predicate — `[ -d research-wiki/ ]`
+- single canonical helper — `python3 "$ARIS_REPO/tools/research_wiki.py" ingest_paper …`
+- concrete artifact — `papers/<slug>.md` + `log.md` entry
+- backfill — `sync --arxiv-ids …`
+- diagnostic — `verify_wiki_coverage.sh` (Policy E; resolved per integration-contract §2)
+
+### Hook 1: After `/research-lit` finds papers
+
+```
+# At end of research-lit, after synthesis:
+if research-wiki/ exists:
+    ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null)}"
+    WIKI_SCRIPT=""
+    [ -n "$ARIS_REPO" ] && [ -f "$ARIS_REPO/tools/research_wiki.py" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"
+    [ -z "$WIKI_SCRIPT" ] && [ -f tools/research_wiki.py ] && WIKI_SCRIPT="tools/research_wiki.py"
+    [ -z "$WIKI_SCRIPT" ] && [ -f ~/.codex/skills/research-wiki/research_wiki.py ] && WIKI_SCRIPT="$HOME/.codex/skills/research-wiki/research_wiki.py"
+    for paper in top_relevant_papers (limit 8-12):
+        [ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
+            --arxiv-id <id> [--thesis "..."] [--tags "..."]
+        for each explicit relation to existing wiki paper:
+            [ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" add_edge research-wiki/ \
+                --from "paper:<slug>" --to "<target>" \
+                --type <extends|contradicts|addresses_gap|...> \
+                --evidence "..."
+    log "research-lit ingested N papers"
+```
+
+Each paper-reading skill ships its own Step "Update Research Wiki (if
+active)" that calls the same helper once per paper it touched. The
+business logic is not duplicated — only the loop over that skill's
+specific result set differs.
+
+### Hook 2: `/idea-creator` reads AND writes wiki
+
+**Before ideation:**
+```
+if research-wiki/query_pack.md exists (and < 7 days old):
+    prepend query_pack to landscape context
+    treat failed ideas as banlist
+    treat top gaps as search seeds
+    still run fresh literature search for last 3-6 months
+```
+
+**After ideation (THIS IS CRITICAL — without it, ideas/ stays empty):**
+```
+for idea in all_generated_ideas (recommended + killed):
+    /research-wiki upsert_idea(idea)
+    for paper_id in idea.based_on:
+        add_edge(idea.node_id, paper_id, "inspired_by")
+    for gap_id in idea.target_gaps:
+        add_edge(idea.node_id, gap_id, "addresses_gap")
+rebuild query_pack
+log "idea-creator wrote N ideas to wiki"
+```
+
+### Hook 3: After `/result-to-claim` verdict
+
+```
+# Create experiment page
+exp_id = upsert_experiment(experiment_data)
+
+# Update each claim's status
+for claim_id in resolved_claims:
+    if verdict == "yes":
+        set_claim_status(claim_id, "supported")
+        add_edge(exp_id, claim_id, "supports")
+    elif verdict == "partial":
+        set_claim_status(claim_id, "partial")
+        add_edge(exp_id, claim_id, "supports")  # partial
+    else:
+        set_claim_status(claim_id, "invalidated")
+        add_edge(exp_id, claim_id, "invalidates")
+
+# Update idea outcome
+update_idea(active_idea_id, outcome=verdict)
+
+# If failed, record WHY for future ideation
+if verdict in ("no", "partial"):
+    update_idea failure_notes with specific metrics and reasons
+
+rebuild query_pack
+log "result-to-claim: exp_id updated, verdict=..."
+```
+
+## Re-ideation Trigger
+
+After significant wiki updates, suggest re-running `/idea-creator`:
+
+- ≥5 new papers ingested since last ideation
+- ≥3 new failed/partial ideas since last ideation
+- New contradiction discovered in the graph
+- New gap identified that no existing idea addresses
+
+The system suggests but does not auto-trigger. User decides.
+
+## Key Rules
+
+- **One source of truth for relationships**: `graph/edges.jsonl`. Page `Connections` sections are auto-generated views.
+- **Canonical node IDs everywhere**: `paper:<slug>`, `idea:<id>`, `exp:<id>`, `claim:<id>`, `gap:<id>`. Never use raw titles or inconsistent shorthands.
+- **Failed ideas are the most valuable memory.** Never prune them from query_pack.
+- **query_pack.md is hard-budgeted** at 8000 chars. Deterministic generation, not open-ended summarization.
+- **Append to log.md for every mutation.** The log is the audit trail.
+- **Reviewer independence applies.** When the wiki is read by cross-model review skills, pass file paths only — do not summarize wiki content for the reviewer.
+
+## Acknowledgements
+
+Inspired by [Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — "compile knowledge once, keep it current, don't re-derive on every query."