research-survey
[research-workflow sub-skill] Scoped to research-workflow projects only — do not invoke as a standalone tool. Defines how to survey a sub-topic for a research project. Use when the task is 'investigate this sub-area' rather than 'record this one paper' — e.g., the main agent receives a sub-topic brief, or research-workflow Workflow E discovers it is facing a sub-area sweep, not a single-paper intake. Defines the input contract (so sub-agents can work without follow-up questions), the six survey constitution rules (recency, venue, version, code, content fields, objectivity), the sweep workflow, and the output format. Pairs with research-workflow Workflow E' (sub-topic surveying).
- License 许可
- MIT
- 最近更新
- 2026-06-04
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- research-survey
- license
- MIT
- description
- [research-workflow sub-skill] Scoped to research-workflow projects only — do not invoke as a standalone tool. Defines how to survey a sub-topic for a research project. Use when the task is 'investigate this sub-area' rather than 'record this one paper' — e.g., the main agent receives a sub-topic brief, or research-workflow Workflow E discovers it is facing a sub-area sweep, not a single-paper intake. Defines the input contract (so sub-agents can work without follow-up questions), the six survey constitution rules (recency, venue, version, code, content fields, objectivity), the sweep workflow, and the output format. Pairs with research-workflow Workflow E' (sub-topic surveying).
02 资源文件 6
03 SKILL.md 正文
research-survey — Surveying a Sub-Topic for a research-workflow Project
This skill is a sub-skill of research-workflow. It does not redefine the research constitution — it inherits from research-workflow SKILL.md — and it does not handle single-paper intake (that is research-workflow Workflow E). It handles the case where the task is "go investigate sub-area X and bring back a structured survey".
The skill is designed to be runnable by isolated sub-agents (no ability to ask the user back). It therefore enforces an explicit input contract: the dispatcher must provide every field the worker needs up-front. If the brief is incomplete, the worker returns a failure receipt rather than guessing.
When to Use
- The main agent or user says: "调研一下 X 这个子方向 / sweep the literature on X / survey related work on X"
- research-workflow Workflow E's step 1 reveals the request is not a single paper but a sub-area
- A
survey/<slug>.brief.mdfile is handed to a worker (sub-agent or remote routine) - Inside an auto research-workflow run, the controller dispatches sub-topic sweeps in parallel
When NOT to Use
- A specific paper is already named and needs recording → research-workflow Workflow E (single-paper intake)
- Early brainstorming with no target sub-topic yet →
brainstorming-research-ideas - The project lives in
~/Documents/project/00-QuickReview/(no project constitution applies; do whatever is convenient) - Citation / BibTeX verification during paper writing →
20-ml-paper-writing
Section 1 — Input Contract (the brief)
A sub-agent cannot call ask the user. To avoid mid-task guessing, every sweep starts from a brief that the dispatcher fills out. The brief is a markdown file under <project>/survey/<slug>.brief.md, generated from templates/subtopic-brief.md.template.
Required fields
| Field | Meaning | Example |
|---|---|---|
subtopic |
One-line description of the sub-area | "Advantage normalization techniques in GRPO-style RL fine-tuning" |
slug |
kebab-case identifier, used in filenames | grpo-adv-norm |
parent_proposal_ref |
Relative path (or proposal.md#section) the worker reads to learn the main topic |
../proposal.md#section-3-method |
axes_of_interest |
Comma list of dimensions the worker should compare against the parent topic | task, method, dataset, metric |
time_window_start |
ISO date, defaults to the project's creation date (NOT today). Fixed across the project's life. | 2026-05-14 (means: papers published on/after this date, looking back 5 years → 2021-05-14) |
venue_whitelist_extra |
Project-specific extras beyond CCF-A (read from project AGENTS.md accepted_venues) |
ICLR, COLM, TMLR |
target_count |
Soft cap on number of papers in the final survey (recommend 8–15; if a sub-topic needs >20, the dispatcher should split it) | 12 |
output_path |
Where to write the survey | survey/grpo-adv-norm.md |
Optional fields
| Field | Meaning |
|---|---|
seed_papers |
Known-relevant papers the dispatcher already has, used as anchors for cite-chain search |
exclude_papers |
DBLP keys / arXiv ids to skip (already in main survey.md, or known irrelevant) |
recency_override |
If set, expands time window beyond 5 years (with reason, e.g., "include foundational 2017 paper X") |
notes_for_worker |
Free-form extra context (subtle distinctions, terminology the worker should not confuse) |
Time window semantics (per the project decision)
time_window_startis the project's creation date, recorded once and reused.- The accepted publication window is
[time_window_start - 5 years, today]. - Rationale: a survey done in month 1 and a survey done in month 10 of the same project should agree on what "近五年" means. Rolling windows break this.
- If the worker needs to break the 5-year wall, the dispatcher must set
recency_overridein the brief. The worker does NOT decide this on its own.
If the brief is incomplete
The worker does not guess. It writes a failure receipt (see templates/failure-receipt.md.template) listing the missing fields and stops. The dispatcher fixes the brief and re-dispatches.
Section 2 — The Survey Constitution (C-S1 ~ C-S6)
These rules govern every sweep. They sit below the research-workflow constitution (C1–C8) and inherit from it; where this skill is silent, research-workflow applies.
C-S1. Recency: ≥ (project-creation-date − 5 years)
Default: only papers published in the 5-year window described in Section 1.
- Why: surveys for active research projects need current state of the art, not historical foundations.
- How to apply: filter candidates by publication year against
time_window_start − 5y. Older papers go to adropped_for_recencylist at the bottom of the candidates file, not into the survey. - Override: only when
recency_overrideis set in the brief.
C-S2. Venue: CCF-A by default, plus project-declared extras
- Default whitelist: CCF-A conferences and journals across the relevant area (AI/ML: NeurIPS, ICML, AAAI, IJCAI, ACL, EMNLP, NAACL, CVPR, ICCV, ECCV, TPAMI, IJCV, JMLR, TOG, SIGGRAPH; SE: ICSE, FSE, ASE, ISSTA, OOPSLA, TSE, TOSEM; Sys: SOSP, OSDI, ASPLOS, ISCA, MICRO, HPCA, SIGCOMM, NSDI, MobiCom, FAST, EuroSys; DB: SIGMOD, VLDB, ICDE; Sec: CCS, S&P, USENIX Security, NDSS; Theory: STOC, FOCS, SODA, LICS, CAV; HCI: CHI, UIST, CSCW). When in doubt about a venue's tier, do not silently include it — the worker writes the candidate to the candidates file with
venue_justification: needs-reviewand surfaces it in the final receipt for the dispatcher to decide. - Project extras: the project's
AGENTS.mdmay declare anaccepted_venues:field naming additional venues the project considers acceptable (ICLR, COLM, TMLR are common examples). The worker reads this and merges it with the CCF-A default. The brief'svenue_whitelist_extraoverrides per-sweep. - Workshop papers, arXiv-only papers, technical reports: not acceptable as primary entries. They may appear as
discovered_viareferences for context but do not get rows in the survey. - Why: keeps the sweep anchored to peer-reviewed venues the project lead trusts, while allowing per-project flexibility.
C-S3. Version: publication > arXiv
- Preferred: the venue's published version (PDF from the publisher's site, the conference proceedings page, or the journal page).
- Acceptable fallback: if the publication version is paywalled and not retrievable, use the arXiv version. Record
version: arxiv-fallbackandfallback_reason: paywalledon the entry. - Not acceptable: using arXiv when the publication version is freely available. The worker must attempt the publication URL first and record the attempt.
- Why: the publication version is the one of record; reviewers will compare to it.
C-S4. Code: open-source repository required (or proof of absence)
Every survey entry must carry either:
code: <github-url>— verified to exist and to correspond to the paper, ORcode: not-foundplus asearch_traceshowing the three search steps were performed:- Paper-side: searched the paper PDF (abstract, footnotes, intro, "Code available at", appendix) for any URL
- Author-side: checked the first/last author's GitHub profile for a repo matching the paper title or method name
- Topic-side: searched GitHub for
<method-name>and<paper-keywords>to find third-party reimplementations (if even a third-party repo exists, log it but markcode: third-party-only)
code: not-found without a search_trace is treated as missing data — the entry is rejected from the survey.
C-S5. Content fields (per entry)
Every entry must contain these fields, factually stated:
what: what the paper does (1–3 sentences, descriptive only)goal: the stated purpose / problem it tries to solve (in the paper's own framing)relation_to_parent: how this work connects to the parent project's topic, across theaxes_of_interestdifferences: in what dimensions this work diverges from the parent topic (task / method / setting / data / metric — be specific)salience_axes: which of the brief'saxes_of_interestthis paper actually touches (this is factual labeling, not a judgment). Example:[task, dataset]if the paper shares the task and dataset but not the method.
C-S6. Objectivity: no value judgments
The worker describes facts. The worker does not:
- Rank papers by importance, relevance, novelty, or "collision risk" with the parent topic
- Use evaluative language: "the most likely to overlap", "the most worth learning from", "SOTA", "seminal", "groundbreaking", "weak", "strong"
- Recommend which paper the user should read first
The downstream analyst (human or another agent) decides what is salient. The worker's job is to produce a clean, complete, factual record so that downstream judgment is well-supported.
Stating that a paper "shares dataset X with our proposal" is factual. Stating that it "is likely to be a direct competitor" is not. Keep to the first kind.
Section 3 — Workflow (a sweep, end to end)
This is the worker's procedure. Each step is concrete enough that a sub-agent with no prior context can execute it given only the brief and access to research-workflow SKILL.md.
Step 0 — Read brief and verify completeness
- Read
<project>/survey/<slug>.brief.md - Verify all required fields (Section 1) are present and non-empty
- Read project
AGENTS.mdto fetchaccepted_venues - If any required field missing → write failure receipt → stop
Step 1 — Read the parent proposal
Read the parent_proposal_ref target. Extract:
- The parent topic in one sentence
- The specific dimensions named in
axes_of_interest(e.g., what task, what method family, what dataset) - Vocabulary the parent uses (to align terminology in
relation_to_parent/differenceslater)
Step 2 — Discovery (cast a wide net)
Goal: collect 30–50 candidates with metadata only (no PDF download yet).
Sources, in order of trust:
- Venue ToCs: for each venue in the whitelist, scan the relevant year's accepted papers list for keyword matches
- DBLP: author / keyword queries scoped to the venue whitelist and time window
- Google Scholar: keyword search with
venue:and year filters; useful for finding the publication version of a paper you only know from arXiv - Cite-chain from seed_papers: forward and backward citations of any
seed_papersin the brief - arXiv: only for finding the publication-version URL of a recent paper; never as the primary source
For each candidate, record metadata in <project>/survey/<slug>.candidates.md (template provided):
- Title, authors, venue, year
- Stable ID (DBLP key preferred, else arXiv id, else DOI)
discovered_via: which source surfaced it- Abstract (copied verbatim)
- Provisional
venue_status: in-whitelist / project-extra / needs-review / out-of-scope
Step 3 — Filter candidates
Apply, in order:
- Venue filter (C-S2): drop
out-of-scope; flagneeds-reviewfor the dispatcher - Time filter (C-S1): drop anything outside the window
- Relevance filter (abstract-level): drop anything whose abstract clearly does not touch the parent topic. Be permissive at this stage; better to read one extra PDF than to miss a relevant paper
- Deduplication: a paper that appears in both arXiv form and conference form is one entry, keyed by the conference DBLP key; merge
discovered_vialists - Exclude list: drop anything in the brief's
exclude_papers
Aim to come out of this step with ~15–25 papers that warrant a PDF read.
Step 4 — Fetch publication PDFs
For each surviving candidate:
- Try the publication URL first (conference proceedings page, journal page, publisher PDF)
- If paywalled / 403 / unavailable after a reasonable attempt → fall back to arXiv version, record
version: arxiv-fallbackand the reason - Save the PDF to
<project>/cache/papers/<stable-id>.pdf - If both publication and arXiv fail → drop from this sweep, log in candidates file as
dropped_for_unavailable
cache/papers/ is the same cache that research-workflow C4 uses. PDFs landed here become available for subsequent single-paper Workflow E intake.
Step 5 — Code repository hunt
For each paper whose PDF landed:
- Paper-side search: open the PDF, search for
github.com,gitlab.com, "Code available", "Implementation", footnotes on page 1, the abstract page, and the appendix. Capture the URL. - Author-side search: if not found, look up the first author and last author on GitHub (try
github.com/<lastname>, then a GitHub user search). Scan their repos for one matching the paper title or method name. - Topic-side search: if still not found, search GitHub for
<method-name>and 2–3 distinctive keywords from the paper. If only third-party reimplementations exist, record one and markcode: third-party-only. - Verification: open the candidate repo's README. Confirm it cites this paper or implements its method (don't just match on name). Record the verification.
Outcomes:
code: <url>(verified official) — recordcode_status: official-verifiedcode: <url>(third-party only) — recordcode_status: third-party-onlycode: not-found— record the fullsearch_trace(what was tried, what was found)
Step 6 — Read and extract
For each paper, read at minimum: abstract, intro (especially the contributions list), method overview, experiments setup, conclusion. Extract the C-S5 content fields. Stick to descriptive language (C-S6).
Cross-reference with the parent proposal vocabulary (from Step 1) so relation_to_parent and differences are anchored in the project's own terms, not the paper's.
Step 7 — Write the survey file
Write to <project>/survey/<slug>.md using templates/subtopic-survey.md.template.
Structure:
- YAML frontmatter with sweep metadata (slug, time window, venue whitelist used, brief path, worker session id if available, total papers in survey, count of
code: not-found) - Summary table listing all papers with the essential columns (title, venue/year, code link or
not-found, salience_axes, verified_by) - Per-paper sections with the full C-S5 fields
- Coverage notes (optional): brief paragraph on which sub-axes are well covered and which are sparse. Factual, not evaluative.
- Dropped candidates appendix: short list of
needs-reviewvenue cases anddropped_for_unavailablepapers, so the dispatcher can decide next steps
Step 8 — Log the sweep
Write a log entry to <project>/log/entries/<ts>_survey-sweep_<slug>.md using templates/log-entry-survey-sweep.md.template. Type is survey-sweep (new log type, must be added to research-workflow SKILL.md's log type vocabulary — see research-workflow Section 5).
Summary should state: N papers in survey, M with code: not-found, K flagged needs-review for venue.
Step 9 — Final message to dispatcher
The worker's final message to the dispatcher (the main agent or routine controller) is short and structured:
- Path to
survey/<slug>.md - Path to
survey/<slug>.candidates.md - Path to the log entry
- Counts: total papers, code not-found, venue needs-review
- Any papers requiring
verified_byvalidation before being merged into the project-rootsurvey.mdvia Workflow E
The dispatcher (not the worker) decides when and how to merge sub-topic surveys into the project-root survey.md.
Section 4 — Output Format
The detailed format lives in templates/subtopic-survey.md.template. Highlights:
- YAML frontmatter carries machine-readable sweep metadata so a downstream merge script can verify counts and constraints
- Each paper has both a row in the summary table and a section below with full fields — the table is for scanning, the sections are for analysis
- Every entry has
verified_by: cache/papers/<stable-id>.pdf— same convention as research-workflow C4, so Workflow E can promote entries to the rootsurvey.mdwithout re-verification - No subjective fields anywhere in the schema — there is no "importance score", "collision likelihood", or "recommended reading order" column
Section 5 — Dispatch Mode
The same brief and worker behavior are designed for in-session Codex sub-agents.
The main agent, during a research-workflow session, hands off a sub-topic sweep:
- Main agent drafts
<project>/survey/<slug>.brief.md(using the template; main agent has full context to fill it well) - Main agent spawns a Codex sub-agent with this prompt:
"You are a research-survey worker. Read
~/.codex/skills/research-survey/SKILL.mdfor the protocol. Your brief is at<absolute-path>/survey/<slug>.brief.md. Execute Section 3 end-to-end and return the Section 3 Step 9 final message." - Multiple sweeps in parallel → one message with multiple Codex sub-agent tool calls
- Worker returns the structured final message; main agent reads
survey/<slug>.mdand decides on Workflow E promotions
Sub-agent vs main agent capability differences (operational facts the dispatcher must know)
- Sub-agent cannot call
ask the user. The brief must be complete; if it's not, the worker returns a failure receipt. - Sub-agent cannot launch its own sub-agents. It does PDF fetch and code search serially. Don't make sweeps too large.
- Sub-agent has fresh context. It does not see the conversation, MEMORY.md, or any prior decisions. Everything it needs must be in the brief or reachable from disk via the brief.
- Parallel sweeps don't share state. Two workers on adjacent sub-topics will likely re-discover the same paper. Dedup at the dispatcher level using stable IDs after both return.
Section 6 — Anti-patterns
| Anti-pattern | Symptom | Correction |
|---|---|---|
| Abstract-only entries | Entry exists in survey/<slug>.md but PDF was never fetched |
Reject. PDF must be in cache/papers/ with verified_by set. Apply C-S3 + research-workflow C4. |
| Silent venue inclusion | A workshop / non-CCF-A paper appears in the survey without justification | Reject. Apply C-S2 — either it matches accepted_venues or it goes to needs-review, not into the survey. |
code: not-found without trace |
Code field marked missing but no search_trace recorded |
Reject. Apply C-S4 — three-step search is mandatory; the trace proves the search happened. |
| arXiv-by-default | Worker grabs arXiv URL without trying the publication version | Apply C-S3 — try publication first, record the attempt; arXiv is a fallback, not a default. |
| Value judgments leaking in | Entries use "SOTA", "seminal", "likely competitor", "weak baseline" | Strip. Apply C-S6 — describe, don't evaluate. The analyst evaluates. |
| Rolling time window | Sweep done in month 10 uses a different "5 years" than sweep done in month 1 of the same project | Apply Section 1 — time_window_start is the project's creation date, fixed for the project's life. |
| Sub-agent guessing missing brief fields | Worker assumed defaults instead of returning a failure receipt | Reject. Apply Section 1 — if the brief is incomplete, fail loudly, don't paper over. |
| Mega-sweep | A single sub-topic has 40+ papers in the survey | Split the sub-topic into 2–3 narrower briefs. Workers don't read 40 PDFs well. |
| Re-discovering papers across parallel sweeps without dedup | The same paper appears in two sub-topic surveys with different what writeups |
Dedup at the dispatcher using stable IDs (DBLP > arXiv > DOI). Don't change the worker; fix the merge. |
| Drift between modes | A brief works in Mode A but not Mode B (or vice versa) because someone added a side-channel assumption | Keep the brief format identical. If a mode needs extra context, add it as an optional brief field, not as out-of-band knowledge. |
Section 7 — Integration with research-workflow
This skill depends on changes to research-workflow SKILL.md. Those changes are:
- New log type:
survey-sweepadded to Section 5's type vocabulary - New workflow: Workflow E' (Surveying a sub-topic) added to Section 3, with the entry condition "the request is a sub-area sweep, not a single-paper intake"
- Routing table: Section 6 gains a row "Surveying a sub-topic → research-survey"
- Directory layout: Section 2 gains the
survey/subdirectory under each project (sibling ofcache/,log/,doc/,src/).survey/is in git;cache/papers/already isn't. - Workflow E reference: Workflow E gains a one-line note: "If the user mentions a sub-area rather than a specific paper, route to research-survey first; Workflow E then promotes individual entries from
survey/<slug>.mdinto the project-rootsurvey.md."
Promotion path: when the project lead decides a sub-topic survey is ready to fold into the master related-work list, each row of survey/<slug>.md becomes a Workflow E call. The verified_by field is already there (same convention), so promotion is a copy, not a re-verification.
Notes for the agent
- This skill is meant to be readable and executable by an isolated worker. Keep procedures concrete; assume no prior conversation.
- The constitution rules (C-S1 ~ C-S6) are non-negotiable for survey entries. The workflow steps (Section 3) are the default procedure; minor adaptations are fine (e.g., a different discovery order for an unusual sub-area) but the constitution must hold.
- When in doubt about a venue, mark
needs-reviewand surface in the receipt. Do not silently include or exclude. - When in doubt about objectivity, ask: "would this sentence still be true if a hostile reviewer read it?" If the sentence is a judgment that depends on the reader's priors, rephrase as a fact.
- The dispatcher (main agent or controller), not the worker, decides when sub-topic surveys are promoted into the project-root
survey.md. The worker's job ends at Step 9.
04 同仓库更多 Skills
vibe-survey
Compatibility alias for research-survey. Use when the user says vibe-survey or asks for the old /vibe-survey behavior.
vibe-review
Compatibility alias for research-review. Use when the user says vibe-review or asks for the old /vibe-review behavior.
vibe-research
Compatibility alias for research-workflow. Use when the user says vibe-research or asks for the old /vibe-research behavior.
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 /report workflow. Codex defaults to data/backend validation and deployment; Claude defaults to HTML/front-end authoring.
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/project group, review or implement the protocol in protocol.md, coordinate Claude/Codex discussion, log consensus/debate/handoff outcomes, manage shared workspace write discipline, run independent cross-agent reviews, or start/inspect the optional full-auto worktree sandbox.
vibe-cowork
Compatibility alias for research-cowork. Use when the user says vibe-cowork or asks for the old /vibe-cowork behavior.