paper-analysis-report

name	paper-analysis-report
description	Use when running bibliometric analysis and report generation on processed data: topic modeling, mobility, cross-analysis, visualizations, and deep-report writing with figure-text consistency gates. Portable — no hardcoded paths. Keywords: analysis, BERTopic, mobility, Sankey, trends, reporting, 深度分析, 图文一致, 报告生成, 交叉分析.

Paper Analysis And Reporting Skill

Purpose

Run analytical modules on processed UT-keyed data and produce portable, reusable, and publication-grade report artifacts. This skill is not only about generating figures and tables; it also enforces a deep-analysis reporting standard so the final report does not degrade into chart description or appendix padding.

Package Contents

This skill package is complete only when the agent uses all of the following:

• SKILL.md
• checklists/report-quality-checklist.md
• references/deep-analysis-requirements.md
• references/figure-text-contract.md
• references/topic-hierarchy-policy.md
• scripts/report_quality_gate.py

If any of these are missing, the agent should state the gap and proceed with the closest fallback.

Portable Directory Convention

Inherits the same directory layout as paper-data-processing. Analysis scripts read from data/processed/ and write to reports/ and data/processed/.

{workspace}/
├── data/processed/        # ← Inputs: wos_cleaned.csv, paper_topics.csv, paper_authors.csv …
├── reports/
│   ├── figures/           # PNG + HTML visualizations
│   ├── tables/            # CSV data tables per chapter
│   ├── topic_visualizations/
│   └── *.md / *.docx      # Final report documents
├── models/
└── src/

All artifact paths must remain workspace-relative. Before running any analysis script, the agent MUST check for hardcoded absolute paths and patch them to workspace-relative paths.

Pre-flight Interactive Inquiry

Before the first script run, the agent MUST ask the user:

1. “您的项目根目录在哪里？” → set PROJECT_ROOT
2. “是否已有训练好的 BERTopic 模型？格式是什么？(safetensors/pkl/pytorch)”
   • 有 → set BERTOPIC_MODEL_PATH=<path>, skip training
   • 无 → train from scratch, save to models/bertopic_model/
3. “Embedding 模型用什么？”
   • EMBEDDING_MODEL=auto by default
   • or explicit HuggingFace/local model path
4. “本地 LLM 后端是 Ollama 还是 MLX？模型名称？”
   • Ollama → LLM_BACKEND=ollama
   • OpenAI-compatible / MLX → LLM_BACKEND=openai + LLM_URL
5. “本次输出目标是：数据底稿、正式长报告、汇报版摘要，还是全部？”
   • If the user wants a formal long report, the deep-analysis quality gates in this skill are mandatory.
   • The default formal long-report deliverable is a figure-integrated deep-analysis report in both Markdown and .docx.

All scripts derive paths from: ROOT = Path(os.environ.get("PROJECT_ROOT", Path(__file__).resolve().parent.parent))

For final report export, the agent should prefer:

• reports/{RESEARCH_TOPIC}_bibliometric_report.md
• reports/{RESEARCH_TOPIC}_bibliometric_report.docx

Avoid generic final filenames such as reports/bibliometric_report.md when the topic is known, because they increase the risk of stale-report reuse during cold-start execution.

Inputs

Artifact	Path	Producer
Enriched paper table	data/processed/wos_cleaned.csv	paper-data-processing
Paper-author pairs	data/processed/paper_authors.csv	paper-data-processing
Author summary	data/processed/authors_summary.csv	paper-data-processing
Paper topics	data/processed/paper_topics.csv	src/analyze_topics.py

Core Project Scripts

Script	Purpose	Key Outputs
src/analyze_topics.py	BERTopic topic modeling + topic naming	data/processed/paper_topics.csv, reports/topic_info_fine.csv, reports/topic_info_coarse.csv
src/analyze_mobility.py	Talent flow detection	data/processed/researcher_flows.csv, reports/flow_matrix.csv, reports/talent_flow_sankey.html
src/run_full_analysis.py	Core chapter figures/tables	reports/figures/fig_*.png, reports/tables/tab_*.csv
src/run_extended_analysis.py	Deep-dive chapter figures/tables	reports/figures/fig_*.png, reports/tables/tab_*.csv

Skill-Level Quality Gate Script

Before the final report is considered complete, run:

scripts/report_quality_gate.py --report reports/{RESEARCH_TOPIC}_bibliometric_report.md

This script is a portable structural validator. It checks:

