Research Literature Review

Positioning and Retrieval Dependencies

Objective: Complete the full review pipeline of "Retrieval → Deduplication → Scoring → Paper Selection → Writing → Verification → PDF/Word Export" within an isolated working directory.
Applicable: Users explicitly request systematic literature review, literature review, related work, literature research, and expect to get LaTeX + BibTeX + PDF/Word deliverables.
Not applicable: Only want to supplement a single reference, only want to polish existing text, only want to write a regular abstract or articles unrelated to reviews.
Highest principle: Complete the review with the best available evidence and writing quality; when uncertain, explain the processing method, and do not sacrifice credibility for progress.
```
research-literature-search
```
is a required dependency for Phase 1/2 (contract
```
rls.v1
```
). The review only consumes its manifest, canonical candidates and provenance, and no longer embeds providers or executes a second set of canonical deduplication.
The old name
```
systematic-literature-review
```
is retained only as a prompt compatibility alias;
```
.systematic-literature-review/
```
remains the stable historical workspace name.

Input

Minimum requirements:

```
{Topic}
```
: One-sentence topic.
Optional scope: Time, language, research type, database preference, etc.
Tier:
```
Premium
```
/
```
Standard
```
/
```
Basic
```
; if not specified, read the default value from
```
config.yaml
```
.
Target word count and reference range: If not specified, follow
```
config.yaml.scoring.default_*_range
```
.
Output directory or sanitized prefix: If not specified, use the sanitized topic name.
Query input: Before Phase 1, multi-query JSON conforming to the public schema must be provided; it is recommended to use
```
--query-file
```
, or fill in
```
input/queries.json
```
of the current run.

Process

Input

Provide necessary input according to user requests and configuration files; if information is missing, list it clearly and stop the steps that depend on this input.

Execution Steps

When a bug caused by the design flaw of this skill occurs in the user's environment, prioritize using
```
bensz-collect-bugs
```
to record it in
```
~/.bensz-skills/bugs/
```
according to specifications. It is strictly forbidden to directly modify the source code of the skill installed in the user's local Claude Code / Codex.
If the AI can still complete the user's task through a workaround, record the bug first, then continue to complete the current task.
When the user explicitly requests actions such as "report bensz skills bugs" for public reporting, call the local
```
gh
```
and
```
bensz-collect-bugs
```
, and only upload new 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

to generate query JSON. The public schema supports the following three forms:

{"queries": [{"query": "...", "rationale": "..."}]}

```
[{"query": "...", "rationale": "..."}]
```
```
["query 1", "query 2"]
```

After removing empty queries, the valid number must meet
```
config.yaml:query_input.min_queries/max_queries
```
(default 5–25).
When the working directory is known, directly save the file to
```
<work-dir>/input/queries.json
```
, or use
```
--query-file <path>
```
to let the runner copy the explicit input to this location. When the working directory has not been established, run
```
--prepare-only
```
first, fill in the printed
```
input/queries.json
```
, then continue with
```
--resume ... --resume-from 1
```
.

Prioritize reading the following before starting:

references/ai_query_generation_prompt.md

```
references/ai_scoring_prompt.md
```
```
references/expert-review-writing.md
```

references/review-tex-section-templates.md

Read
```
references/multilingual-guide.md
```
when translation is involved

Multi-Query Retrieval (Call research-literature-search)

Query source priority is fixed as: Explicit
```
--query-file
```
→
```
input/queries.json
```
of current run →
```
input/queries_{stem}.json
```
→
```
output/artifacts/queries_{stem}.json
```
→ the only historical compatible file in current run.
Stop and report conflicts when multiple candidates are automatically discovered; stop and give repair prompts when the file is found but the schema/quantity is invalid. Do not guess query paths across runs.
During the startup phase, first discover and verify
```
research-literature-search
```
(order:
```
--search-skill-root
```
→ in-project
```
skills/research-literature-search
```
→ environment variables → user Skill root directory); fail-closed if missing or contract incompatible, and give installation prompts.
Call the
```
run
```
entry of search to generate the manifest bundle; the review saves it as a read-only input package and records the manifest/candidate hash, contract version and source path.
```
search_mode/query_source/requested_query_count/accepted_query_count/fallback_reason
```
in Search Log is generated unidirectionally by the manifest; the AI does not manually write the number of providers, candidate quantity or deduplication conclusions.
Single query is only used as an explicit fallback: pass
```
--allow-single-query-fallback
```
, and use
```
--fallback-reason
```
to specify the reason; the log must mark
```
search_mode=single_query
```
and a prominent warning.

