Lambenthan/empiricalwiki / i18n/en/skills/survey
survey
VerifiedGenerate a Related Work section for a paper from wiki knowledge — thematic grouping → narrative structure → LaTeX output, following citation-verification and academic-writing
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.4 KB |
SKILL.md
View on GitHub---
description: Generate a Related Work section for a paper from wiki knowledge — thematic grouping → narrative structure → LaTeX output, following citation-verification and academic-writing
argument-hint: <research-question-or-claim-slugs> [--format latex|markdown] [--max-papers 30]
---
# /survey
> Generate a Related Work section ready for direct use in a paper, based on existing wiki knowledge.
> Draw material from wiki/papers/, concepts/, topics/; group by research direction (not paper-by-paper listing).
> End each group with a statement of how it differs from this work. Citations follow citation-verification.md;
> writing follows academic-writing.md Related Work rules.
> Supports LaTeX and Markdown output formats.
## Inputs
- `query`: one of:
- research question description (free text, e.g. "parameter-efficient fine-tuning for LLMs")
- list of claim slugs (from wiki/claims/, used to organize related work around specific claims)
- path to PAPER_PLAN.md (extract Related Work section definition from it)
- `--format` (optional, default `latex`): output format
- `latex`: `\cite{key}` citations, embeddable directly in a paper
- `markdown`: `[[slug]]` wikilink citations, for wiki archiving
- `--max-papers` (optional, default 30): maximum number of papers to cite
## Outputs
- `wiki/outputs/related-work-{slug}-{date}.md` — Related Work text (archived)
- `wiki/graph/edges.jsonl` — derived_from edges (if a new output is created)
- `wiki/log.md` — appended log entry
- **Terminal output** — Related Work body text (for direct copy-paste)
## Wiki Interaction
### Reads
- `wiki/papers/*.md` — Problem, Key idea, Results, Related, My take
- `wiki/concepts/*.md` — Definition, Variants, Comparison, Known limitations
- `wiki/topics/*.md` — Overview, Timeline, Open problems, Seminal works
- `wiki/claims/*.md` — Statement, source_papers (if input is claim slugs)
- `wiki/ideas/*.md` — Motivation (understand this paper's positioning)
- `wiki/index.md` — content catalog, filtered by importance
- `wiki/graph/context_brief.md` — global context
- `wiki/graph/edges.jsonl` — inter-paper semantic relationships (same_problem_as, similar_method_to, complementary_to, builds_on, compares_against, improves_on, challenges, surveys)
- `.claude/skills/shared-references/academic-writing.md` — Related Work writing rules
- `.claude/skills/shared-references/citation-verification.md` — citation discipline
### Writes
- `wiki/outputs/related-work-{slug}-{date}.md` — archived file
- `wiki/graph/edges.jsonl` — derived_from edges
- `wiki/log.md` — appended operation log
### Graph edges created
- `derived_from`: related-work output → source papers
## Workflow
**Precondition**: confirm the working directory is the wiki project root (the directory containing `wiki/`, `raw/`, `tools/`).
### Step 1: Locate Relevant Knowledge
1. **Parse input**:
- If free text: extract keywords; match against tags and titles in wiki/index.md
- If claim slugs: read each claim's source_papers; collect related papers
- If PAPER_PLAN path: read the Related Work section's groupings and citations
2. **Read wiki/graph/context_brief.md** for global context
3. **Read wiki/graph/edges.jsonl**: extract inter-paper semantic relationships (same_problem_as, similar_method_to, complementary_to, builds_on, compares_against, improves_on, challenges, surveys)
4. **Build candidate paper list**:
- Sort by importance descending from index.md
- Rank by tags and domain match
- Cap at `--max-papers` papers
5. **If candidate papers < 5**: warn "insufficient related papers; consider /ingest of more papers first"
### Step 2: Deep-Read Related Pages
For each paper in the candidate list:
1. Read `wiki/papers/{slug}.md`: focus on Problem, Key idea, Results, My take
2. Read linked `wiki/concepts/*.md`: focus on Definition, Variants, Comparison
3. Read related `wiki/topics/*.md`: focus on Timeline, Open problems
Record for each paper:
- core contribution (one sentence)
- method category (which research direction it belongs to)
- relationship to this work (same problem / similar method / complementary / builds on / compares against / improves on / challenges / surveys)
- limitations (extracted from Limitations or My take)
### Step 3: Thematic Grouping
Following the Related Work rules in `shared-references/academic-writing.md`:
1. **Group by research direction** (not paper-by-paper listing):
- Extract natural groupings from wiki/topics/ and concepts/ classifications
- 3–8 papers per group
- Group headings describe research directions (e.g. "Parameter-Efficient Fine-Tuning"), not individual papers
2. **Determine group order**:
- Broad to specific (major direction → sub-direction → most related methods)
- Or chronological (foundational → development → recent)
3. **Determine within-group order**:
- Ascending by year (show progression)
- Important papers: 2–3 sentences; secondary papers: 1 sentence
4. **Annotate each group's relationship to this work**:
- End each group with one sentence: "Unlike these approaches, our method..." or "We build upon X by..."
### Step 4: Generate Paragraphs
Following `shared-references/academic-writing.md`:
1. **One or two paragraphs per group**:
- Opening: background and importance of the direction
- Body: expand on each paper's contribution in within-group order
- Closing: positioning relative to this work (required)
2. **Citation format**:
- `--format latex`: `\cite{key}`, key generated from citation-verification.md naming rules
- `--format markdown`: `[[slug]]`
3. **Writing standards**:
- No flat lists ("X did Y. Z did W.")
- Each paragraph has a topic sentence
- Use contrastive connectives ("While X focuses on..., Y addresses...")
- No AI-signature vocabulary (see de-AI list in academic-writing.md)
4. **De-AI polish**:
- Scan and replace AI-signature vocabulary
- Vary sentence openings
- Remove filler sentences
### Step 5: BibTeX Preparation (--format latex only)
If output format is LaTeX, following `shared-references/citation-verification.md`:
1. Collect all `\cite{key}` citations
2. For each key, attempt to fetch BibTeX: DBLP → CrossRef → S2
3. Verified: record BibTeX
4. Unverified: mark `[UNCONFIRMED]`
5. Output list of BibTeX entries (can be appended to paper/references.bib)
6. Report citation coverage
### Step 6: Archive
1. **Generate slug**:
```bash
python3 tools/research_wiki.py slug "<query-keywords>"
```
2. **Write archive file**:
Create `wiki/outputs/related-work-{slug}-{date}.md`:
```yaml
---
title: "Related Work: {topic}"
type: related-work
format: {latex|markdown}
paper_count: {N}
date_generated: YYYY-MM-DD
---
```
Body is the complete Related Work text.
If latex format: append BibTeX entries as an appendix.
3. **Add graph edges**:
```bash
# output → each cited paper
python3 tools/research_wiki.py add-edge wiki/ \
--from "outputs/related-work-{slug}-{date}" --to "papers/{paper-slug}" \
--type derived_from --evidence "Cited in related work section"
```
4. **Append log**:
```bash
python3 tools/research_wiki.py log wiki/ \
"survey | {topic} | {N} papers, {G} groups, format: {format}"
```
5. **Terminal output**: complete Related Work body text + citation coverage statistics
## Constraints
- **Only cite papers already in the wiki**: do not fabricate citations; every `\cite{}` or `[[slug]]` must correspond to a page in wiki/papers/
- **Group by theme, not as a flat list**: each paragraph covers a research direction, not "Paper A did X. Paper B did Y."
- **Every group must have a positioning sentence**: state the relationship to this work (at the end — difference or inheritance)
- **Warn when candidate papers < 5**: prompt user to /ingest more papers first
- **BibTeX follows citation-verification.md**: do not generate from LLM memory (--format latex only)
- **De-AI polish is mandatory**: a polish pass must be applied after generation
- **Archive to outputs/**: do not directly modify wiki papers/concepts/topics pages
- **Graph edges via tools/research_wiki.py**: do not manually edit edges.jsonl
## Error Handling
- **Fewer than 3 wiki papers**: error; suggest /ingest of enough papers first
- **No matching papers**: broaden search scope (relax tag matching); if still none, error
- **All BibTeX fetches failed** (latex format): use [UNCONFIRMED] placeholders; report count
- **PAPER_PLAN format mismatch**: ignore plan's grouping suggestions; use automatic grouping
- **Slug conflict**: append date suffix
## Dependencies
### Tools(via Bash)
- `python3 tools/research_wiki.py slug "<title>"` — generate slug
- `python3 tools/research_wiki.py add-edge wiki/ ...` — add graph edge
- `python3 tools/research_wiki.py log wiki/ "<message>"` — append log
- `python3 tools/fetch_s2.py search "<title>"` — BibTeX fallback (S2 search)
### MCP Servers
- None (survey does not require Review LLM; use /review --focus writing for separate review)
### Claude Code Native
- `Read` — read wiki pages
- `Glob` — find wiki pages
- `WebFetch` — DBLP / CrossRef BibTeX fetch (--format latex only)
### Shared References
- `.claude/skills/shared-references/academic-writing.md` — Related Work writing rules + de-AI polish
- `.claude/skills/shared-references/citation-verification.md` — BibTeX fetch and [UNCONFIRMED] protocol
### Called by
- `/paper-draft` Step 3 (Related Work section can be delegated to this skill)
- Manual user invocation
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |