Survey

---
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