SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsresearch-literature-review

research-literature-review

Writing & research

View repository

Updated 10-15 22:14

About this skill

Research Literature Review

Goal

  • Goal: Complete the full review pipeline of "retrieval → deduplication → scoring → paper selection → writing → validation → PDF/Word export" within an isolated working directory.
  • Applicable: The user explicitly wants a systematic review, literature review, related work, or literature survey, and expects LaTeX + BibTeX + PDF/Word deliverables.
  • Not applicable: Only wants to add a single reference, only wants to polish existing text, only wants to write an ordinary abstract, or wants an article unrelated to a review.
  • Highest principle: Complete the review using the best available evidence and writing quality; when uncertain, explain how it was handled, and do not sacrifice credibility to save time.
  • research-literature-search is a required dependency for phases 1/2 (contract rls.v1). review only consumes its manifest, canonical candidates, and provenance; it no longer embeds a provider or executes a second set of canonical deduplication.
  • Legacy name systematic-literature-review is retained only as a prompt compatibility alias;.systematic-literature-review/ remains the stable historical workspace name.

Input Overview

At minimum, the following are required:

  1. {主题}: A one-sentence topic.
  2. Optional scope: time, language, study type, database preference, etc.
  3. Tier:Premium / Standard / Basic; if unspecified, read the config.yaml default value.
  4. Target word count and reference range: if unspecified, follow config.yaml.scoring.default_*_range。
  5. Output directory or sanitized prefix: if unspecified, use the sanitized topic name.
  6. Query input: Before phase 1, a multi-query JSON conforming to the public schema must be provided; recommended to use --query-file, or fill in the current run's input/queries.json。

Process

Input

Provide the necessary inputs according to the user request and configuration file; missing information should be clearly listed and steps depending on that input should stop.

Execution Steps

  • When bugs caused by design flaws in this skill appear in the user's environment, preferentially use bensz-collect-bugs to record them according to the specification in ~/.bensz-skills/bugs/; it is strictly forbidden to directly modify the installed skill source code in the user's local Claude Code / Codex.
  • If the AI can still continue completing the user's task through a workaround, it should first record the bug, then continue completing the current task.
  • When the user explicitly requests public reporting actions such as "report bensz skills bugs," call the local gh and bensz-collect-bugs, and upload only newly added bugs to huangwb8/bensz-bugs; do not pull / clone the entire bug repository.

Preparation

  • Record the topic, tier, word count/reference range, and output directory.
  • First read references/ai_query_generation_prompt.md, and generate the query JSON. The public schema supports the following three forms:
    • {"queries": [{"query": "...", "rationale": "..."}]}
    • [{"query": "...", "rationale": "..."}]
    • ["query 1", "query 2"]
  • After removing empty queries, the effective count must satisfy config.yaml:query_input.min_queries/max_queries(default 5–25).
  • When the working directory is known, save the file directly to <work-dir>/input/queries.json, or use --query-file <path> to have the runner copy the explicit input to that location. When the working directory has not yet been established, first run --prepare-only, fill in the printed input/queries.json, then continue with --resume ... --resume-from 1 .
  • Before starting, preferentially read:
    • references/ai_query_generation_prompt.md
    • references/ai_scoring_prompt.md
    • references/expert-review-writing.md
    • references/review-tex-section-templates.md
    • If translation is involved, also read references/multilingual-guide.md

Multi-query retrieval (calls research-literature-search)

  • The query source priority is fixed as: explicit --query-file → the current run's input/queries.json → input/queries_{stem}.json → output/artifacts/queries_{stem}.json → the unique historically compatible file within the current run.
  • When multiple candidates are automatically discovered, stop and report the conflict; when a file is discovered but the schema/count is invalid, stop and provide a repair hint. Do not guess query paths across runs.
  • During startup, first discover and validate research-literature-search(order:--search-skill-root → in-project skills/research-literature-search → environment variable → user Skill root directory); if missing or the contract is incompatible, fail-closed and provide an installation hint.
  • Call search's run entry point to generate the manifest bundle; review saves it as a read-only input package and records the manifest/candidate hash, contract version, and source path.
  • The Search Log's search_mode/query_source/requested_query_count/accepted_query_count/fallback_reason is generated unidirectionally from the manifest; the AI does not hand-write provider counts, candidate counts, or deduplication conclusions.
  • A single query serves only as an explicit fallback: pass --allow-single-query-fallback, and optionally use --fallback-reason to state the reason; the log must mark search_mode=single_query and a prominent warning.

