[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M74GPVPPRMCDKKCABNJM7GFE":3,"skill-same:01M74GPVPPRMCDKKCABNJM7GFE":86},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M74GPVPPRMCDKKCABNJM7GFE","research-workflow",null,"A meta-skill that defines the structural framework for collaborating with a researcher across the full research lifecycle. Use whenever the user is starting a new research project, working inside a numbered project directory under ~\u002FDocuments\u002Fproject, or asking how to organize research artifacts. This skill does NOT teach how to do research, write papers, or pick topics; it defines the constitution, directory layout, log discipline, and inter-skill routing that every research project must follow.","Siyuexi\u002Fcodex-research-kit","Siyuexi","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F50619651?v=4","01M74GNP0DQZKN3088BDHCKCDF","Junjielong Xu","01M74GNP13FNC637NW9K8V98HZ",0,"MIT","https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: research-workflow\ndescription: A meta-skill that defines the structural framework for collaborating with a researcher across the full research lifecycle. Use whenever the user is starting a new research project, working inside a numbered project directory under ~\u002FDocuments\u002Fproject, or asking how to organize research artifacts. This skill does NOT teach how to do research, write papers, or pick topics; it defines the constitution, directory layout, log discipline, and inter-skill routing that every research project must follow.\nlicense: MIT\n---\n\n# research-workflow — A Constitution for Research Collaboration\n\nThis skill is a **meta-skill**. It does not give domain advice (how to brainstorm, how to write a paper, how to design experiments). It defines:\n\n- **The constitution**: principles Codex must obey when collaborating on research\n- **The directory layout**: how every project under `~\u002FDocuments\u002Fproject\u002F` is organized\n- **The log discipline**: how decisions, debates, experiments, and changes are recorded over time\n- **The routing map**: which other research skills to invoke at which lifecycle stage\n\nWhen you are about to do anything research-related, this skill comes first. Domain skills (ideation, paper-writing, RL training) are invoked from within this framework.\n\n---\n\n## ⚠️ Sub-skills you MUST know about\n\nresearch-workflow has **four first-class sub-skills**. They are NOT optional tools — they are the framework's own dispatch points for common situations. If you find yourself manually doing what one of these handles, **stop and use the sub-skill instead** (or explain to the user why you're deviating).\n\n| Sub-skill | Triggers on | Workflow | What goes wrong without it |\n|---|---|---|---|\n| **`research-survey`** | \"调研一下 X 这个子方向\" \u002F sub-area sweep request, NOT a single-paper intake | Workflow E' | You'd run 10× sequential Workflow E and lose sub-topic context (axes, search trace, coverage). |\n| **`research-cowork`** | ≥ 1 `src-update` log entry with `status: todo` AND it's concrete code-writing in `src\u002F` | Workflow G | You'd write code serially in the main session, blow up context, and lose the PR audit trail. |\n| **`research-review`** | `bin\u002Freview-trigger` reports TRIGGER (≥ 10 new log entries since last review), OR user asks \"review 一下\" | Workflow H | You'd skip checkpoints; soundness\u002Fnovelty\u002Fconsistency\u002Fcoherence drift goes unnoticed until it's a crisis. (Architecture: two mutually blind Codex reviewer sub-agents plus a diff pass. Main Codex session only dispatches and presents.) |\n| **`vibe-report`** | User asks for a visual web report, `\u002Freport`, deployed report page, or report template | Reports | You'd keep re-deciding Claude\u002FCodex report roles and drift away from the shared HTML-primary\u002FMD-shadow artifact contract. |\n\n**How to spot them**: in the global skill list, most first-class workflow entries describe themselves as `[research-workflow sub-skill]`; `vibe-report` is intentionally independent but part of the same VRC report contract. They are scoped to research-workflow\u002FVRC projects — do not invoke them outside that context unless the user explicitly asks for a standalone report artifact.\n\nWhen in doubt about whether to dispatch to a sub-skill or handle inline: dispatch. The sub-skills enforce the input contracts and constitution rules that ad-hoc handling tends to skip.\n\n---\n\n## When to Use\n\n- The user starts a new research project (\"let's start a new topic on X\")\n- The current working directory is `~\u002FDocuments\u002Fproject\u002F[1-9][0-9]*-*\u002F`\n- The user asks \"how should I organize this\", \"where does this go\", or any question about the research workflow\n- Before invoking a domain research skill (brainstorming, paper-writing, etc.) — research-workflow provides the surrounding context\n\n## When NOT to Use\n\n- Pure coding tasks unrelated to a research project\n- Working inside `~\u002FDocuments\u002Fproject\u002F00-QuickReview\u002F` (this is a non-project scratch area; constitution does not apply)\n- One-shot questions that don't touch any research artifact\n\n---\n\n## Section 1 — The Constitution (non-negotiable)\n\nThese rules govern every interaction in a research-workflow project. They are listed here, and **enforced** by the project-level `AGENTS.md` that this skill writes during init.\n\n### C1. First-principles, always\n\nReject empiricism. Start from raw requirements. If the user's request seems suboptimal, **propose a shorter or cheaper alternative before executing**. If the goal is vague, stop and discuss.\n\n### C2. Cool-headed reviewer, not eager assistant\n\nCodex's role is a **calm peer reviewer** of the research progress. Never default to \"always push for changes\" nor \"always preserve the status quo\". On every proposed modification, weigh: is this change earning its complexity?\n\n### C3. The proposal is the kernel\n\n`proposal.md` is the project's nucleus. Every action — coding, experiments, paper-writing — must serve it. Two modification protocols apply:\n\n- **Minor change** (baseline swap, measurement tweak, presentation): edit `proposal.md` directly, log it as `proposal-update`\n- **Major change** (core hypothesis overturned, target metric replaced, claim scope shifted): **STOP. Surface the conflict to the user. Do not modify `proposal.md` until the user agrees.**\n\nIf unsure which class a change belongs to, treat it as major.\n\n### C4. Survey is sacred — never fabricate\n\nEntries in `survey.md` must be **factually correct**. Hard rule: **no entry may be added to `survey.md` until the corresponding paper PDF has been downloaded to `cache\u002Fpapers\u002F` AND the entry's `verified_by` field points to that file.**\n\nIf you've only seen an abstract, a citation, or a search result, the paper goes into a separate scratch list (`log\u002Fentries\u002F*_survey-add_*.md` with status=todo). It does NOT enter `survey.md`.\n\nThis is structural enforcement. Do not work around it.\n\n### C5. Modification order: proposal → src → output → doc\n\nWhen iterating, always propagate in this direction:\n\n1. Update `proposal.md` if the change is conceptual\n2. Update `src\u002F` to implement\n3. Run experiments, capture outputs in `src\u002Fdata\u002F`, summarize in `result.md`\n4. Only then update `doc\u002F` to reflect new findings\n\n`doc\u002F` is the **lagging mirror** of validated state. Never write claims into `doc\u002F` that aren't backed by `result.md` confirmed findings. Use `\\todo{}` placeholders if a section needs scaffolding before results land.\n\n### C6. Holistic view — touch one thing, check the rest\n\nA change to `src\u002F` may invalidate a `proposal.md` design choice, which may obsolete a `TODO` log entry, which may require `doc\u002F` rewriting. After any non-trivial change, scan adjacent artifacts and surface implications.\n\n### C7. Discuss before acting on uncertainty\n\nWhen you're not sure whether something is correct, or have no objective evidence — **ask, don't guess**. This is more important than appearing decisive.\n\n### C8. Reset session cache deliberately when context bloats or when crossing a task boundary\n\nLong contexts degrade Codex's reasoning. **Multiple sessions on one project is the norm, not a failure mode** — the `sessions:` field in log entries is plural for this reason. A 30-minute session at peak quality beats a 3-hour session at 60% quality.\n\nFor Feishu-mediated topic work, use the cache model shared by Claude and Codex:\n\n| Level | Where it lives | Purpose |\n|---|---|---|\n| **L1** | live agent CLI session (`session_id`) | immediate reasoning context |\n| **L2** | latest handoff log under `log\u002Fentries\u002F` | one-file reload after rotation |\n| **L3** | `log\u002Fsession-index.md`, `log\u002Fentries\u002F`, workspace docs | durable project memory |\n\nAt roughly 50% measured context usage, the bridge should rotate: write L1 to an L2 handoff, clear the session id, then start the next dispatch fresh with an explicit pointer to that handoff. Workspace logs are authoritative; private agent memory indexes are only discovery aids.\n\n**Trigger signals (any one is enough)**:\n\n- The conversation has crossed ~50 turns or has been auto-compacted at least once\n- Recent answers feel hedged, repetitive, or have lost track of earlier decisions\n- The user is about to start a clearly different sub-task (proposal → src, src → doc, debugging → ideation). Task boundaries are natural session boundaries.\n\n**When triggered in a normal Codex TUI session, do NOT just suggest `\u002Fclear`. Run the handoff protocol**:\n\n1. Write a fresh log entry of type `decision`, slug `session-handoff-\u003Cshort-context>`, with `sessions: [\u003Ccurrent-session-id-if-known-else-empty>]`. The entry body MUST be **self-contained** — a fresh Codex reading only this entry (not the old session) should be able to continue without loss. Required fields in the body:\n\n   - **Where we are**: 1-3 sentences on current project stage and what just finished\n   - **Current understanding**: increments not yet captured in `proposal.md` \u002F `result.md` \u002F other log entries. This is the most important part — it's the bridge between sessions.\n   - **Next concrete step**: one sentence on what the new session should do first\n   - **Required reading (ordered)**: file paths and log entries the new session must read before acting\n   - **Open questions awaiting user**: if any, the new session's first move is to ask\n\n2. Tell the user: *\"I suggest `\u002Fclear` and starting a new session. The handoff is at `log\u002Fentries\u002F\u003Cfilename>`. Start the new session by asking me to read it.\"*\n\n3. The new session's first action is to read `AGENTS.md` and the handoff entry. It then appends its own session-id to the handoff entry's `sessions:` field so the audit chain is preserved.\n\n**Why this design**: the handoff body — not the session jsonl archive — is what makes continuity work. `\u002Fclear` removes the session from active memory; Codex does keep a jsonl archive on disk, but treat it as audit material, not as the substrate of cross-session continuity. The session-id pointer is plural so you can chain handoffs across many sessions on the same logical work thread.\n\n**Feishu bridge sessions**: the bridge owns `session_id`, not the agent. Use controller-only `@bridge clear-session \u003Cagent|all>` for a clean manual reset: the bridge should make the old session write a handoff, clear the sid, and make the next dispatch fresh with an L2 pointer. Use `@bridge clear-session \u003Cagent|all> --no-handoff` only for deliberate hard resets such as smoke-test or version-cutover contamination; this clears L1 without creating an L2 handoff, but should still leave an audit row in `log\u002Fsession-index.md`.\n\n**Special case: code-task handoff via GitHub issue**\n\nWhen all of the following conditions hold, open a GitHub issue as the handoff artifact (in addition to a thin local log entry):\n\n1. The work being handed off is a **concrete code task** in `src\u002F` (not a discussion, not exploratory debugging, not ideation)\n2. `src\u002F` has a GitHub remote (`git -C src remote -v` shows a github.com URL)\n3. `gh auth status` succeeds (gh CLI is authenticated)\n4. The task is scoped well enough to write a one-line PR title\n5. The working tree is either clean OR the WIP can be precisely described so the next session can resume without losing changes\n\nIf any condition fails, fall back to the default markdown handoff above. Tell the user which condition failed.\n\nWhen the conditions hold:\n\n1. Draft the issue body using the **same 5 fields** as the markdown handoff (Where we are \u002F Current understanding \u002F Next concrete step \u002F Required reading \u002F Open questions). Add a trailing line: *\"This issue is a research-workflow session handoff. Resolve by opening a PR.\"*\n2. Open the issue: `gh issue create --title \"\u003Cone-line task>\" --body \"...\" --label research-workflow:handoff` — drop the `--label` flag if the label doesn't exist in the repo; **do not auto-create labels**.\n3. **Still write a local log entry** of type `decision`, slug `session-handoff-\u003Cshort>`. Body is minimal: one-line summary plus a `gh_issue: \u003Curl>` field. This keeps `log-filter` aware of the handoff alongside non-code handoffs.\n4. Tell the user: *\"Issue opened at `\u003Curl>`. Suggest `\u002Fclear`. The new session should read the issue and open a branch to resolve it.\"*\n\nThe new session's first action: read the issue, read `AGENTS.md` and any files the issue references, then `git checkout -b` and start work. When the PR lands and the issue closes, update the local log entry's `status` to `done`.\n\nThe GitHub issue is the **source of truth** for code-task handoffs; the local log entry is a pointer so the timeline filter stays complete.\n\n**Connection to Workflow G**: a single handoff issue is resumed by the next session as a normal `gh issue` → branch → PR. When **multiple** open code-task issues accumulate (e.g., several past handoffs, or a queue of `src-update` TODOs that all need execution), the natural next step is Workflow G — batch them through `research-cowork` rather than resolving them one-by-one in a single session.\n\n### C9. Offer to commit at the end of an independent unit of work\n\nThe root git is a **local-only audit log** of the research timeline (see Section 2 \"Version control\"). It only accumulates value if commits actually land. There is **no fixed rhythm and no hook**: you decide, per moment, whether a meaningful unit of root-tracked work has just finished, and if so, you ask the user whether to commit. The user always decides; you never commit silently.\n\n**When to ask** (any one is a reasonable trigger — use judgment, not a checklist):\n\n- A `research-survey` sub-topic sweep has fully landed (brief + candidates + survey markdown all written)\n- A `research-review` checkpoint has produced its four artifacts (brief \u002F codex \u002F codex \u002F diff)\n- A `research-cowork` batch has finished merging and its log entries are settled\n- `proposal.md` just took a Workflow B major change, or accumulated several minor edits\n- `result.md` gained a new Confirmed Finding or Failed Attempt\n- A session handoff entry was just written (commit before the user `\u002Fclear`s)\n- A clear topical boundary has been crossed and several root-tracked files are dirty, even if none of the above fits exactly\n\n**When NOT to ask**:\n\n- Mid-workflow, with files only half-written (wait for the unit to land)\n- After a `src\u002F` or `doc\u002F` submodule edit where the submodule itself hasn't been committed-and-pushed yet — bumping the pointer to a dirty submodule is worse than not committing (see Section 2 \"Version control\")\n- For changes confined to `cache\u002F` or other gitignored paths\n- When the only dirty files are unrelated incidental edits (e.g., a single `AGENTS.md` typo) — batch with the next real unit instead\n\n**How to ask** — one short sentence, naming the unit and the files. Example:\n\n> *\"Survey sweep on `swe-process-reward` is done — 3 new files under `survey\u002F`, 1 new log entry. Commit root now? Suggested message: `survey: swe-process-reward sweep`.\"*\n\nIf the user says yes:\n\n1. `git -C \u003Cproject-root> status` to confirm what's actually dirty.\n2. Stage only research artifacts (`log\u002F`, `survey\u002F`, `review\u002F`, `proposal.md`, `result.md`, `survey.md`, `AGENTS.md`, `log\u002Findex.md`, `.gitignore`, `.gitmodules`). Do **not** `git add src` or `git add doc` unless the submodule itself was just committed-and-pushed in this turn — bumping pointers is a separate commit (see VC section).\n3. Use a structured prefix in the message so `git log --oneline` reads as a research timeline. Suggested prefixes: `log:`, `survey:`, `review:`, `cowork:`, `proposal:`, `result:`, `handoff:`, `bump:` (for submodule pointer bumps), `chore:` (for config\u002Fignore tweaks).\n4. Show the resulting commit hash + one-line summary back to the user.\n\nIf the user says no or \"later\" — drop it. Do not nag. The next natural unit boundary will surface the question again.\n\n---\n\n## Section 2 — Project Directory Structure\n\nEvery project lives under `~\u002FDocuments\u002Fproject\u002FNN-\u003Cslug>\u002F`, where `NN` is a zero-padded sequence number (01, 02, ...). `00-QuickReview\u002F` is reserved as a non-project scratch area for early literature\u002Frepo exploration.\n\n### Layout\n\n```\n~\u002FDocuments\u002Fproject\u002F\n  00-QuickReview\u002F                  # NON-PROJECT. Scratch for early exploration.\n                                   # Constitution does NOT apply here.\n  NN-\u003Cslug>\u002F                       # A project. Constitution applies.\n    AGENTS.md                      # Project-level persistent context (status, key constraints)\n    proposal.md                    # The kernel\n    survey.md                      # Verified related work (each row has verified_by)\n    result.md                      # Confirmed Findings + Failed Attempts (two sections)\n    talk.pptx                      # OPTIONAL. Reuse-only: presentation\u002Ftalk after research done.\n                                   # NOT used for figures in the paper.\n    survey\u002F                        # Sub-topic surveys (one file per sub-area). See research-survey skill.\n                                   # Markdown only — text artifacts the project lead reviews.\n                                   # PDFs are NOT here; they go to cache\u002Fpapers\u002F. Each sub-topic\n                                   # survey is independent; promotion to the root survey.md is by\n                                   # explicit Workflow E call (per row).\n      \u003Cslug>.brief.md              # Input contract for the worker (dispatcher fills)\n      \u003Cslug>.md                    # Worker's output: structured sub-topic survey\n      \u003Cslug>.candidates.md         # Audit trail of all candidates considered\n    cache\u002F                         # Project-level cache. Heavy\u002Fbinary artifacts only —\n                                   # never the substance of the project. If `src\u002F` or `doc\u002F`\n                                   # adopts git, cache\u002F MUST be in their .gitignore.\n      papers\u002F                      # Downloaded paper PDFs (referenced by survey.md AND survey\u002F*.md)\n      repos\u002F                       # Third-party repos cloned for reference\n      datasets\u002F                    # Original dataset downloads (before src ingestion)\n      cowork\u002F                      # Per-batch worktrees + worker artifacts (research-cowork).\n                                   # cache\u002Fcowork\u002F\u003Cbatch-id>\u002F\u003Cissue>-\u003Cslug>\u002F holds the\n                                   # git worktree, prompt.txt, events.jsonl, result.md.\n      review\u002F                      # Per-review scratch artifacts (research-review).\n                                   # cache\u002Freview\u002F\u003Cts>\u002F may hold dispatcher notes or validation\n                                   # scratch. The .md REPORTS themselves live in\n                                   # the tracked review\u002F directory, not here.\n    review\u002F                        # Key-checkpoint reviews (see research-review skill). Tracked.\n                                   # \u003Cts>.brief.md \u002F \u003Cts>.a.md \u002F \u003Cts>.b.md \u002F \u003Cts>.diff.md\n                                   # .state holds last_reviewed_log_count cursor.\n    log\u002F                           # Project timeline (see Section 5)\n      session-index.md             # Session rotation index for Feishu-mediated agents.\n      index.md                     # Auto-maintained reverse-chronological table\n      entries\u002F                     # Individual event files\n    report\u002F                        # User-facing reports. HTML primary, MD shadow.\n      YYYY-MM-DD_\u003Cslug>.html       # Self-contained visual report.\n      YYYY-MM-DD_\u003Cslug>.md         # Markdown shadow for Feishu Docx export.\n      assets\u002F\n        lib\u002F                       # Optional vendored chart\u002Fmath\u002Fcode libs.\n        \u003Cslug>\u002F                    # Per-report generated assets.\n    doc\u002F                           # LaTeX paper repo. Submodule of root.\n                                   # Independent git, Overleaf-cloned. Content is whatever\n                                   # Overleaf has — do NOT pre-stage files here before clone.\n      figures\u002F                     # ALL figures live here. Two kinds:\n                                   #   schematic: fig-\u003Cslug>.tex (standalone TikZ) + .pdf\n                                   #   result:    fig-\u003Cslug>.pdf  (copied from src\u002Fdata\u002Ffigures\u002F)\n                                   # No PNG\u002FJPG. PDF only.\n      sections\u002F                    # Per-section .tex files\n      main.tex\n    src\u002F                           # Code repo. Submodule of root.\n                                   # Independent git, bound to user's GitHub.\n      data\u002F                        # Datasets and experimental outputs (gitignored)\n      .gitignore                   # Must ignore data\u002F\n    .git\u002F                          # Root git. Local-only by default (no remote required).\n                                   # Tracks research artifacts + the two submodule pointers.\n                                   # See \"Version control\" below.\n    .gitignore                     # Excludes cache\u002F, legacy\u002F (if present), .DS_Store, etc.\n    .gitmodules                    # Lists src\u002F and doc\u002F submodules\n```\n\n### Version control (three-git layout)\n\nA research-workflow project uses **three independent gits**, with `src\u002F` and `doc\u002F` wired into the root as **submodules**:\n\n| Git | Scope | Remote | Tracked content |\n|---|---|---|---|\n| **root** | the project as a whole | optional (local-only by default) | `AGENTS.md`, `proposal.md`, `survey.md`, `result.md`, `log\u002F`, `survey\u002F`, `.gitignore`, `.gitmodules`, and the two submodule pointers |\n| **`src\u002F`** (submodule) | code | required (GitHub) | code, tests, scripts |\n| **`doc\u002F`** (submodule) | paper | required (Overleaf) | LaTeX sources, figures, bibliography |\n\n**Why three gits:**\n- Each subrepo has a natural external remote (GitHub for code, Overleaf for paper) with its own commit cadence, contributors, and CI. Bundling them into one repo would force every paper edit through a code-repo PR and vice versa.\n- The root is the **assembly point**. It pins which commit of `src\u002F` and `doc\u002F` corresponds to which state of the research artifacts (proposal version, log entries, survey rows). This is what makes the proposal → src → result → doc chain (C5) actually reproducible — at any past root commit, the two submodules check out to the exact versions that match.\n- Root has no required remote because the research artifacts are private-by-default. A user MAY add a remote (private GitHub repo) for cross-machine sync; absent that, root git just gives local history + the submodule pinning.\n\n**`cache\u002F`, `legacy\u002F`, and per-machine files are NEVER tracked by any of the three.** Root `.gitignore` MUST contain at minimum:\n\n```\ncache\u002F\nlegacy\u002F\n.DS_Store\n*.swp\n```\n\nRoot `.gitignore` does NOT list `src\u002F` or `doc\u002F` — those are submodules, tracked as pointers, not as ignored directories.\n\n**Init order during Workflow A:**\n\n1. Scaffold the directory tree and research-artifact files (steps 1–5 of Workflow A).\n2. User initializes `src\u002F` (GitHub clone) and `doc\u002F` (Overleaf clone) as instructed in step 6. These arrive as independent gits.\n3. Init root git: `git init`, write `.gitignore`, `git submodule add \u003Csrc-remote> src`, `git submodule add \u003Cdoc-remote> doc`, commit. **Defer adding a submodule whose remote does not yet exist** — initialize the directory normally and convert to a submodule later.\n4. If either submodule's remote is not ready at init time, the root git can still be created tracking only the research artifacts; add the submodule when the remote is ready and amend `.gitmodules` then.\n\n**Important interaction with C5 (modification order proposal → src → output → doc):**\n- When updating `src\u002F` or `doc\u002F`, work inside the submodule first (commit there, push to its remote).\n- Then at root, `git add src` (or `doc`) bumps the submodule pointer to the new commit. Commit at root.\n- This double-commit is the price of three-git isolation. Worth it because the root pointer is then a reproducible snapshot.\n\n**When to actually commit at root**: governed by **C9** (offer-to-commit). No fixed rhythm, no hook — at the end of an independent unit of work (survey sweep done, review landed, proposal major change, session handoff written, etc.), Codex asks the user whether to commit; the user decides. See C9 for the trigger list, the staging rules, and the message-prefix convention.\n\n### Per-file responsibilities\n\n| File | Owner | Mutability | Notes |\n|---|---|---|---|\n| `AGENTS.md` | research-workflow init | Rare edits | Holds project status (active\u002Farchived\u002Fabandoned), key constraints, target conference |\n| `proposal.md` | researcher + Codex | Iterative early, stable later | Governed by C3 modification protocol |\n| `survey.md` | Codex (after PDF read) | Append-mostly | Governed by C4. Single-paper intake via Workflow E. |\n| `survey\u002F\u003Cslug>.*` | research-survey worker sub-agent | Per-sweep | Sub-topic sweeps. See research-survey skill. Promotion to root `survey.md` is by Workflow E per row. |\n| `review\u002F\u003Cts>.*` | research-review (main Codex session + reviewer sub-agent) | Per-checkpoint | Key-checkpoint reviews. See research-review skill. `.state` carries the trigger cursor. |\n| `result.md` | Codex after each validated experiment | Append-mostly | Two sections: Confirmed Findings, Failed Attempts |\n| `talk.pptx` | Optional, post-research only | Rare | Used for talks\u002Freports AFTER research is done. Not used for paper figures. |\n| `cache\u002F` | Codex when downloading | Free | Never tracked by any git. Always in root `.gitignore`. |\n| `log\u002F` | Codex | Append-only | See Section 5. Tracked by root git. |\n| `doc\u002F` | Codex when results stable | Lagging | **Submodule.** Init by user via Overleaf clone. |\n| `src\u002F` | Codex implementing | Active | **Submodule.** Init via discussion of base framework. |\n| `.gitignore` + `.gitmodules` | research-workflow init | Rare | Root git config. See \"Version control\" above. |\n\n### What this skill does NOT manage\n\n- LaTeX template selection: the user initializes `doc\u002F` themselves on Overleaf, then `git clone`s. This skill only **reminds** the user to do this and points to the conference's formatting guidelines page.\n- Base code framework selection (verl \u002F FSDP \u002F vLLM \u002F etc.): must be **discussed** before src\u002F is initialized. This skill enforces the discussion, not the choice.\n\n---\n\n## Section 3 — Workflows\n\n### Workflow A: Starting a new project\n\nTriggered by user saying \"let's start a new topic on X\" or by `$research init \u003Cslug>` \u002F `$research-workflow init \u003Cslug>`.\n\n1. **Confirm intent**. If the user's message is ambiguous, ask: \"Is this a new top-level research project (gets its own NN-\u003Cslug>\u002F), or are we extending an existing project, or is this just exploration that should go to 00-QuickReview\u002F?\"\n2. **Discuss the seed**. Before writing any file, have a short discussion: what is the rough idea, what's the target conference, what's the rough timeline? This populates the initial AGENTS.md and proposal.md skeleton.\n3. **Compute next number**. `ls ~\u002FDocuments\u002Fproject\u002F | grep -E '^[0-9]{2}-' | sort | tail -1` → next sequence number.\n4. **Scaffold**. Create the directory tree from Section 2. Copy templates from `~\u002F.codex\u002Fskills\u002Fresearch-workflow\u002Ftemplates\u002F` into the new project, renaming as follows:\n\n   | Template | Destination | Notes |\n   |---|---|---|\n   | `AGENTS.md.template` | `\u003Cproject>\u002FAGENTS.md` | Fill `{{PROJECT_NAME}}`, `{{NN-slug}}`, `{{ONE_LINE_TOPIC}}`, `{{YYYY-MM-DD}}` from the discussion in step 2 |\n   | `proposal.md.template` | `\u003Cproject>\u002Fproposal.md` | Leave most placeholders for the researcher to fill during proposal iteration; only fill the title and date |\n   | `survey.md.template` | `\u003Cproject>\u002Fsurvey.md` | Fill title; keep the example row commented or delete it |\n   | `result.md.template` | `\u003Cproject>\u002Fresult.md` | Fill title; keep both section headers, remove example entries |\n   | `log-index.md.template` | `\u003Cproject>\u002Flog\u002Findex.md` | Fill title |\n   | `src-gitignore` | `\u003Cproject>\u002Fsrc\u002F.gitignore` | Copy verbatim |\n\n   Also `mkdir -p \u003Cproject>\u002Flog\u002Fentries \u003Cproject>\u002Fcache\u002Fpapers \u003Cproject>\u002Fcache\u002Frepos \u003Cproject>\u002Fcache\u002Fdatasets \u003Cproject>\u002Fsurvey \u003Cproject>\u002Freview`. Do NOT create `doc\u002F` or `src\u002F` contents — those are user-initialized (see step 6). The `log-entry.md.template` is for runtime use by Workflow's log-writing step, not for init.\n5. **Initialize log**. Create `log\u002Findex.md` with header, no entries yet.\n6. **Remind user about doc\u002F and src\u002F init** (three-git layout — see Section 2 \"Version control\"). Tell the user:\n   - \"Initialize `doc\u002F` by creating an Overleaf project from the target conference's template, then `git clone` it into `\u003Cproject>\u002Fdoc\u002F`. I'll wait.\"\n   - \"Before I scaffold `src\u002F`, let's discuss what base framework to build on (verl \u002F rLLM \u002F from scratch \u002F etc.). Once decided, `git clone` it from GitHub into `\u003Cproject>\u002Fsrc\u002F`.\"\n7. **Init root git + wire submodules**. After the user has cloned `src\u002F` and `doc\u002F`:\n   - `git init` at project root.\n   - Write root `.gitignore` (must include `cache\u002F`, `legacy\u002F` if present, `.DS_Store`, `*.swp`, plus per-project items). Do NOT list `src\u002F` or `doc\u002F` — they will be submodules.\n   - `git submodule add \u003Csrc-remote-url> src` and `git submodule add \u003Cdoc-remote-url> doc`. If a remote is not yet ready, defer that submodule and add when ready.\n   - Initial commit covers: `AGENTS.md`, `proposal.md`, `survey.md`, `result.md`, `log\u002F`, `survey\u002F`, `.gitignore`, `.gitmodules`, and the submodule pointers.\n   - Root remote is optional and local-only by default. Add a remote only if the user explicitly asks for cross-machine sync.\n8. **Log the init event** as `decision_project-init`.\n\n### Workflow B: Iterating on the proposal\n\nTriggered by any discussion that might affect proposal.md.\n\n1. **Determine change class** (per C3): minor or major?\n2. If **minor**: edit `proposal.md`, log as `proposal-update`, surface a one-line summary to user.\n3. If **major**:\n   - Stop. Do not edit.\n   - State the conflict: \"What you're proposing changes [aspect X] of the proposal. Previously we said [Y]. This invalidates [Z list of artifacts].\"\n   - Wait for user confirmation.\n   - On confirmation: edit, log as `proposal-update` with `related:` field pointing to all invalidated artifacts. Trigger Workflow F (cascade check).\n4. **Schematic figures** (only if the method has stabilized enough to be drawn): create `doc\u002Ffigures\u002Ffig-\u003Cslug>.tex` using the `standalone` document class with TikZ; compile it locally (`pdflatex` in `doc\u002Ffigures\u002F`) to produce `fig-\u003Cslug>.pdf`. Reference the PDF from `doc\u002Fsections\u002F*.tex` via `\\includegraphics`. Don't draw schematics for moving targets — wait until the method is settled.\n\n### Workflow C: Running an experiment\n\n1. Confirm experiment is connected to a proposal claim. If not, ask why we're running it.\n2. Implement \u002F modify in `src\u002F`.\n3. Run, capture raw outputs in `src\u002Fdata\u002F`.\n4. **Decide outcome**: did it confirm or contradict the proposal?\n   - **Confirms**: append to `result.md` `## Confirmed Findings` with quantitative summary.\n   - **Contradicts**: append to `result.md` `## Failed Attempts` with hypothesis, actual result, suspected reason, whether still open question. Then **trigger Workflow B (major change check)** — does this contradiction force a proposal revision?\n5. **Result figures** (only if the result is publication-relevant): write a plotting script under `src\u002Fscripts\u002Fplot_*.py` (matplotlib \u002F seaborn \u002F TikZ \u002F PGFPlots). Output PDF to `src\u002Fdata\u002Ffigures\u002F`, then **copy** (not symlink — `doc\u002F` is a separate git repo) the PDF into `doc\u002Ffigures\u002F`.\n6. Log as `experiment` with status=done, `related:` pointing to proposal sections it tested.\n\n### Workflow D: Updating doc\u002F\n\n1. Verify the claim being added to doc\u002F has a corresponding entry in `result.md` `## Confirmed Findings`. If not, refuse — use `\\todo{}` placeholder instead.\n2. Modify `doc\u002Fsections\u002F*.tex`.\n3. **Citations**: never write BibTeX from memory. Defer to `ml-paper-writing` skill rules. If a citation can't be verified, mark as `\\cite{PLACEHOLDER_...}`.\n4. Log as `doc-update`.\n\n### Workflow E: Adding to survey.md (single-paper intake)\n\n**Routing note**: if the user mentions a *sub-area* rather than a specific paper (\"调研一下 X 方向 \u002F sweep the literature on X\"), route to **Workflow E'** instead. Workflow E is for single-paper intake.\n\n1. The user mentions a paper, OR Codex suggests a paper to look at.\n2. Log as `survey-add` with status=todo.\n3. **Download the PDF** (arxiv URL, conference page, etc.) into `cache\u002Fpapers\u002F\u003Cpaper-id>.pdf`. If you can't download, the entry stays in `log\u002F` as todo and never enters `survey.md`.\n4. **Read the PDF** (at minimum: abstract, intro, method, conclusion).\n5. Append a row to `survey.md` with: title, link, venue, relation to our proposal, key difference, `verified_by: cache\u002Fpapers\u002F\u003Cpaper-id>.pdf`.\n6. Mark log entry as status=done.\n\n### Workflow E': Surveying a sub-topic (sweep)\n\nTriggered when the request is to investigate a sub-area, not to record a known paper. Delegates to the `research-survey` sub-skill.\n\n1. **Disambiguate** if needed: \"Is this a sub-area sweep, or a single paper you've already identified?\" If single, switch to Workflow E.\n2. **Draft a brief**. Main agent creates `\u003Cproject>\u002Fsurvey\u002F\u003Cslug>.brief.md` from `~\u002F.codex\u002Fskills\u002Fresearch-survey\u002Ftemplates\u002Fsubtopic-brief.md.template`. Fill every required field; pull `time_window_start` from this project's creation date (NOT today), pull `accepted_venues` from this project's `AGENTS.md`. Log as `survey-sweep` with status=todo.\n3. **Dispatch workers**. Spawn one Codex sub-agent per sub-topic. Prompt each worker to read `~\u002F.codex\u002Fskills\u002Fresearch-survey\u002FSKILL.md` and execute against the brief's absolute path. Multiple sub-topics can run in parallel. Workers do not share state; the dispatcher dedups after they return.\n4. **Receive the worker's final message**. Read `survey\u002F\u003Cslug>.md`, the candidates audit trail, and the sweep log entry. Surface to the user:\n   - Count summary (papers in survey, code not-found, venue needs-review)\n   - Any flagged items that need a dispatcher decision (venue inclusion, dropped-for-unavailable retries)\n5. **Promote rows to root `survey.md`** (per user direction or your own judgment, then user confirm). Each promoted row is a Workflow E call; the `verified_by` field is already set, so the PDF check is satisfied — no re-verification needed. The sub-topic `survey\u002F\u003Cslug>.md` remains as the source of truth for that sweep's full per-paper writeup.\n6. Mark the `survey-sweep` log entry as status=done.\n\n**Why this is separate from Workflow E**: a sweep produces 8–15 rows in one operation; doing it through 8–15 sequential Workflow E calls loses the sub-topic context (axes_of_interest, search trace, coverage notes) that makes the sweep valuable later. The sub-topic file preserves that context; the root `survey.md` row is the promoted summary.\n\n### Workflow G: Executing queued code TODOs via a cowork batch\n\nTriggered when ≥ 1 log entry of type `src-update` (or similar code-change type) has `status: todo` AND the work is concrete code writing in `src\u002F` (not exploratory debugging, not a design discussion). Delegates to the `research-cowork` sub-skill.\n\n1. **Identify the batch**. Filter `log\u002Fentries\u002F` for `type=src-update` AND `status=todo`. Confirm the work is code-writing (not \"decide between approaches\"). If only one TODO and it's a single small change, prefer a direct commit inside Workflow C — cowork pays off when ≥ 2 atomic, parallelizable issues exist.\n2. **Preflight environment**. Per `research-cowork` SKILL.md: verify the target repo, `git`, `gh` if PRs are expected, and test commands. Parallel Codex sub-agents are the worker model; do not add a nested `codex exec` layer.\n3. **Confirm scope with the user** before opening any GitHub issue. Present the candidate batch (which TODOs become which issues, source repo, batch id) and wait for approval.\n4. **Hand off to research-cowork**. Execute the cowork workflow: decompose into atomic issues → assign disjoint file scopes → spawn parallel Codex sub-agents → review worker reports\u002FPRs → resolve conflicts at merge → update logs.\n5. **Source TODO close-out**. For each `src-update` log entry that was closed by a merged PR, set `status: done` and add a body line referencing the cowork batch id and PR number.\n6. **Log the batch**. Write a `cowork-batch` log entry (type defined in Section 5). Summary: N issues, M PRs merged, K conflicts resolved, and source repo. Failures use `cowork-batch-failure`.\n7. **Trigger Workflow F (cascade check)** after the batch lands — a non-trivial code change in `src\u002F` may invalidate proposal claims, result findings, or doc sections.\n\n**Why this is separate from Workflow C (running an experiment)**: Workflow C is one researcher + one running experiment; the code edit there is incidental and stays in the local working tree. Workflow G is multiple parallel atomic edits, each landing through its own PR — needed when the queue has several independent code TODOs and the project benefits from independent reviews.\n\n### Workflow H: Key-checkpoint review (two parallel reviewer sub-agents + diff pass)\n\nTriggered when `~\u002F.codex\u002Fskills\u002Fresearch-review\u002Fbin\u002Freview-trigger \u003Cproject_root>` reports `TRIGGER` (≥ 10 new log entries since last review), OR when the user explicitly asks for a review (\"review 一下\"). Delegates to the `research-review` sub-skill.\n\n1. **Trigger detection**. Either: (a) after writing a log entry, run `review-trigger` and observe `TRIGGER`, then **proactively suggest** a review to the user (do not run autonomously); (b) the user manually requests one. Wait for user confirmation before starting.\n2. **Draft the brief**. Main agent fills `\u003Cproject>\u002Freview\u002F\u003Cts>.brief.md` from `~\u002F.codex\u002Fskills\u002Fresearch-review\u002Ftemplates\u002Freview-brief.md.template`. Required fields include the log window (from `since_log_entry` to latest), snapshot paths (proposal.md, result.md, survey.md, survey\u002F*.md), novelty parameters (fixed: 3 months, 4 sources), and output paths.\n3. **Dispatch TWO reviewer sub-agents in parallel** (per research-review — architectural symmetry). In **one message**, main Codex session invokes two Codex reviewer sub-agents:\n   - Reviewer A (`reviewer-prompt.md.template`, `reviewer_id=codex_a`) -> produces `\u003Cts>.a.md`\n   - Reviewer B (`reviewer-prompt.md.template`, `reviewer_id=codex_b`) -> produces `\u003Cts>.b.md`\n   Neither prompt references the other's output path. Main Codex session does NOT do any review work itself in the main session.\n4. **Return to useful work**. Main Codex session does not poll unless blocked on the review outcome.\n5. **Generate the diff**. After both reports exist, use a third sub-agent or deterministic comparison pass to produce `\u003Cts>.diff.md`. If either reviewer failed, skip this step.\n6. **Present result**. Main Codex session reads the diff headline and surfaces it to the user. Updates `\u003Cproject>\u002Freview\u002F.state` (`last_reviewed_log_count`, `last_reviewed_log_entry`, `last_reviewed_ts`).\n7. **Log the review**. Write `\u003Cts>_review_\u003Cslug>.md` log entry (type=`review`, or `review-failure` if any sub-agent returned `failed`). Cites the four report paths.\n8. **Trigger Workflow F (cascade check)** ONLY if the review surfaces consensus RED-FLAGs that the researcher decides to act on. Review by itself does not mutate research artifacts (per research-review C-R6).\n\n**Why this is separate from Workflow F (cascade check)**: cascade check is a one-shot integrity scan after a specific known change; key-checkpoint review is a periodic parallel-reviewer audit triggered by accumulated activity. Review surfaces *what should be questioned*; cascade check propagates *what is already decided*.\n\n### Workflow F: Cascade check (after any major change)\n\nAfter a major proposal change, src refactor, or contradicting experiment:\n\n1. Scan `proposal.md` — any sections invalidated?\n2. Scan `log\u002F` for status=todo entries — any obsolete or now-blocked?\n3. Scan `result.md` — any Confirmed Findings now in question?\n4. Scan `doc\u002Fsections\u002F` — any claims now unsupported?\n5. For each: surface to user with options (update \u002F drop \u002F supersede). Do not silently propagate.\n\n---\n\n## Section 4 — Figure rules\n\nFigure production is **part of the workflows** (schematics in Workflow B step 4, result plots in Workflow C step 5), not a separate phase. All figures live under `doc\u002Ffigures\u002F` — even result plots produced from `src\u002F`. Only the rules live here:\n\n- **No raster images.** All figures must be vector PDF. PNG \u002F JPG \u002F screenshot are rejected from `doc\u002Ffigures\u002F`.\n- **Schematics** (architecture diagrams, conceptual workflows, illustrations) → write `doc\u002Ffigures\u002Ffig-\u003Cslug>.tex` using `\\documentclass[tikz,border=2pt]{standalone}` + TikZ → compile with `pdflatex` to `fig-\u003Cslug>.pdf` → `\\includegraphics` from `doc\u002Fsections\u002F*.tex`. One `.tex` per figure. **Do not use `beamer` or `pptx` for paper figures.**\n- **Result plots** (loss curves, ablation bars, scatter, heatmaps) → matplotlib \u002F seaborn \u002F PGFPlots in `src\u002Fscripts\u002Fplot_*.py` → PDF emitted to `src\u002Fdata\u002Ffigures\u002F` → **copy** (not symlink — `doc\u002F` is a separate git repo) the PDF to `doc\u002Ffigures\u002Ffig-\u003Cslug>.pdf`.\n- **Timing**: draw schematics only when the method has stabilized; draw result plots only when the result is publication-relevant. Premature figures rot fast.\n- **`talk.pptx` is unrelated to paper figures.** It exists only for post-research talks \u002F reports. Never source a paper figure from it.\n\n---\n\n## Reports — HTML primary, MD shadow\n\nUse `vibe-report` for report-specific authoring\u002Fdeployment guidance and templates. This section defines the durable artifact contract that `vibe-report` inherits.\n\nWhen the user or a full-auto workflow asks for a written report, default to a visual HTML report plus a Markdown shadow:\n\n- Primary artifact: `report\u002FYYYY-MM-DD_\u003Cslug>.html`. It should be self-contained: inline CSS, inline JS only when needed, and base64 or local generated assets. The user should be able to open it locally without a dev server or internet access.\n- Shadow artifact: `report\u002FYYYY-MM-DD_\u003Cslug>.md`. It carries the same claims in plain prose and is the source for later Feishu Docx export.\n- Generated assets live under `report\u002Fassets\u002F\u003Cslug>\u002F`. Reusable optional libraries live under `report\u002Fassets\u002Flib\u002F`.\n- Use vendored Chart.js, KaTeX, or highlight.js only when they are already available. Do not make report generation depend on network downloads. Plain CSS, inline SVG, and static tables are acceptable defaults.\n- Do not use React, Vue, or a build step for reports unless the user explicitly asks for an app rather than a report.\n- Author with the existing single-writer discipline. A reviewer can add inline `\u003Caside class=\"reviewer-note\">...\u003C\u002Faside>` blocks or a separate review log; the primary author resolves them before final delivery.\n- Match visualization complexity to signal. Use charts, timelines, matrices, and callouts when they clarify the result; do not decorate sparse evidence.\n- The report must present findings and the data behind them together: key findings, visual evidence, method\u002Fscope, caveats, and links to source artifacts should all be visible in the HTML.\n- In Feishu bridge mode, prefer Bridge `\u002Freport`: Claude defaults to the HTML\u002Ffront-end artifact via `vibe-report`; Codex defaults to deployment with `vrc report serve`.\n- `vrc report serve \u003Cworkspace> \u003Creport.html>` serves the report from the topic workspace with backend Basic Auth, binds `0.0.0.0`, chooses an available port, generates a controller-reachable `http:\u002F\u002F\u003Chost>:\u003Cport>\u002F...` URL using `report_public_host` or host-IP detection, and sends credentials to the controller by Feishu DM. Do not post report passwords in the group.\n- Commit the HTML, MD, and required assets as normal workspace artifacts after the report unit is complete and the user approves the commit.\n\n---\n\n## Section 5 — The log\u002F system\n\nThe log replaces `TODO.md`, `decisions.md`, and any other timeline document. Everything that happens with a timestamp goes here.\n\n### File layout\n\n```\nlog\u002F\n  index.md                                # Auto-maintained, reverse-chronological table\n  entries\u002F\n    YYYY-MM-DD_HHMM_\u003Ctype>_\u003Cslug>.md      # Individual events\n```\n\n### Event file schema\n\n```markdown\n---\ntimestamp: 2026-04-29T11:00:00+08:00\ntype: \u003Cone of: debate | decision | experiment | proposal-update | src-update | doc-update | survey-add | survey-sweep | survey-sweep-failure | cowork-batch | cowork-batch-failure | review | review-failure>\nslug: short-kebab-case\nstatus: todo | done           # OPTIONAL. Only used for actionable events.\nsessions: [\u003Ccc-session-id>, ...]   # OPTIONAL. Cross-references to Codex sessions.\nrelated: [\u003Cother-entry-filename>]   # OPTIONAL. Links to related events.\n---\n\n# One-line title\n\n**Summary**: One sentence. This is what shows up in `index.md`.\n\n**Details**: Free-form markdown body. As long as needed.\n```\n\n### When entries are created\n\n**Codex proactively offers** to create a log entry after:\n- A round of proposal\u002Farchitecture discussion concludes\n- An experiment finishes (success or failure)\n- The user states a clear decision (\"let's go with X\", \"drop Y\")\n- A non-trivial change to proposal.md \u002F src\u002F \u002F doc\u002F lands\n- A debate ends without resolution (log as `debate`, status=open if you add status)\n\n**Manual creation** via `$research log \u003Ctype> \u003Cslug> [--status todo]` or `$research-workflow log \u003Ctype> \u003Cslug> [--status todo]`.\n\nIn both cases, the actual file may be written directly by the main Codex session or by a lightweight Codex sub-agent when isolation is useful.\n\n### index.md\n\nAuto-maintained. Reverse-chronological. Full list, no truncation. Format:\n\n```markdown\n# Project NN-\u003Cslug> Timeline\n\n| Date | Type | Slug | Summary | Status |\n|---|---|---|---|---|\n| 2026-04-29 11:00 | proposal-update | drop-multi-task | Removed multi-task variant after 4 ablations showed no gain | done |\n| 2026-04-29 09:30 | debate | aux-loss-question | Discussed adding aux loss; no decision | — |\n| ... |\n```\n\nRegenerated by `~\u002F.codex\u002Fskills\u002Fresearch-workflow\u002Fbin\u002Flog-filter --regenerate-index` after any new entry.\n\n### Filter program\n\n`bin\u002Flog-filter` (bash, uses ripgrep + awk). Output mimics `git log --oneline`.\n\n```bash\nlog-filter                              # All events, reverse-chronological\nlog-filter --type experiment            # Only experiments\nlog-filter --status todo                # Only open todos\nlog-filter --slug multi-task            # Slug substring match\nlog-filter --recent 10                  # Last 10\nlog-filter --type src-update --recent 5 # Combine filters\nlog-filter --regenerate-index           # Rewrite index.md from entries\u002F\n```\n\nThe script is idempotent and stateless — it only reads `entries\u002F` and prints \u002F overwrites `index.md`.\n\n---\n\n## Section 6 — Inter-skill routing\n\nresearch-workflow does not duplicate domain skills. It **routes** to them at the right moment.\n\nThe full list of relevant skills installed locally is in [`available-skills.md`](.\u002Favailable-skills.md). Consult that file when picking a skill. High-frequency routings:\n\n| Lifecycle stage | Default skill |\n|---|---|\n| Brainstorming early ideas \u002F pivoting | `brainstorming-research-ideas` |\n| Stuck, need creative leap | `creative-thinking-for-research` |\n| Surveying a sub-topic (sub-area sweep, not single-paper intake) | `research-survey` |\n| Executing queued code TODOs (≥ 2 atomic issues in parallel via Codex sub-agents) | `research-cowork` |\n| Key-checkpoint review of the research (parallel codex + Codex, four dimensions) | `research-review` |\n| Drafting \u002F refining the paper | `ml-paper-writing` (a.k.a. `20-ml-paper-writing`) |\n| Drawing schematic figures | Direct LaTeX\u002FTikZ in `doc\u002Ffigures\u002F` (standalone, no skill required) |\n| Post-research talk \u002F report slides | `pptx` (document-skills) — only for `talk.pptx`, never for paper figures |\n| RL post-training | `verl`, `openrlhf`, `trl-fine-tuning`, `grpo-rl-training` |\n| Distributed training scaffolding | `accelerate`, `pytorch-fsdp2`, `megatron-core` |\n| Inference for eval \u002F agent harness | `vllm`, `sglang` |\n| Evaluation | `lm-evaluation-harness`, `bigcode-evaluation-harness` |\n| Experiment tracking | `weights-and-biases` |\n\nWhen you spot that a different skill in `~\u002F.codex\u002Fskills\u002F` would help and isn't in `available-skills.md`, **suggest adding it** rather than silently using it. The user maintains the whitelist.\n\n---\n\n## Section 7 — Common Anti-patterns\n\n| Anti-pattern | Symptom | Correction |\n|---|---|---|\n| **Eager proposal rewrite** | Modifying proposal.md every time an experiment surprises us | Apply C3 — minor vs major distinction. Most surprises are minor adjustments to claims, not core revisions. |\n| **Survey by hearsay** | Adding entries to survey.md based on titles\u002Fabstracts only | Apply C4 hard. PDF must exist locally; verified_by must point to it. |\n| **Doc gets ahead of results** | Writing claims in doc\u002F before result.md confirms them | Apply C5. Use \\todo{} placeholders. doc is a lagging mirror. |\n| **Silent cascades** | Changing src\u002F without checking proposal\u002Fdoc\u002Flog impact | Apply C6. After any non-trivial change, run cascade check (Workflow F). |\n| **Decision without log** | \"We decided X\" but no log entry | Offer to log immediately. Log entries are cheap, retrieval is priceless. |\n| **Raster figures sneaking in** | PNG screenshots in doc\u002Ffigures\u002F | Reject. Apply Section 4. Either redo as a standalone TikZ schematic or as a matplotlib\u002FPGFPlots PDF. |\n| **Citations from memory** | BibTeX entries Codex wrote without API verification | Reject per ml-paper-writing rules. Use \\cite{PLACEHOLDER_...} until verified. |\n| **Constitutional drift** | Mid-session, Codex forgets the constitution | Re-read project-level AGENTS.md. The user can also remind by saying \"constitution check\". |\n| **Long-session quality decay** | Conversation past ~50 turns, hedged\u002Frepetitive answers, or about to start a new sub-task — but Codex keeps going | Apply C8. Stop, write a handoff log entry, suggest `\u002Fclear`. Multi-session work is normal. |\n\n---\n\n## Section 8 — Skill Entry Aliases\n\nCodex CLI does not load user-defined slash commands from `~\u002F.codex\u002Fcommands`.\nUse `\u002Fskills`, `$skill-name` mentions, or natural language. Common argument\nshapes:\n\n- `$research init \u003Cslug>` — Workflow A. Creates the project scaffold.\n- `$research log \u003Ctype> \u003Cslug> [--status todo|done]` — Manually create a log entry.\n- `$research filter [args]` — Wraps `bin\u002Flog-filter`. Same args.\n- `$research check` — Run cascade check (Workflow F) on the current project.\n- `$research status` — Show current project's AGENTS.md status, recent log activity, open todos.\n\n---\n\n## Notes for the agent\n\n- This skill is meta. Do not put domain advice here. If you find yourself wanting to write \"how to brainstorm\" or \"how to pick baselines\", that belongs in another skill.\n- The constitution is maintained primarily by the project-level `AGENTS.md` that init writes. SKILL.md (this file) is the source of truth, but the user-facing daily enforcer is the per-project AGENTS.md.\n- When in doubt, follow C7: ask the user. This is a meta skill about disciplined collaboration, not autonomous execution.\n","# research-workflow — A Constitution for Research Collaboration\n\nThis skill is a **meta-skill**. It does not give domain advice (how to brainstorm, how to write a paper, how to design experiments). It defines:\n\n- **The constitution**: principles Codex must obey when collaborating on research\n- **The directory layout**: how every project under `~\u002FDocuments\u002Fproject\u002F` is organized\n- **The log discipline**: how decisions, debates, experiments, and changes are recorded over time\n- **The routing map**: which other research skills to invoke at which lifecycle stage\n\nWhen you are about to do anything research-related, this skill comes first. Domain skills (ideation, paper-writing, RL training) are invoked from within this framework.\n\n---\n\n## ⚠️ Sub-skills you MUST know about\n\nresearch-workflow has **four first-class sub-skills**. They are NOT optional tools — they are the framework's own dispatch points for common situations. If you find yourself manually doing what one of these handles, **stop and use the sub-skill instead** (or explain to the user why you're deviating).\n\n| Sub-skill | Triggers on | Workflow | What goes wrong without it |\n|---|---|---|---|\n| **`research-survey`** | \"调研一下 X 这个子方向\" \u002F sub-area sweep request, NOT a single-paper intake | Workflow E' | You'd run 10× sequential Workflow E and lose sub-topic context (axes, search trace, coverage). |\n| **`research-cowork`** | ≥ 1 `src-update` log entry with `status: todo` AND it's concrete code-writing in `src\u002F` | Workflow G | You'd write code serially in the main session, blow up context, and lose the PR audit trail. |\n| **`research-review`** | `bin\u002Freview-trigger` reports TRIGGER (≥ 10 new log entries since last review), OR user asks \"review 一下\" | Workflow H | You'd skip checkpoints; soundness\u002Fnovelty\u002Fconsistency\u002Fcoherence drift goes unnoticed until it's a crisis. (Architecture: two mutually blind Codex reviewer sub-agents plus a diff pass. Main Codex session only dispatches and presents.) |\n| **`vibe-report`** | User asks for a visual web report, `\u002Freport`, deployed report page, or report template | Reports | You'd keep re-deciding Claude\u002FCodex report roles and drift away from the shared HTML-primary\u002FMD-shadow artifact contract. |\n\n**How to spot them**: in the global skill list, most first-class workflow entries describe themselves as `[research-workflow sub-skill]`; `vibe-report` is intentionally independent but part of the same VRC report contract. They are scoped to research-workflow\u002FVRC projects — do not invoke them outside that context unless the user explicitly asks for a standalone report artifact.\n\nWhen in doubt about whether to dispatch to a sub-skill or handle inline: dispatch. The sub-skills enforce the input contracts and constitution rules that ad-hoc handling tends to skip.\n\n---\n\n## When to Use\n\n- The user starts a new research project (\"let's start a new topic on X\")\n- The current working directory is `~\u002FDocuments\u002Fproject\u002F[1-9][0-9]*-*\u002F`\n- The user asks \"how should I organize this\", \"where does this go\", or any question about the research workflow\n- Before invoking a domain research skill (brainstorming, paper-writing, etc.) — research-workflow provides the surrounding context\n\n## When NOT to Use\n\n- Pure coding tasks unrelated to a research project\n- Working inside `~\u002FDocuments\u002Fproject\u002F00-QuickReview\u002F` (this is a non-project scratch area; constitution does not apply)\n- One-shot questions that don't touch any research artifact\n\n---\n\n## Section 1 — The Constitution (non-negotiable)\n\nThese rules govern every interaction in a research-workflow project. They are listed here, and **enforced** by the project-level `AGENTS.md` that this skill writes during init.\n\n### C1. First-principles, always\n\nReject empiricism. Start from raw requirements. If the user's request seems suboptimal, **propose a shorter or cheaper alternative before executing**. If the goal is vague, stop and discuss.\n\n### C2. Cool-headed reviewer, not eager assistant\n\nCodex's role is a **calm peer reviewer** of the research progress. Never default to \"always push for changes\" nor \"always preserve the status quo\". On every proposed modification, weigh: is this change earning its complexity?\n\n### C3. The proposal is the kernel\n\n`proposal.md` is the project's nucleus. Every action — coding, experiments, paper-writing — must serve it. Two modification protocols apply:\n\n- **Minor change** (baseline swap, measurement tweak, presentation): edit `proposal.md` directly, log it as `proposal-update`\n- **Major change** (core hypothesis overturned, target metric replaced, claim scope shifted): **STOP. Surface the conflict to the user. Do not modify `proposal.md` until the user agrees.**\n\nIf unsure which class a change belongs to, treat it as major.\n\n### C4. Survey is sacred — never fabricate\n\nEntries in `survey.md` must be **factually correct**. Hard rule: **no entry may be added to `survey.md` until the corresponding paper PDF has been downloaded to `cache\u002Fpapers\u002F` AND the entry's `verified_by` field points to that file.**\n\nIf you've only seen an abstract, a citation, or a search result, the paper goes into a separate scratch list (`log\u002Fentries\u002F*_survey-add_*.md` with status=todo). It does NOT enter `survey.md`.\n\nThis is structural enforcement. Do not work around it.\n\n### C5. Modification order: proposal → src → output → doc\n\nWhen iterating, always propagate in this direction:\n\n1. Update `proposal.md` if the change is conceptual\n2. Update `src\u002F` to implement\n3. Run experiments, capture outputs in `src\u002Fdata\u002F`, summarize in `result.md`\n4. Only then update `doc\u002F` to reflect new findings\n\n`doc\u002F` is the **lagging mirror** of validated state. Never write claims into `doc\u002F` that aren't backed by `result.md` confirmed findings. Use `\\todo{}` placeholders if a section needs scaffolding before results land.\n\n### C6. Holistic view — touch one thing, check the rest\n\nA change to `src\u002F` may invalidate a `proposal.md` design choice, which may obsolete a `TODO` log entry, which may require `doc\u002F` rewriting. After any non-trivial change, scan adjacent artifacts and surface implications.\n\n### C7. Discuss before acting on uncertainty\n\nWhen you're not sure whether something is correct, or have no objective evidence — **ask, don't guess**. This is more important than appearing decisive.\n\n### C8. Reset session cache deliberately when context bloats or when crossing a task boundary\n\nLong contexts degrade Codex's reasoning. **Multiple sessions on one project is the norm, not a failure mode** — the `sessions:` field in log entries is plural for this reason. A 30-minute session at peak quality beats a 3-hour session at 60% quality.\n\nFor Feishu-mediated topic work, use the cache model shared by Claude and Codex:\n\n| Level | Where it lives | Purpose |\n|---|---|---|\n| **L1** | live agent CLI session (`session_id`) | immediate reasoning context |\n| **L2** | latest handoff log under `log\u002Fentries\u002F` | one-file reload after rotation |\n| **L3** | `log\u002Fsession-index.md`, `log\u002Fentries\u002F`, workspace docs | durable project memory |\n\nAt roughly 50% measured context usage, the bridge should rotate: write L1 to an L2 handoff, clear the session id, then start the next dispatch fresh with an explicit pointer to that handoff. Workspace logs are authoritative; private agent memory indexes are only discovery aids.\n\n**Trigger signals (any one is enough)**:\n\n- The conversation has crossed ~50 turns or has been auto-compacted at least once\n- Recent answers feel hedged, repetitive, or have lost track of earlier decisions\n- The user is about to start a clearly different sub-task (proposal → src, src → doc, debugging → ideation). Task boundaries are natural session boundaries.\n\n**When triggered in a normal Codex TUI session, do NOT just suggest `\u002Fclear`. Run the handoff protocol**:\n\n1. Write a fresh log entry of type `decision`, slug `session-handoff-\u003Cshort-context>`, with `sessions: [\u003Ccurrent-session-id-if-known-else-empty>]`. The entry body MUST be **self-contained** — a fresh Codex reading only this entry (not the old session) should be able to continue without loss. Required fields in the body:\n\n   - **Where we are**: 1-3 sentences on current project stage and what just finished\n   - **Current understanding**: increments not yet captured in `proposal.md` \u002F `result.md` \u002F other log entries. This is the most important part — it's the bridge between sessions.\n   - **Next concrete step**: one sentence on what the new session should do first\n   - **Required reading (ordered)**: file paths and log entries the new session must read before acting\n   - **Open questions awaiting user**: if any, the new session's first move is to ask\n\n2. Tell the user: *\"I suggest `\u002Fclear` and starting a new session. The handoff is at `log\u002Fentries\u002F\u003Cfilename>`. Start the new session by asking me to read it.\"*\n\n3. The new session's first action is to read `AGENTS.md` and the handoff entry. It then appends its own session-id to the handoff entry's `sessions:` field so the audit chain is preserved.\n\n**Why this design**: the handoff body — not the session jsonl archive — is what makes continuity work. `\u002Fclear` removes the session from active memory; Codex does keep a jsonl archive on disk, but treat it as audit material, not as the substrate of cross-session continuity. The session-id pointer is plural so you can chain handoffs across many sessions on the same logical work thread.\n\n**Feishu bridge sessions**: the bridge owns `session_id`, not the agent. Use controller-only `@bridge clear-session \u003Cagent|all>` for a clean manual reset: the bridge should make the old session write a handoff, clear the sid, and make the next dispatch fresh with an L2 pointer. Use `@bridge clear-session \u003Cagent|all> --no-handoff` only for deliberate hard resets such as smoke-test or version-cutover contamination; this clears L1 without creating an L2 handoff, but should still leave an audit row in `log\u002Fsession-index.md`.\n\n**Special case: code-task handoff via GitHub issue**\n\nWhen all of the following conditions hold, open a GitHub issue as the handoff artifact (in addition to a thin local log entry):\n\n1. The work being handed off is a **concrete code task** in `src\u002F` (not a discussion, not exploratory debugging, not ideation)\n2. `src\u002F` has a GitHub remote (`git -C src remote -v` shows a github.com URL)\n3. `gh auth status` succeeds (gh CLI is authenticated)\n4. The task is scoped well enough to write a one-line PR title\n5. The working tree is either clean OR the WIP can be precisely described so the next session can resume without losing changes\n\nIf any condition fails, fall back to the default markdown handoff above. Tell the user which condition failed.\n\nWhen the conditions hold:\n\n1. Draft the issue body using the **same 5 fields** as the markdown handoff (Where we are \u002F Current understanding \u002F Next concrete step \u002F Required reading \u002F Open questions). Add a trailing line: *\"This issue is a research-workflow session handoff. Resolve by opening a PR.\"*\n2. Open the issue: `gh issue create --title \"\u003Cone-line task>\" --body \"...\" --label research-workflow:handoff` — drop the `--label` flag if the label doesn't exist in the repo; **do not auto-create labels**.\n3. **Still write a local log entry** of type `decision`, slug `session-handoff-\u003Cshort>`. Body is minimal: one-line summary plus a `gh_issue: \u003Curl>` field. This keeps `log-filter` aware of the handoff alongside non-code handoffs.\n4. Tell the user: *\"Issue opened at `\u003Curl>`. Suggest `\u002Fclear`. The new session should read the issue and open a branch to resolve it.\"*\n\nThe new session's first action: read the issue, read `AGENTS.md` and any files the issue references, then `git checkout -b` and start work. When the PR lands and the issue closes, update the local log entry's `status` to `done`.\n\nThe GitHub issue is the **source of truth** for code-task handoffs; the local log entry is a pointer so the timeline filter stays complete.\n\n**Connection to Workflow G**: a single handoff issue is resumed by the next session as a normal `gh issue` → branch → PR. When **multiple** open code-task issues accumulate (e.g., several past handoffs, or a queue of `src-update` TODOs that all need execution), the natural next step is Workflow G — batch them through `research-cowork` rather than resolving them one-by-one in a single session.\n\n### C9. Offer to commit at the end of an independent unit of work\n\nThe root git is a **local-only audit log** of the research timeline (see Section 2 \"Version control\"). It only accumulates value if commits actually land. There is **no fixed rhythm and no hook**: you decide, per moment, whether a meaningful unit of root-tracked work has just finished, and if so, you ask the user whether to commit. The user always decides; you never commit silently.\n\n**When to ask** (any one is a reasonable trigger — use judgment, not a checklist):\n\n- A `research-survey` sub-topic sweep has fully landed (brief + candidates + survey markdown all written)\n- A `research-review` checkpoint has produced its four artifacts (brief \u002F codex \u002F codex \u002F diff)\n- A `research-cowork` batch has finished merging and its log entries are settled\n- `proposal.md` just took a Workflow B major change, or accumulated several minor edits\n- `result.md` gained a new Confirmed Finding or Failed Attempt\n- A session handoff entry was just written (commit before the user `\u002Fclear`s)\n- A clear topical boundary has been crossed and several root-tracked files are dirty, even if none of the above fits exactly\n\n**When NOT to ask**:\n\n- Mid-workflow, with files only half-written (wait for the unit to land)\n- After a `src\u002F` or `doc\u002F` submodule edit where the submodule itself hasn't been committed-and-pushed yet — bumping the pointer to a dirty submodule is worse than not committing (see Section 2 \"Version control\")\n- For changes confined to `cache\u002F` or other gitignored paths\n- When the only dirty files are unrelated incidental edits (e.g., a single `AGENTS.md` typo) — batch with the next real unit instead\n\n**How to ask** — one short sentence, naming the unit and the files. Example:\n\n> *\"Survey sweep on `swe-process-reward` is done — 3 new files under `survey\u002F`, 1 new log entry. Commit root now? Suggested message: `survey: swe-process-reward sweep`.\"*\n\nIf the user says yes:\n\n1. `git -C \u003Cproject-root> status` to confirm what's actually dirty.\n2. Stage only research artifacts (`log\u002F`, `survey\u002F`, `review\u002F`, `proposal.md`, `result.md`, `survey.md`, `AGENTS.md`, `log\u002Findex.md`, `.gitignore`, `.gitmodules`). Do **not** `git add src` or `git add doc` unless the submodule itself was just committed-and-pushed in this turn — bumping pointers is a separate commit (see VC section).\n3. Use a structured prefix in the message so `git log --oneline` reads as a research timeline. Suggested prefixes: `log:`, `survey:`, `review:`, `cowork:`, `proposal:`, `result:`, `handoff:`, `bump:` (for submodule pointer bumps), `chore:` (for config\u002Fignore tweaks).\n4. Show the resulting commit hash + one-line summary back to the user.\n\nIf the user says no or \"later\" — drop it. Do not nag. The next natural unit boundary will surface the question again.\n\n---\n\n## Section 2 — Project Directory Structure\n\nEvery project lives under `~\u002FDocuments\u002Fproject\u002FNN-\u003Cslug>\u002F`, where `NN` is a zero-padded sequence number (01, 02, ...). `00-QuickReview\u002F` is reserved as a non-project scratch area for early literature\u002Frepo exploration.\n\n### Layout\n\n```\n~\u002FDocuments\u002Fproject\u002F\n  00-QuickReview\u002F                  # NON-PROJECT. Scratch for early exploration.\n                                   # Constitution does NOT apply here.\n  NN-\u003Cslug>\u002F                       # A project. Constitution applies.\n    AGENTS.md                      # Project-level persistent context (status, key constraints)\n    proposal.md                    # The kernel\n    survey.md                      # Verified related work (each row has verified_by)\n    result.md                      # Confirmed Findings + Failed Attempts (two sections)\n    talk.pptx                      # OPTIONAL. Reuse-only: presentation\u002Ftalk after research done.\n                                   # NOT used for figures in the paper.\n    survey\u002F                        # Sub-topic surveys (one file per sub-area). See research-survey skill.\n                                   # Markdown only — text artifacts the project lead reviews.\n                                   # PDFs are NOT here; they go to cache\u002Fpapers\u002F. Each sub-topic\n                                   # survey is independent; promotion to the root survey.md is by\n                                   # explicit Workflow E call (per row).\n      \u003Cslug>.brief.md              # Input contract for the worker (dispatcher fills)\n      \u003Cslug>.md                    # Worker's output: structured sub-topic survey\n      \u003Cslug>.candidates.md         # Audit trail of all candidates considered\n    cache\u002F                         # Project-level cache. Heavy\u002Fbinary artifacts only —\n                                   # never the substance of the project. If `src\u002F` or `doc\u002F`\n                                   # adopts git, cache\u002F MUST be in their .gitignore.\n      papers\u002F                      # Downloaded paper PDFs (referenced by survey.md AND survey\u002F*.md)\n      repos\u002F                       # Third-party repos cloned for reference\n      datasets\u002F                    # Original dataset downloads (before src ingestion)\n      cowork\u002F                      # Per-batch worktrees + worker artifacts (research-cowork).\n                                   # cache\u002Fcowork\u002F\u003Cbatch-id>\u002F\u003Cissue>-\u003Cslug>\u002F holds the\n                                   # git worktree, prompt.txt, events.jsonl, result.md.\n      review\u002F                      # Per-review scratch artifacts (research-review).\n                                   # cache\u002Freview\u002F\u003Cts>\u002F may hold dispatcher notes or validation\n                                   # scratch. The .md REPORTS themselves live in\n                                   # the tracked review\u002F directory, not here.\n    review\u002F                        # Key-checkpoint reviews (see research-review skill). Tracked.\n                                   # \u003Cts>.brief.md \u002F \u003Cts>.a.md \u002F \u003Cts>.b.md \u002F \u003Cts>.diff.md\n                                   # .state holds last_reviewed_log_count cursor.\n    log\u002F                           # Project timeline (see Section 5)\n      session-index.md             # Session rotation index for Feishu-mediated agents.\n      index.md                     # Auto-maintained reverse-chronological table\n      entries\u002F                     # Individual event files\n    report\u002F                        # User-facing reports. HTML primary, MD shadow.\n      YYYY-MM-DD_\u003Cslug>.html       # Self-contained visual report.\n      YYYY-MM-DD_\u003Cslug>.md         # Markdown shadow for Feishu Docx export.\n      assets\u002F\n        lib\u002F                       # Optional vendored chart\u002Fmath\u002Fcode libs.\n        \u003Cslug>\u002F                    # Per-report generated assets.\n    doc\u002F                           # LaTeX paper repo. Submodule of root.\n                                   # Independent git, Overleaf-cloned. Content is whatever\n                                   # Overleaf has — do NOT pre-stage files here before clone.\n      figures\u002F                     # ALL figures live here. Two kinds:\n                                   #   schematic: fig-\u003Cslug>.tex (standalone TikZ) + .pdf\n                                   #   result:    fig-\u003Cslug>.pdf  (copied from src\u002Fdata\u002Ffigures\u002F)\n                                   # No PNG\u002FJPG. PDF only.\n      sections\u002F                    # Per-section .tex files\n      main.tex\n    src\u002F                           # Code repo. Submodule of root.\n                                   # Independent git, bound to user's GitHub.\n      data\u002F                        # Datasets and experimental outputs (gitignored)\n      .gitignore                   # Must ignore data\u002F\n    .git\u002F                          # Root git. Local-only by default (no remote required).\n                                   # Tracks research artifacts + the two submodule pointers.\n                                   # See \"Version control\" below.\n    .gitignore                     # Excludes cache\u002F, legacy\u002F (if present), .DS_Store, etc.\n    .gitmodules                    # Lists src\u002F and doc\u002F submodules\n```\n\n### Version control (three-git layout)\n\nA research-workflow project uses **three independent gits**, with `src\u002F` and `doc\u002F` wired into the root as **submodules**:\n\n| Git | Scope | Remote | Tracked content |\n|---|---|---|---|\n| **root** | the project as a whole | optional (local-only by default) | `AGENTS.md`, `proposal.md`, `survey.md`, `result.md`, `log\u002F`, `survey\u002F`, `.gitignore`, `.gitmodules`, and the two submodule pointers |\n| **`src\u002F`** (submodule) | code | required (GitHub) | code, tests, scripts |\n| **`doc\u002F`** (submodule) | paper | required (Overleaf) | LaTeX sources, figures, bibliography |\n\n**Why three gits:**\n- Each subrepo has a natural external remote (GitHub for code, Overleaf for paper) with its own commit cadence, contributors, and CI. Bundling them into one repo would force every paper edit through a code-repo PR and vice versa.\n- The root is the **assembly point**. It pins which commit of `src\u002F` and `doc\u002F` corresponds to which state of the research artifacts (proposal version, log entries, survey rows). This is what makes the proposal → src → result → doc chain (C5) actually reproducible — at any past root commit, the two submodules check out to the exact versions that match.\n- Root has no required remote because the research artifacts are private-by-default. A user MAY add a remote (private GitHub repo) for cross-machine sync; absent that, root git just gives local history + the submodule pinning.\n\n**`cache\u002F`, `legacy\u002F`, and per-machine files are NEVER tracked by any of the three.** Root `.gitignore` MUST contain at minimum:\n\n```\ncache\u002F\nlegacy\u002F\n.DS_Store\n*.swp\n```\n\nRoot `.gitignore` does NOT list `src\u002F` or `doc\u002F` — those are submodules, tracked as pointers, not as ignored directories.\n\n**Init order during Workflow A:**\n\n1. Scaffold the directory tree and research-artifact files (steps 1–5 of Workflow A).\n2. User initializes `src\u002F` (GitHub clone) and `doc\u002F` (Overleaf clone) as instructed in step 6. These arrive as independent gits.\n3. Init root git: `git init`, write `.gitignore`, `git submodule add \u003Csrc-remote> src`, `git submodule add \u003Cdoc-remote> doc`, commit. **Defer adding a submodule whose remote does not yet exist** — initialize the directory normally and convert to a submodule later.\n4. If either submodule's remote is not ready at init time, the root git can still be created tracking only the research artifacts; add the submodule when the remote is ready and amend `.gitmodules` then.\n\n**Important interaction with C5 (modification order proposal → src → output → doc):**\n- When updating `src\u002F` or `doc\u002F`, work inside the submodule first (commit there, push to its remote).\n- Then at root, `git add src` (or `doc`) bumps the submodule pointer to the new commit. Commit at root.\n- This double-commit is the price of three-git isolation. Worth it because the root pointer is then a reproducible snapshot.\n\n**When to actually commit at root**: governed by **C9** (offer-to-commit). No fixed rhythm, no hook — at the end of an independent unit of work (survey sweep done, review landed, proposal major change, session handoff written, etc.), Codex asks the user whether to commit; the user decides. See C9 for the trigger list, the staging rules, and the message-prefix convention.\n\n### Per-file responsibilities\n\n| File | Owner | Mutability | Notes |\n|---|---|---|---|\n| `AGENTS.md` | research-workflow init | Rare edits | Holds project status (active\u002Farchived\u002Fabandoned), key constraints, target conference |\n| `proposal.md` | researcher + Codex | Iterative early, stable later | Governed by C3 modification protocol |\n| `survey.md` | Codex (after PDF read) | Append-mostly | Governed by C4. Single-paper intake via Workflow E. |\n| `survey\u002F\u003Cslug>.*` | research-survey worker sub-agent | Per-sweep | Sub-topic sweeps. See research-survey skill. Promotion to root `survey.md` is by Workflow E per row. |\n| `review\u002F\u003Cts>.*` | research-review (main Codex session + reviewer sub-agent) | Per-checkpoint | Key-checkpoint reviews. See research-review skill. `.state` carries the trigger cursor. |\n| `result.md` | Codex after each validated experiment | Append-mostly | Two sections: Confirmed Findings, Failed Attempts |\n| `talk.pptx` | Optional, post-research only | Rare | Used for talks\u002Freports AFTER research is done. Not used for paper figures. |\n| `cache\u002F` | Codex when downloading | Free | Never tracked by any git. Always in root `.gitignore`. |\n| `log\u002F` | Codex | Append-only | See Section 5. Tracked by root git. |\n| `doc\u002F` | Codex when results stable | Lagging | **Submodule.** Init by user via Overleaf clone. |\n| `src\u002F` | Codex implementing | Active | **Submodule.** Init via discussion of base framework. |\n| `.gitignore` + `.gitmodules` | research-workflow init | Rare | Root git config. See \"Version control\" above. |\n\n### What this skill does NOT manage\n\n- LaTeX template selection: the user initializes `doc\u002F` themselves on Overleaf, then `git clone`s. This skill only **reminds** the user to do this and points to the conference's formatting guidelines page.\n- Base code framework selection (verl \u002F FSDP \u002F vLLM \u002F etc.): must be **discussed** before src\u002F is initialized. This skill enforces the discussion, not the choice.\n\n---\n\n## Section 3 — Workflows\n\n### Workflow A: Starting a new project\n\nTriggered by user saying \"let's start a new topic on X\" or by `$research init \u003Cslug>` \u002F `$research-workflow init \u003Cslug>`.\n\n1. **Confirm intent**. If the user's message is ambiguous, ask: \"Is this a new top-level research project (gets its own NN-\u003Cslug>\u002F), or are we extending an existing project, or is this just exploration that should go to 00-QuickReview\u002F?\"\n2. **Discuss the seed**. Before writing any file, have a short discussion: what is the rough idea, what's the target conference, what's the rough timeline? This populates the initial AGENTS.md and proposal.md skeleton.\n3. **Compute next number**. `ls ~\u002FDocuments\u002Fproject\u002F | grep -E '^[0-9]{2}-' | sort | tail -1` → next sequence number.\n4. **Scaffold**. Create the directory tree from Section 2. Copy templates from `~\u002F.codex\u002Fskills\u002Fresearch-workflow\u002Ftemplates\u002F` into the new project, renaming as follows:\n\n   | Template | Destination | Notes |\n   |---|---|---|\n   | `AGENTS.md.template` | `\u003Cproject>\u002FAGENTS.md` | Fill `{{PROJECT_NAME}}`, `{{NN-slug}}`, `{{ONE_LINE_TOPIC}}`, `{{YYYY-MM-DD}}` from the discussion in step 2 |\n   | `proposal.md.template` | `\u003Cproject>\u002Fproposal.md` | Leave most placeholders for the researcher to fill during proposal iteration; only fill the title and date |\n   | `survey.md.template` | `\u003Cproject>\u002Fsurvey.md` | Fill title; keep the example row commented or delete it |\n   | `result.md.template` | `\u003Cproject>\u002Fresult.md` | Fill title; keep both section headers, remove example entries |\n   | `log-index.md.template` | `\u003Cproject>\u002Flog\u002Findex.md` | Fill title |\n   | `src-gitignore` | `\u003Cproject>\u002Fsrc\u002F.gitignore` | Copy verbatim |\n\n   Also `mkdir -p \u003Cproject>\u002Flog\u002Fentries \u003Cproject>\u002Fcache\u002Fpapers \u003Cproject>\u002Fcache\u002Frepos \u003Cproject>\u002Fcache\u002Fdatasets \u003Cproject>\u002Fsurvey \u003Cproject>\u002Freview`. Do NOT create `doc\u002F` or `src\u002F` contents — those are user-initialized (see step 6). The `log-entry.md.template` is for runtime use by Workflow's log-writing step, not for init.\n5. **Initialize log**. Create `log\u002Findex.md` with header, no entries yet.\n6. **Remind user about doc\u002F and src\u002F init** (three-git layout — see Section 2 \"Version control\"). Tell the user:\n   - \"Initialize `doc\u002F` by creating an Overleaf project from the target conference's template, then `git clone` it into `\u003Cproject>\u002Fdoc\u002F`. I'll wait.\"\n   - \"Before I scaffold `src\u002F`, let's discuss what base framework to build on (verl \u002F rLLM \u002F from scratch \u002F etc.). Once decided, `git clone` it from GitHub into `\u003Cproject>\u002Fsrc\u002F`.\"\n7. **Init root git + wire submodules**. After the user has cloned `src\u002F` and `doc\u002F`:\n   - `git init` at project root.\n   - Write root `.gitignore` (must include `cache\u002F`, `legacy\u002F` if present, `.DS_Store`, `*.swp`, plus per-project items). Do NOT list `src\u002F` or `doc\u002F` — they will be submodules.\n   - `git submodule add \u003Csrc-remote-url> src` and `git submodule add \u003Cdoc-remote-url> doc`. If a remote is not yet ready, defer that submodule and add when ready.\n   - Initial commit covers: `AGENTS.md`, `proposal.md`, `survey.md`, `result.md`, `log\u002F`, `survey\u002F`, `.gitignore`, `.gitmodules`, and the submodule pointers.\n   - Root remote is optional and local-only by default. Add a remote only if the user explicitly asks for cross-machine sync.\n8. **Log the init event** as `decision_project-init`.\n\n### Workflow B: Iterating on the proposal\n\nTriggered by any discussion that might affect proposal.md.\n\n1. **Determine change class** (per C3): minor or major?\n2. If **minor**: edit `proposal.md`, log as `proposal-update`, surface a one-line summary to user.\n3. If **major**:\n   - Stop. Do not edit.\n   - State the conflict: \"What you're proposing changes [aspect X] of the proposal. Previously we said [Y]. This invalidates [Z list of artifacts].\"\n   - Wait for user confirmation.\n   - On confirmation: edit, log as `proposal-update` with `related:` field pointing to all invalidated artifacts. Trigger Workflow F (cascade check).\n4. **Schematic figures** (only if the method has stabilized enough to be drawn): create `doc\u002Ffigures\u002Ffig-\u003Cslug>.tex` using the `standalone` document class with TikZ; compile it locally (`pdflatex` in `doc\u002Ffigures\u002F`) to produce `fig-\u003Cslug>.pdf`. Reference the PDF from `doc\u002Fsections\u002F*.tex` via `\\includegraphics`. Don't draw schematics for moving targets — wait until the method is settled.\n\n### Workflow C: Running an experiment\n\n1. Confirm experiment is connected to a proposal claim. If not, ask why we're running it.\n2. Implement \u002F modify in `src\u002F`.\n3. Run, capture raw outputs in `src\u002Fdata\u002F`.\n4. **Decide outcome**: did it confirm or contradict the proposal?\n   - **Confirms**: append to `result.md` `## Confirmed Findings` with quantitative summary.\n   - **Contradicts**: append to `result.md` `## Failed Attempts` with hypothesis, actual result, suspected reason, whether still open question. Then **trigger Workflow B (major change check)** — does this contradiction force a proposal revision?\n5. **Result figures** (only if the result is publication-relevant): write a plotting script under `src\u002Fscripts\u002Fplot_*.py` (matplotlib \u002F seaborn \u002F TikZ \u002F PGFPlots). Output PDF to `src\u002Fdata\u002Ffigures\u002F`, then **copy** (not symlink — `doc\u002F` is a separate git repo) the PDF into `doc\u002Ffigures\u002F`.\n6. Log as `experiment` with status=done, `related:` pointing to proposal sections it tested.\n\n### Workflow D: Updating doc\u002F\n\n1. Verify the claim being added to doc\u002F has a corresponding entry in `result.md` `## Confirmed Findings`. If not, refuse — use `\\todo{}` placeholder instead.\n2. Modify `doc\u002Fsections\u002F*.tex`.\n3. **Citations**: never write BibTeX from memory. Defer to `ml-paper-writing` skill rules. If a citation can't be verified, mark as `\\cite{PLACEHOLDER_...}`.\n4. Log as `doc-update`.\n\n### Workflow E: Adding to survey.md (single-paper intake)\n\n**Routing note**: if the user mentions a *sub-area* rather than a specific paper (\"调研一下 X 方向 \u002F sweep the literature on X\"), route to **Workflow E'** instead. Workflow E is for single-paper intake.\n\n1. The user mentions a paper, OR Codex suggests a paper to look at.\n2. Log as `survey-add` with status=todo.\n3. **Download the PDF** (arxiv URL, conference page, etc.) into `cache\u002Fpapers\u002F\u003Cpaper-id>.pdf`. If you can't download, the entry stays in `log\u002F` as todo and never enters `survey.md`.\n4. **Read the PDF** (at minimum: abstract, intro, method, conclusion).\n5. Append a row to `survey.md` with: title, link, venue, relation to our proposal, key difference, `verified_by: cache\u002Fpapers\u002F\u003Cpaper-id>.pdf`.\n6. Mark log entry as status=done.\n\n### Workflow E': Surveying a sub-topic (sweep)\n\nTriggered when the request is to investigate a sub-area, not to record a known paper. Delegates to the `research-survey` sub-skill.\n\n1. **Disambiguate** if needed: \"Is this a sub-area sweep, or a single paper you've already identified?\" If single, switch to Workflow E.\n2. **Draft a brief**. Main agent creates `\u003Cproject>\u002Fsurvey\u002F\u003Cslug>.brief.md` from `~\u002F.codex\u002Fskills\u002Fresearch-survey\u002Ftemplates\u002Fsubtopic-brief.md.template`. Fill every required field; pull `time_window_start` from this project's creation date (NOT today), pull `accepted_venues` from this project's `AGENTS.md`. Log as `survey-sweep` with status=todo.\n3. **Dispatch workers**. Spawn one Codex sub-agent per sub-topic. Prompt each worker to read `~\u002F.codex\u002Fskills\u002Fresearch-survey\u002FSKILL.md` and execute against the brief's absolute path. Multiple sub-topics can run in parallel. Workers do not share state; the dispatcher dedups after they return.\n4. **Receive the worker's final message**. Read `survey\u002F\u003Cslug>.md`, the candidates audit trail, and the sweep log entry. Surface to the user:\n   - Count summary (papers in survey, code not-found, venue needs-review)\n   - Any flagged items that need a dispatcher decision (venue inclusion, dropped-for-unavailable retries)\n5. **Promote rows to root `survey.md`** (per user direction or your own judgment, then user confirm). Each promoted row is a Workflow E call; the `verified_by` field is already set, so the PDF check is satisfied — no re-verification needed. The sub-topic `survey\u002F\u003Cslug>.md` remains as the source of truth for that sweep's full per-paper writeup.\n6. Mark the `survey-sweep` log entry as status=done.\n\n**Why this is separate from Workflow E**: a sweep produces 8–15 rows in one operation; doing it through 8–15 sequential Workflow E calls loses the sub-topic context (axes_of_interest, search trace, coverage notes) that makes the sweep valuable later. The sub-topic file preserves that context; the root `survey.md` row is the promoted summary.\n\n### Workflow G: Executing queued code TODOs via a cowork batch\n\nTriggered when ≥ 1 log entry of type `src-update` (or similar code-change type) has `status: todo` AND the work is concrete code writing in `src\u002F` (not exploratory debugging, not a design discussion). Delegates to the `research-cowork` sub-skill.\n\n1. **Identify the batch**. Filter `log\u002Fentries\u002F` for `type=src-update` AND `status=todo`. Confirm the work is code-writing (not \"decide between approaches\"). If only one TODO and it's a single small change, prefer a direct commit inside Workflow C — cowork pays off when ≥ 2 atomic, parallelizable issues exist.\n2. **Preflight environment**. Per `research-cowork` SKILL.md: verify the target repo, `git`, `gh` if PRs are expected, and test commands. Parallel Codex sub-agents are the worker model; do not add a nested `codex exec` layer.\n3. **Confirm scope with the user** before opening any GitHub issue. Present the candidate batch (which TODOs become which issues, source repo, batch id) and wait for approval.\n4. **Hand off to research-cowork**. Execute the cowork workflow: decompose into atomic issues → assign disjoint file scopes → spawn parallel Codex sub-agents → review worker reports\u002FPRs → resolve conflicts at merge → update logs.\n5. **Source TODO close-out**. For each `src-update` log entry that was closed by a merged PR, set `status: done` and add a body line referencing the cowork batch id and PR number.\n6. **Log the batch**. Write a `cowork-batch` log entry (type defined in Section 5). Summary: N issues, M PRs merged, K conflicts resolved, and source repo. Failures use `cowork-batch-failure`.\n7. **Trigger Workflow F (cascade check)** after the batch lands — a non-trivial code change in `src\u002F` may invalidate proposal claims, result findings, or doc sections.\n\n**Why this is separate from Workflow C (running an experiment)**: Workflow C is one researcher + one running experiment; the code edit there is incidental and stays in the local working tree. Workflow G is multiple parallel atomic edits, each landing through its own PR — needed when the queue has several independent code TODOs and the project benefits from independent reviews.\n\n### Workflow H: Key-checkpoint review (two parallel reviewer sub-agents + diff pass)\n\nTriggered when `~\u002F.codex\u002Fskills\u002Fresearch-review\u002Fbin\u002Freview-trigger \u003Cproject_root>` reports `TRIGGER` (≥ 10 new log entries since last review), OR when the user explicitly asks for a review (\"review 一下\"). Delegates to the `research-review` sub-skill.\n\n1. **Trigger detection**. Either: (a) after writing a log entry, run `review-trigger` and observe `TRIGGER`, then **proactively suggest** a review to the user (do not run autonomously); (b) the user manually requests one. Wait for user confirmation before starting.\n2. **Draft the brief**. Main agent fills `\u003Cproject>\u002Freview\u002F\u003Cts>.brief.md` from `~\u002F.codex\u002Fskills\u002Fresearch-review\u002Ftemplates\u002Freview-brief.md.template`. Required fields include the log window (from `since_log_entry` to latest), snapshot paths (proposal.md, result.md, survey.md, survey\u002F*.md), novelty parameters (fixed: 3 months, 4 sources), and output paths.\n3. **Dispatch TWO reviewer sub-agents in parallel** (per research-review — architectural symmetry). In **one message**, main Codex session invokes two Codex reviewer sub-agents:\n   - Reviewer A (`reviewer-prompt.md.template`, `reviewer_id=codex_a`) -> produces `\u003Cts>.a.md`\n   - Reviewer B (`reviewer-prompt.md.template`, `reviewer_id=codex_b`) -> produces `\u003Cts>.b.md`\n   Neither prompt references the other's output path. Main Codex session does NOT do any review work itself in the main session.\n4. **Return to useful work**. Main Codex session does not poll unless blocked on the review outcome.\n5. **Generate the diff**. After both reports exist, use a third sub-agent or deterministic comparison pass to produce `\u003Cts>.diff.md`. If either reviewer failed, skip this step.\n6. **Present result**. Main Codex session reads the diff headline and surfaces it to the user. Updates `\u003Cproject>\u002Freview\u002F.state` (`last_reviewed_log_count`, `last_reviewed_log_entry`, `last_reviewed_ts`).\n7. **Log the review**. Write `\u003Cts>_review_\u003Cslug>.md` log entry (type=`review`, or `review-failure` if any sub-agent returned `failed`). Cites the four report paths.\n8. **Trigger Workflow F (cascade check)** ONLY if the review surfaces consensus RED-FLAGs that the researcher decides to act on. Review by itself does not mutate research artifacts (per research-review C-R6).\n\n**Why this is separate from Workflow F (cascade check)**: cascade check is a one-shot integrity scan after a specific known change; key-checkpoint review is a periodic parallel-reviewer audit triggered by accumulated activity. Review surfaces *what should be questioned*; cascade check propagates *what is already decided*.\n\n### Workflow F: Cascade check (after any major change)\n\nAfter a major proposal change, src refactor, or contradicting experiment:\n\n1. Scan `proposal.md` — any sections invalidated?\n2. Scan `log\u002F` for status=todo entries — any obsolete or now-blocked?\n3. Scan `result.md` — any Confirmed Findings now in question?\n4. Scan `doc\u002Fsections\u002F` — any claims now unsupported?\n5. For each: surface to user with options (update \u002F drop \u002F supersede). Do not silently propagate.\n\n---\n\n## Section 4 — Figure rules\n\nFigure production is **part of the workflows** (schematics in Workflow B step 4, result plots in Workflow C step 5), not a separate phase. All figures live under `doc\u002Ffigures\u002F` — even result plots produced from `src\u002F`. Only the rules live here:\n\n- **No raster images.** All figures must be vector PDF. PNG \u002F JPG \u002F screenshot are rejected from `doc\u002Ffigures\u002F`.\n- **Schematics** (architecture diagrams, conceptual workflows, illustrations) → write `doc\u002Ffigures\u002Ffig-\u003Cslug>.tex` using `\\documentclass[tikz,border=2pt]{standalone}` + TikZ → compile with `pdflatex` to `fig-\u003Cslug>.pdf` → `\\includegraphics` from `doc\u002Fsections\u002F*.tex`. One `.tex` per figure. **Do not use `beamer` or `pptx` for paper figures.**\n- **Result plots** (loss curves, ablation bars, scatter, heatmaps) → matplotlib \u002F seaborn \u002F PGFPlots in `src\u002Fscripts\u002Fplot_*.py` → PDF emitted to `src\u002Fdata\u002Ffigures\u002F` → **copy** (not symlink — `doc\u002F` is a separate git repo) the PDF to `doc\u002Ffigures\u002Ffig-\u003Cslug>.pdf`.\n- **Timing**: draw schematics only when the method has stabilized; draw result plots only when the result is publication-relevant. Premature figures rot fast.\n- **`talk.pptx` is unrelated to paper figures.** It exists only for post-research talks \u002F reports. Never source a paper figure from it.\n\n---\n\n## Reports — HTML primary, MD shadow\n\nUse `vibe-report` for report-specific authoring\u002Fdeployment guidance and templates. This section defines the durable artifact contract that `vibe-report` inherits.\n\nWhen the user or a full-auto workflow asks for a written report, default to a visual HTML report plus a Markdown shadow:\n\n- Primary artifact: `report\u002FYYYY-MM-DD_\u003Cslug>.html`. It should be self-contained: inline CSS, inline JS only when needed, and base64 or local generated assets. The user should be able to open it locally without a dev server or internet access.\n- Shadow artifact: `report\u002FYYYY-MM-DD_\u003Cslug>.md`. It carries the same claims in plain prose and is the source for later Feishu Docx export.\n- Generated assets live under `report\u002Fassets\u002F\u003Cslug>\u002F`. Reusable optional libraries live under `report\u002Fassets\u002Flib\u002F`.\n- Use vendored Chart.js, KaTeX, or highlight.js only when they are already available. Do not make report generation depend on network downloads. Plain CSS, inline SVG, and static tables are acceptable defaults.\n- Do not use React, Vue, or a build step for reports unless the user explicitly asks for an app rather than a report.\n- Author with the existing single-writer discipline. A reviewer can add inline `\u003Caside class=\"reviewer-note\">...\u003C\u002Faside>` blocks or a separate review log; the primary author resolves them before final delivery.\n- Match visualization complexity to signal. Use charts, timelines, matrices, and callouts when they clarify the result; do not decorate sparse evidence.\n- The report must present findings and the data behind them together: key findings, visual evidence, method\u002Fscope, caveats, and links to source artifacts should all be visible in the HTML.\n- In Feishu bridge mode, prefer Bridge `\u002Freport`: Claude defaults to the HTML\u002Ffront-end artifact via `vibe-report`; Codex defaults to deployment with `vrc report serve`.\n- `vrc report serve \u003Cworkspace> \u003Creport.html>` serves the report from the topic workspace with backend Basic Auth, binds `0.0.0.0`, chooses an available port, generates a controller-reachable `http:\u002F\u002F\u003Chost>:\u003Cport>\u002F...` URL using `report_public_host` or host-IP detection, and sends credentials to the controller by Feishu DM. Do not post report passwords in the group.\n- Commit the HTML, MD, and required assets as normal workspace artifacts after the report unit is complete and the user approves the commit.\n\n---\n\n## Section 5 — The log\u002F system\n\nThe log replaces `TODO.md`, `decisions.md`, and any other timeline document. Everything that happens with a timestamp goes here.\n\n### File layout\n\n```\nlog\u002F\n  index.md                                # Auto-maintained, reverse-chronological table\n  entries\u002F\n    YYYY-MM-DD_HHMM_\u003Ctype>_\u003Cslug>.md      # Individual events\n```\n\n### Event file schema\n\n```markdown\n---\ntimestamp: 2026-04-29T11:00:00+08:00\ntype: \u003Cone of: debate | decision | experiment | proposal-update | src-update | doc-update | survey-add | survey-sweep | survey-sweep-failure | cowork-batch | cowork-batch-failure | review | review-failure>\nslug: short-kebab-case\nstatus: todo | done           # OPTIONAL. Only used for actionable events.\nsessions: [\u003Ccc-session-id>, ...]   # OPTIONAL. Cross-references to Codex sessions.\nrelated: [\u003Cother-entry-filename>]   # OPTIONAL. Links to related events.\n---\n\n# One-line title\n\n**Summary**: One sentence. This is what shows up in `index.md`.\n\n**Details**: Free-form markdown body. As long as needed.\n```\n\n### When entries are created\n\n**Codex proactively offers** to create a log entry after:\n- A round of proposal\u002Farchitecture discussion concludes\n- An experiment finishes (success or failure)\n- The user states a clear decision (\"let's go with X\", \"drop Y\")\n- A non-trivial change to proposal.md \u002F src\u002F \u002F doc\u002F lands\n- A debate ends without resolution (log as `debate`, status=open if you add status)\n\n**Manual creation** via `$research log \u003Ctype> \u003Cslug> [--status todo]` or `$research-workflow log \u003Ctype> \u003Cslug> [--status todo]`.\n\nIn both cases, the actual file may be written directly by the main Codex session or by a lightweight Codex sub-agent when isolation is useful.\n\n### index.md\n\nAuto-maintained. Reverse-chronological. Full list, no truncation. Format:\n\n```markdown\n# Project NN-\u003Cslug> Timeline\n\n| Date | Type | Slug | Summary | Status |\n|---|---|---|---|---|\n| 2026-04-29 11:00 | proposal-update | drop-multi-task | Removed multi-task variant after 4 ablations showed no gain | done |\n| 2026-04-29 09:30 | debate | aux-loss-question | Discussed adding aux loss; no decision | — |\n| ... |\n```\n\nRegenerated by `~\u002F.codex\u002Fskills\u002Fresearch-workflow\u002Fbin\u002Flog-filter --regenerate-index` after any new entry.\n\n### Filter program\n\n`bin\u002Flog-filter` (bash, uses ripgrep + awk). Output mimics `git log --oneline`.\n\n```bash\nlog-filter                              # All events, reverse-chronological\nlog-filter --type experiment            # Only experiments\nlog-filter --status todo                # Only open todos\nlog-filter --slug multi-task            # Slug substring match\nlog-filter --recent 10                  # Last 10\nlog-filter --type src-update --recent 5 # Combine filters\nlog-filter --regenerate-index           # Rewrite index.md from entries\u002F\n```\n\nThe script is idempotent and stateless — it only reads `entries\u002F` and prints \u002F overwrites `index.md`.\n\n---\n\n## Section 6 — Inter-skill routing\n\nresearch-workflow does not duplicate domain skills. It **routes** to them at the right moment.\n\nThe full list of relevant skills installed locally is in [`available-skills.md`](.\u002Favailable-skills.md). Consult that file when picking a skill. High-frequency routings:\n\n| Lifecycle stage | Default skill |\n|---|---|\n| Brainstorming early ideas \u002F pivoting | `brainstorming-research-ideas` |\n| Stuck, need creative leap | `creative-thinking-for-research` |\n| Surveying a sub-topic (sub-area sweep, not single-paper intake) | `research-survey` |\n| Executing queued code TODOs (≥ 2 atomic issues in parallel via Codex sub-agents) | `research-cowork` |\n| Key-checkpoint review of the research (parallel codex + Codex, four dimensions) | `research-review` |\n| Drafting \u002F refining the paper | `ml-paper-writing` (a.k.a. `20-ml-paper-writing`) |\n| Drawing schematic figures | Direct LaTeX\u002FTikZ in `doc\u002Ffigures\u002F` (standalone, no skill required) |\n| Post-research talk \u002F report slides | `pptx` (document-skills) — only for `talk.pptx`, never for paper figures |\n| RL post-training | `verl`, `openrlhf`, `trl-fine-tuning`, `grpo-rl-training` |\n| Distributed training scaffolding | `accelerate`, `pytorch-fsdp2`, `megatron-core` |\n| Inference for eval \u002F agent harness | `vllm`, `sglang` |\n| Evaluation | `lm-evaluation-harness`, `bigcode-evaluation-harness` |\n| Experiment tracking | `weights-and-biases` |\n\nWhen you spot that a different skill in `~\u002F.codex\u002Fskills\u002F` would help and isn't in `available-skills.md`, **suggest adding it** rather than silently using it. The user maintains the whitelist.\n\n---\n\n## Section 7 — Common Anti-patterns\n\n| Anti-pattern | Symptom | Correction |\n|---|---|---|\n| **Eager proposal rewrite** | Modifying proposal.md every time an experiment surprises us | Apply C3 — minor vs major distinction. Most surprises are minor adjustments to claims, not core revisions. |\n| **Survey by hearsay** | Adding entries to survey.md based on titles\u002Fabstracts only | Apply C4 hard. PDF must exist locally; verified_by must point to it. |\n| **Doc gets ahead of results** | Writing claims in doc\u002F before result.md confirms them | Apply C5. Use \\todo{} placeholders. doc is a lagging mirror. |\n| **Silent cascades** | Changing src\u002F without checking proposal\u002Fdoc\u002Flog impact | Apply C6. After any non-trivial change, run cascade check (Workflow F). |\n| **Decision without log** | \"We decided X\" but no log entry | Offer to log immediately. Log entries are cheap, retrieval is priceless. |\n| **Raster figures sneaking in** | PNG screenshots in doc\u002Ffigures\u002F | Reject. Apply Section 4. Either redo as a standalone TikZ schematic or as a matplotlib\u002FPGFPlots PDF. |\n| **Citations from memory** | BibTeX entries Codex wrote without API verification | Reject per ml-paper-writing rules. Use \\cite{PLACEHOLDER_...} until verified. |\n| **Constitutional drift** | Mid-session, Codex forgets the constitution | Re-read project-level AGENTS.md. The user can also remind by saying \"constitution check\". |\n| **Long-session quality decay** | Conversation past ~50 turns, hedged\u002Frepetitive answers, or about to start a new sub-task — but Codex keeps going | Apply C8. Stop, write a handoff log entry, suggest `\u002Fclear`. Multi-session work is normal. |\n\n---\n\n## Section 8 — Skill Entry Aliases\n\nCodex CLI does not load user-defined slash commands from `~\u002F.codex\u002Fcommands`.\nUse `\u002Fskills`, `$skill-name` mentions, or natural language. Common argument\nshapes:\n\n- `$research init \u003Cslug>` — Workflow A. Creates the project scaffold.\n- `$research log \u003Ctype> \u003Cslug> [--status todo|done]` — Manually create a log entry.\n- `$research filter [args]` — Wraps `bin\u002Flog-filter`. Same args.\n- `$research check` — Run cascade check (Workflow F) on the current project.\n- `$research status` — Show current project's AGENTS.md status, recent log activity, open todos.\n\n---\n\n## Notes for the agent\n\n- This skill is meta. Do not put domain advice here. If you find yourself wanting to write \"how to brainstorm\" or \"how to pick baselines\", that belongs in another skill.\n- The constitution is maintained primarily by the project-level `AGENTS.md` that init writes. SKILL.md (this file) is the source of truth, but the user-facing daily enforcer is the per-project AGENTS.md.\n- When in doubt, follow C7: ask the user. This is a meta skill about disciplined collaboration, not autonomous execution.\n",{"name":5,"license":15,"description":7},"main","7d4c66b07159d74c8fa9cb32475f008f8d36fe0e","plugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow","https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit","https:\u002F\u002Fgithub.com\u002FSiyuexi","siyuexi.github.io","Ph.D., Chinese University of Hongkong, Shenzhen.","2026-06-04 14:03:14",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add Siyuexi\u002Fcodex-research-kit --skill research-workflow",{"tool":38,"command":39},"bunx","bunx skills add Siyuexi\u002Fcodex-research-kit --skill research-workflow",{"tool":41,"command":42},"pnpm","pnpm dlx skills add Siyuexi\u002Fcodex-research-kit --skill research-workflow","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002FSKILL.md",true,[46,52,56,62,66,70,74,78,82],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"agents\u002Fopenai.yaml","REFERENCE","参考文档",254,"https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002Fagents\u002Fopenai.yaml",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"available-skills.md",5231,"https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002Favailable-skills.md",{"path":57,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":60,"sourceHtmlUrl":61},"templates\u002FAGENTS.md.template","OTHER","其他",2205,"https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002Ftemplates\u002FAGENTS.md.template",{"path":63,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":64,"sourceHtmlUrl":65},"templates\u002Flog-entry.md.template",604,"https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002Ftemplates\u002Flog-entry.md.template",{"path":67,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":68,"sourceHtmlUrl":69},"templates\u002Flog-index.md.template",341,"https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002Ftemplates\u002Flog-index.md.template",{"path":71,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":72,"sourceHtmlUrl":73},"templates\u002Fproposal.md.template",2218,"https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002Ftemplates\u002Fproposal.md.template",{"path":75,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":76,"sourceHtmlUrl":77},"templates\u002Fresult.md.template",1474,"https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002Ftemplates\u002Fresult.md.template",{"path":79,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":80,"sourceHtmlUrl":81},"templates\u002Fsrc-gitignore",516,"https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002Ftemplates\u002Fsrc-gitignore",{"path":83,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":84,"sourceHtmlUrl":85},"templates\u002Fsurvey.md.template",1005,"https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fresearch-workflow\u002Ftemplates\u002Fsurvey.md.template",[87,94,101,108,115,122],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M74GQZRN00Z8X286V57MRQJZ","vibe-survey","Compatibility alias for research-survey. Use when the user says vibe-survey or asks for the old \u002Fvibe-survey behavior.","https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fvibe-survey\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":19},"01M74GQY8M79RG5N901D6YQ4F9","vibe-review","Compatibility alias for research-review. Use when the user says vibe-review or asks for the old \u002Fvibe-review behavior.","https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fvibe-review\u002FSKILL.md",[],[],{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":19},"01M74GQVHX1BBTCC4SRS31G18H","vibe-research","Compatibility alias for research-workflow. Use when the user says vibe-research or asks for the old \u002Fvibe-research behavior.","https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fvibe-research\u002FSKILL.md",[],[],{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":19},"01M74GQQRT2EF984V3VEV373NN","vibe-report","VRC report support and deployment skill. Use when the controller asks for a visual web report, deployed report, Feishu-readable report page, report template, or Bridge \u002Freport workflow. Codex defaults to data\u002Fbackend validation and deployment; Claude defaults to HTML\u002Ffront-end authoring.","https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fvibe-report\u002FSKILL.md",[],[],{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":19},"01M74GQMHST4D5QD2EBKBZSK83","vibe-discuss","Feishu-mediated peer collaboration protocol for Claude and Codex on research-workflow projects. Use when the user asks to set up or operate a topic\u002Fproject group, review or implement the protocol in protocol.md, coordinate Claude\u002FCodex discussion, log consensus\u002Fdebate\u002Fhandoff outcomes, manage shared workspace write discipline, run independent cross-agent reviews, or start\u002Finspect the optional full-auto worktree sandbox.","https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fvibe-discuss\u002FSKILL.md",[],[],{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":128,"publishedAt":19},"01M74GQHT45KQT8GE88ZPBQXKA","vibe-cowork","Compatibility alias for research-cowork. Use when the user says vibe-cowork or asks for the old \u002Fvibe-cowork behavior.","https:\u002F\u002Fgithub.com\u002FSiyuexi\u002Fcodex-research-kit\u002Fblob\u002Fmain\u002Fplugins\u002Fcodex-research-kit\u002Fskills\u002Fvibe-cowork\u002FSKILL.md",[],[]]