Deduplication (Contract Verification, No Repeated Deduplication)

Verify manifest, artifact hash,
```
rls.paper.v1
```
and
```
candidates_deduped.jsonl
```
; retain the
```
2_dedupe
```
checkpoint name for resume compatibility.
New runs must not re-execute the old
```
dedupe_papers.py
```
or change the canonical order; old files/old checkpoints are only read through explicit legacy adapters and marked
```
legacy_adapted
```
.
All subsequent processes only read the canonical candidate set of the search bundle.

AI Scoring and Data Extraction

The AI reads the title and abstract of each paper according to
```
references/ai_scoring_prompt.md
```
and outputs
```
scored_papers.jsonl
```
.

Each entry must include at least:

score

subtopic

rationale

alignment

extraction

The scoring range is fixed at 1-10 points; only papers with a score >=5 are assigned subtopics to avoid weak-related papers polluting subtopic planning.
Self-check whether the distribution is healthy: about 20-40% high scores, 40-60% medium scores, 10-30% low scores.

Paper Selection and Bib Generation

```
select_references.py
```
selects the final set according to the target reference range and high-score priority ratio.

Generate

selected_papers.jsonl

references.bib

selection_rationale.yaml

Bib cleaning must retain: case-insensitive deduplicated keys, LaTeX special character escaping, missing field warnings.
Entries with missing or too short abstracts are marked
```
do_not_cite
```
, and prompt the risk of abstract coverage in the report.

Subtopic and Quota Planning

The AI plans 3-7 subtopics based on the scoring results and provides paragraph quotas.
Default approach: Introduction is about 1.5k words, discussion/prospects are about 1k words each, conclusion is about 0.6k words, and the rest are 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 summarize into
```
word_budget_final.csv
```
.
Both quoted and non-quoted paragraph budgets must be covered; the total word count error must be controlled within
```
config.yaml.word_budget.tolerance
```
.

Writing

Fixed sections of the main text: Abstract, Introduction, Subtopic Paragraphs, Discussion, Prospects, Conclusion.
Read
```
word_budget_final.csv
```
before writing, and organize evidence according to the literature review budget.
Single-paper citation priority is adopted by default; citations must follow the viewpoints they support, and avoid stacking at the end of paragraphs.

For detailed writing specifications, directly follow:

```
references/expert-review-writing.md
```

references/review-tex-section-templates.md

Organic Expansion and Verification

If the word count is insufficient, only allow incremental expansion in the shortest or evidence-insufficient subtopic paragraphs, do not add new subtopics, and do not modify original claims and citations.

Run in sequence:

```
validate_counts.py
```
```
validate_review_tex.py
```
Optional
```
validate_word_budget.py
```
```
generate_validation_report.py
```

Export and Multi-Language

Generate PDF via
```
compile_latex_with_bibtex.py
```
.
Generate Word via
```
convert_latex_to_word.py
```
.
If the user requests multi-language versions, use
```
multi_language.py
```
to translate the main text and compile intelligently; if it fails, retain the error report and broken files, and prioritize supporting backup recovery.

bash

# 查询文件已准备好：推荐主入口
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 phase to continue execution, and will not bypass the existing

pipeline_state.json

. When the state file is damaged, back up or repair it first, and prohibit overwriting historical checkpoints with 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

Verification:

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 tokens:
```
pipeline_cost.py log ...
```
Summary:
```
pipeline_cost.py summary
```
All cost data is written to 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