Deduplication (contract validation, no repeated deduplication)

  • Validate the manifest, artifact hash,rls.paper.v1 and candidates_deduped.jsonl; retain the 2_dedupe checkpoint name for resume compatibility.
  • A new run must not execute the old dedupe_papers.py again or change the canonical order; old files/old checkpoints are read only through an explicit legacy adapter and marked legacy_adapted。
  • All subsequent processes read only the canonical candidate set of the search bundle.

AI scoring and data extraction

  • The AI reads titles and abstracts one by one according to references/ai_scoring_prompt.md and outputs scored_papers.jsonl。
  • Each entry contains at least:score、subtopic、rationale、alignment、extraction。
  • The scoring range is fixed at 1-10 points; subtopics are assigned only to documents with >=5 points, to avoid weakly relevant papers polluting subtopic planning.
  • Self-check whether the distribution is healthy: high scores about 20-40%, medium scores 40-60%, low scores 10-30%.

Paper selection and Bib generation

  • select_references.py Select the final set according to minimum relevance, evidence role, and soft budget;target_refs is the budget target,max_refs is the upper limit, and low-scoring or abstract-less entries are no longer used to fill the old min_refs。
  • Generate selected_papers.jsonl、references.bib、selection_rationale.yaml。
  • Bib cleaning must preserve: case-insensitive deduplication keys, LaTeX special character escaping, and missing-field warnings.
  • Evidence roles use direct-neighbor、supporting、methodological、contradictory、boundary; direct close neighbors and counter-evidence take priority over broad methodological similarity.
  • A standard review includes in the formal citation set only entries that have an abstract and meet the relevance threshold. When there are fewer qualifying papers than the soft target, deliver a smaller set as usual, and write the stopping reason and evidence gaps in the rationale.

Novelty check

When the purpose of the call is --purpose novelty-check , run only through stage 4, and output strong close neighbors, counter/boundary evidence, unconfirmed items, and evidence depth, without automatically generating long-form main text, PDF, or Word. Only title-only direct close neighbors may be retained as records to be upgraded and marked do_not_cite; preprints and formally published papers use the same relevance scale, with publication status listed separately.

Subtopic and quota planning

  • The AI plans 3-7 subtopics based on the scoring results and provides paragraph quotas.
  • Default approach: introduction about 1.5k, discussion/outlook about 1k each, conclusion about 0.6k, and the rest allocated to subtopic paragraphs.
  • The results are written into the working conditions and data extraction table as writing anchors.

Word count budget

  • Use plan_word_budget.py to generate 3 budget CSVs, then merge them into word_budget_final.csv。
  • Both cited and uncited section budgets must be covered; the total word count error must be kept within config.yaml.word_budget.tolerance .

Writing

  • The main text sections are fixed as: abstract, introduction, subtopic paragraphs, discussion, outlook, conclusion.
  • Before writing, read word_budget_final.csv, and organize evidence according to the literature review budget.
  • By default, single-source citations are preferred; citations must closely follow the point they support and avoid piling up at the end of a paragraph.
  • If detailed writing specifications are needed, follow directly:
    • references/expert-review-writing.md
    • references/review-tex-section-templates.md

Organic expansion and verification

  • If the word count is insufficient, incremental expansion is only allowed within the shortest or evidence-insufficient subtopic paragraphs; do not add new subtopics and do not change the original claims or citations.
  • Run in sequence:
    • validate_counts.py
    • validate_review_tex.py
    • Optional validate_word_budget.py
    • generate_validation_report.py