• report image paths exist
• figure-heavy subsections that likely violate “one figure, one judgment”
• forbidden meta phrases / weak heading patterns
• basic chapter / appendix presence

The script does not replace human judgment, but it blocks obvious regressions.

Deep Analysis Standard

The default requirement is not “produce a report”, but “produce a report with structural judgment.” The agent MUST follow the requirements in references/deep-analysis-requirements.md. In practice this means:

1. Do not write descriptive ranking summaries as if they were conclusions.
2. Every important judgment must be tied to specific data points, comparisons, or figure evidence.
3. “平台型 / 桥接型 / 赛道型 / 区域分工 / 主题平台化” are not labels to invent freely; they must be demonstrated by metrics.
4. Do not use appendices to fake depth. A thicker appendix cannot compensate for a thin正文.
5. Mention real entities when making structural claims:
   • countries / regions
   • institutions
   • authors
   • topics
6. Prefer mechanism explanations over chart narration:
   • not only “what is high”
   • but “why this structure appears” and “what it changes”

Figure-Text Contract

The report MUST obey the rules in references/figure-text-contract.md:

• A core figure should usually have its own subsection.
• The subsection title must be a judgment, not a self-referential note.
• The figure should serve that judgment, not just decorate it.
• Avoid one paragraph explaining two or three unrelated figures.
• If a figure is auxiliary only, say so briefly and do not let it carry the main claim.

Topic Naming And Hierarchy Rules

The report MUST obey references/topic-hierarchy-policy.md:

• No secondary compression of LLM-generated topic names
• No mechanical truncation
• Complete labels are preferred over short-but-broken labels
• Topic hierarchy figures may be used as formal evidence only if hierarchy validity passes
• If hierarchy validity is weak, demote the figure to auxiliary status and do not build chapter conclusions on it

Recommended Execution Order

Stage 1: Validate Analysis Readiness

• Confirm wos_cleaned.csv exists and is readable
• Confirm UT integrity and topic joinability
• Confirm author artifacts exist if mobility / author chapters are requested

Stage 2: Run Analytical Modules

1. Topic modeling / topic refresh
2. Mobility analysis
3. Core chapter figure/table generation
4. Extended chapter figure/table generation

Stage 3: Draft The Long Report

The agent should create or update:

• reports/{RESEARCH_TOPIC}_bibliometric_report.md

The default long report should answer:

1. What changed over time?
2. Which regions gained scale, which retained network control, and which function as open nodes?
3. Which institutions act as platform centers, bridge nodes, and track specialists?
4. Which topics are wide platforms, strong method platforms, and high-constraint growth frontiers?
5. Which cooperation channels define the main knowledge corridors?
6. Which authors act as bridge migrants, deep specialists, and high-internationalization spreaders?

Stage 4: Run Skill Quality Gate

Run: scripts/report_quality_gate.py --report <markdown_report>

Then manually check the report with:

• checklists/report-quality-checklist.md

Stage 5: Export Final Deliverables

Produce:

• Markdown long report
• figure-integrated .docx long report

The .docx is not an optional decoration for deep-report mode. It should be treated as a formal deliverable when the user asks for a long report, deep analysis, white-paper style output, or figure-text integrated reporting.

Contract Outputs

Category	Key Files
Topic metadata	reports/topic_info_fine.csv, reports/topic_info_coarse.csv
Topic assignments	data/processed/paper_topics.csv
Mobility flows	reports/flow_matrix.csv, reports/talent_flow_sankey.html
Chapter figures	reports/figures/fig_*.png (+ .html)
Chapter tables	reports/tables/tab_*.csv
Final report	reports/{RESEARCH_TOPIC}_bibliometric_report.md, reports/{RESEARCH_TOPIC}_bibliometric_report.docx

Required Checks

• Every paper has topic linkage or explicit outlier topic id -1
• Fine and coarse topic ids are present where required
• Key visuals are generated without runtime errors
• Report tables preserve UT for cross-joins
• Topic names are complete enough for report use
• Figure paths referenced in the report are valid
• Core report sections pass the deep-analysis and figure-text contracts

Done Criteria

• Analysis scripts complete successfully
• Expected report files exist at workspace-relative paths and can be opened
• Cross-analysis tables are joinable by UT
• Final Markdown report exists and references valid figure paths
• Final .docx report exists and embeds the report figures needed for formal delivery
• scripts/report_quality_gate.py passes without blocking issues
• Manual checklist confirms the report is not merely descriptive