The following core files are published by default (copied when specifying the official directory via

--publish-dir

```
{Topic}_review.pdf
```
```
{Topic}_review.docx
```

Optional supporting files (published using

--include-supporting

) include

{Topic}_Working_Conditions.md

{Topic}_review.tex

{Topic}_References.bib

and

{Topic}_Verification_Report.md

. Word count budgets, candidate papers, scores, paper selections, abstract supplements and evidence cards are always internal intermediate products and do not enter the official publication directory.

Necessary intermediate products include:

```
papers*.jsonl
```
```
scored_papers.jsonl
```
```
selected_papers.jsonl
```
```
selection_rationale.yaml
```
Optional
```
evidence_cards_{Topic}.jsonl
```

Output Management

Intermediate files of new tasks for this Skill are uniformly written to

./.bensz-api/task-{yyyymmdd-hhmm}-{short-description}/{skill-name}/input|output|log/

. The same task reuses a single task root directory;

shared/

is created only for multi-Skill collaboration. Official deliverables are not written to this directory, and historical hidden directories only allow explicit compatible reading, migration or cleaning.

By default,

run_pipeline.py

places the running directory in

.bensz-api/task-{yyyymmdd-hhmm}-{short-description}/research-literature-review/<run-id>/

; query input is located in

input/

, and internal state and products are located under

output/

artifacts/

reference/

cache/

scripts/

deliverables/

(supporting files are separately located in

deliverables/supporting/

The official delivery directory must be explicitly specified via
```
--publish-dir
```
, and only accepts PDF/Word (or supporting files explicitly enabled). Do not use the official directory as
```
--work-dir
```
.
AI temporary scripts must be placed in internal
```
output/scripts/
```
; do not write temporary files to the root of the running directory, do not use absolute paths to write
```
/tmp/*
```
, and do not read or write other run directories.

Follow the environment variables

SYSTEMATIC_LITERATURE_REVIEW_SCOPE_ROOT

and

SYSTEMATIC_LITERATURE_REVIEW_SCRIPTS_DIR

The search bundle is located in
```
output/artifacts/search_bundle_{stem}/
```
of the current review run; the review reads only the relative path pointed to by its manifest in read-only mode; do not guess across runs or directly trust external absolute artifact paths.

Verification

After completion, perform the existing static checks, script verification or manual review of the Skill, and record the passing standards.

Failure and Recovery

Retain error evidence and completed products; only retry from the nearest failed step after input, environment or external dependencies are restored.

Constraints

Mandatory export of PDF and Word; missing is only allowed when explicitly failed and the reason is recorded.
The number of main text words and references must fall within the current tier range; it can be overwritten by the user, and the default value is based on
```
config.yaml
```
.
The main text must include: Abstract, Introduction, at least 1 subtopic paragraph, Discussion, Prospects, Conclusion.
```
\cite{key}
```
must be consistent with the BibTeX key; an error is reported if missing.
The main text is prohibited from disclosing the AI workflow; for example, meta-narratives such as "retrieval/deduplication/scoring/paper selection/word count budgeting" can only be written into
```
{Topic}_Working_Conditions.md
```
.
The abstract must be a single paragraph, avoiding methodological flowcharts; table width and style constraints are specified in
```
references/review-tex-section-templates.md
```
.
Do not stack low-score papers to meet citation requirements; when unsure, prioritize not modifying or citing.
When multi-query JSON is missing, conflicting, unparseable, or the number of valid queries is less than the configuration lower limit or exceeds the upper limit, Phase 1 must fail-closed; do not pretend to complete multi-query with a successful exit code.
Only when the caller explicitly passes
```
--allow-single-query-fallback
```
is single query allowed to be executed once, and the mode, source, reason and warning are recorded in the state and Search Log.

Common Hard Constraints

When the task needs to be persisted to disk, use a unique
```
./.bensz-api/task-{yyyymmdd-hhmm}-{short-description}/
```
root directory; shared materials are placed in
```
shared/
```
, and Skill-specific materials are placed in the Skill's
```
input/
```
,
```
output/
```
,
```
log/
```
.
Official deliverables, source code and official plans are saved according to project agreements, and are not written to the task workspace; do not overwrite, delete, migrate or remotely write without authorization.
Project maintenance changes check BAC availability and record requirements, AI output, tool results, file changes and verification summaries; BAC only performs process audits and does not replace signature, 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-volume raw data.
File paths must be normalized and restricted within authorized project scopes; external URLs, subprocesses and network access follow the principle of least privilege to prevent path traversal, SSRF and command injection.
Skill version is uniquely recorded in its own
```
config.yaml:skill_info.version
```
; public API, protocol, directory or configuration changes are synchronized with documents and
```
CHANGELOG.md
```
.
Only design defects of the Skill or Bensz infrastructure itself are submitted to
```
bensz-collect-bugs
```
; first desensitize and write to
```
~/.bensz-skills/bugs/
```
, do not interrupt the current task, and only report publicly when the user explicitly requests it. It is strictly forbidden to directly modify the source code of the Skill installed by the user.

Skill-Specific Constraints

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

research-literature-review

NPX Install

Tags

SKILL.md Content (Chinese)

Research Literature Review

Positioning and Retrieval Dependencies

Input

Process

Input

Execution Steps

Preparation

Multi-Query Retrieval (Call research-literature-search)

Deduplication (Contract Verification, No Repeated Deduplication)

AI Scoring and Data Extraction

Paper Selection and Bib Generation

Subtopic and Quota Planning

Word Count Budget

Writing

Organic Expansion and Verification

Export and Multi-Language

Output

Output Management

Verification

Failure and Recovery

Constraints

Common Hard Constraints

Skill-Specific Constraints