Export and multilingual

  • Generate PDF via compile_latex_with_bibtex.py .
  • Generate Word via convert_latex_to_word.py .
  • If the user requests multilingual versions, use multi_language.py to translate the main text and intelligently compile; on failure, keep the error report and broken files, and prioritize support for restoring backups.
# 查询文件已准备好：推荐主入口
python3 scripts/run_pipeline.py --topic "{主题}" --query-file ./queries.json --publish-dir ./review-deliverables

# 两步式：先生成模板，再填充 input/queries.json 并恢复阶段 1
python3 scripts/pipeline_runner.py --topic "{主题}" --work-dir <work-dir> --prepare-only
python3 scripts/pipeline_runner.py --resume <work-dir> --resume-from 1 --publish-dir ./review-deliverables

# 临时兼容外部编排器：显式、可审计的单查询后备
python3 scripts/run_pipeline.py --topic "{主题}" --allow-single-query-fallback --fallback-reason "外部编排器暂未提供查询文件"

# 旧入口 / resume
python3 scripts/pipeline_runner.py --topic "{主题}" --domain general --query-file ./queries.json --publish-dir ./review-deliverables

# 显式指定 search Skill（独立安装环境）
python3 scripts/pipeline_runner.py --topic "{主题}" --query-file ./queries.json \
  --search-skill-root /path/to/research-literature-search
python3 scripts/pipeline_runner.py --resume .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/research-literature-review/{run-id} --publish-dir ./review-deliverables

# 阶段 3 评分后，从第 4 阶段继续
python3 scripts/pipeline_runner.py --resume .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/research-literature-review/{run-id} --resume-from 4

--resume-from only determines the stage to continue execution and will not bypass existing pipeline_state.json. If the state file is corrupted, back it up or repair it first; it is forbidden to overwrite historical checkpoints with an empty state.

  • Runtime environment: Python 3.9+, LaTeX (xelatex/bibtex）、pandoc。

  • Key scripts:

    • Retrieval:multi_query_search.py、openalex_search.py
    • Deduplication:dedupe_papers.py
    • Paper selection:select_references.py、build_reference_bib_from_papers.py
    • Data extraction:update_working_conditions_data_extraction.py
    • Word count budget:plan_word_budget.py、validate_word_budget.py
    • Validation:validate_counts.py、validate_review_tex.py、generate_validation_report.py
    • Export:compile_latex_with_bibtex.py、convert_latex_to_word.py

  • Initialization:python3 research-literature-review/scripts/pipeline_cost.py init

  • Fetch pricing:python3 research-literature-review/scripts/pipeline_cost.py fetch-prices

  • Record token:pipeline_cost.py log ...

  • Summary:pipeline_cost.py summary

  • All cost data is written to the internal output/cost/(old runs can still explicitly use the legacy directory).

  • references/ai_query_generation_prompt.md

  • references/ai_scoring_prompt.md

  • references/expert-review-writing.md

  • references/review-tex-section-templates.md

  • references/multilingual-guide.md

  • references/development-validation-guide.md

Output

By default, publish the following core files (copied when the official directory is specified via --publish-dir ):

  • {主题}_review.pdf
  • {主题}_review.docx

Optional supporting files (published using --include-supporting ) include {主题}_工作条件.md、{主题}_review.tex、{主题}_参考文献.bib and {主题}_验证报告.md. Word count budgets, candidate literature, scores, selected papers, abstract completion, and evidence cards always belong to internal intermediate artifacts and do not enter the official publication directory.

Necessary intermediate artifacts include:

  • papers*.jsonl
  • scored_papers.jsonl
  • selected_papers.jsonl
  • selection_rationale.yaml
  • Optional evidence_cards_{主题}.jsonl

Output management

For this Skill, new task intermediate files are uniformly written to ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/{skill名}/input|output|log/. The same task reuses one task root directory; only multi-Skill collaboration creates shared/. Official deliverables are not written to this directory; historical hidden directories are only allowed to be explicitly read for compatibility, migrated, or cleaned up.

  • By default, run_pipeline.py places the run directory under .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/research-literature-review/<run-id>/; query input is located in input/, and internal state and artifacts are located under output/ in artifacts/、reference/、cache/、scripts/、deliverables/(supporting files are located separately in deliverables/supporting/）。
  • The official delivery directory must be explicitly specified via --publish-dir , and only accepts PDF/Word (or explicitly enabled supporting files). Do not use the official directory as --work-dir。
  • AI temporary scripts must be placed in the internal output/scripts/; do not write temporary files to the root of the run directory, do not use absolute paths to write /tmp/*, and do not read or write other run directories.
  • Use environment variables SYSTEMATIC_LITERATURE_REVIEW_SCOPE_ROOT and SYSTEMATIC_LITERATURE_REVIEW_SCRIPTS_DIR as the standard.
  • The search bundle is located in the current review run's output/artifacts/search_bundle_{stem}/. The review only consumes the relative paths pointed to by its manifest in a read-only manner; it must not guess across runs or directly trust external absolute artifact paths.

Validation

After completion, execute the Skill's existing static checks, script validation, or manual review, and record the pass criteria.

Failure and recovery

Preserve error evidence and completed artifacts; retry from the most recent failed step only after the input, environment, or external dependencies have recovered.

Constraints

  • Force export of PDF and Word; missing files are allowed only when there is a clear failure and the reason is recorded.
  • The main text word count and the number of references must fall within the current tier's range; this can be overridden by the user, and the default values are based on config.yaml .
  • The main text must contain: abstract, introduction, at least 1 subtopic paragraph, discussion, outlook, conclusion.
  • \cite{key} must match the BibTeX key; a missing match is an error.
  • The main text must not leak the AI workflow; for example, meta-narratives such as "search/deduplication/scoring/paper selection/word budget" may only be written into {主题}_工作条件.md。
  • The abstract must be a single paragraph, avoiding a methodological流水账; for table width and style constraints, see references/review-tex-section-templates.md。
  • Do not pile up low-scoring references just to pad citations; when unable to confirm, prefer not to change and not to cite.
  • When the multi-query JSON is missing, conflicting, unparsable, has fewer valid queries than the configured lower limit, or exceeds the upper limit, stage 1 must fail-closed; it must not disguise a successful exit code as completion of multi-query processing.
  • Only when the caller explicitly passes --allow-single-query-fallback is it allowed to execute a single query once, and record the mode, source, reason, and warning in the state and Search Log.

Common hard constraints

  • When the task needs to persist to disk, use the unique ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ root directory; shared materials go into shared/, and Skill-specific materials go into that Skill's input/、output/、log/。
  • Formal deliverables, source code, and formal plans are saved according to project conventions and are not written into the task workspace; without authorization, do not overwrite, delete, migrate, or write remotely.
  • Project maintenance changes check BAC availability and record requirements, AI outputs, tool results, file changes, and validation summaries; BAC is only for process auditing and does not replace attribution, responsibility, or compliance judgments.
  • Do not record API keys, access tokens, passwords, cookies, environment/credential files, private prompts, identity information, local usernames, hostnames, or unnecessary large raw data.
  • File paths must be normalized and restricted to the authorized project scope; external URLs, subprocesses, and network access follow least privilege to prevent path traversal, SSRF, and command injection.
  • The Skill version is uniquely recorded in its own config.yaml:skill_info.version; public API, protocol, directory, or configuration changes are synchronized with the documentation and CHANGELOG.md。
  • Only design defects in the Skill or Bensz infrastructure itself are handed to bensz-collect-bugs; first write a redacted version into ~/.bensz-skills/bugs/. The current task is not interrupted; public reporting is only done when the user explicitly requests it, and directly modifying the user's installed Skill source code is prohibited.

Skill-specific constraints

Must not exceed the scope declared in this Skill description and the process above; do not disguise unverified information as definite conclusions.