paper-processing-analysis-handoff

name	paper-processing-analysis-handoff
description	Use when handing off bibliometric data from preprocessing to analysis: validate processed artifacts, decide rerun scope, and start topic/mobility/report workflows only when the processing contract passes. Portable — no hardcoded paths. Keywords: handoff, processing to analysis, stage gate, rerun, analysis-ready, UT contract, 处理到分析衔接, 阶段门, 分析就绪, 交接验证.

Paper Processing To Analysis Handoff Skill

Purpose

Bridge preprocessing outputs into analysis inputs with explicit gate checks, rerun rules, and a clear analysis-ready decision. Fully portable — all artifact references use workspace-relative paths.

Scope

• In scope:
  • Validate whether processed artifacts are sufficient for the requested analysis path.
  • Decide the smallest safe rerun scope before analysis starts.
  • Sequence topic, mobility, chapter-analysis, and report-generation steps.
  • Produce a handoff decision with blocking issues, risks, and next actions.
  • Enforce portability: patch any script with hardcoded paths before execution.
• Out of scope:
  • Rebuilding raw-data preprocessing logic from scratch (delegate to paper-data-processing).
  • Interpreting final scientific conclusions from charts or tables.
  • Full pipeline orchestration (delegate to paper-workflow-orchestrator).

Portable Directory Convention

All artifact paths below are workspace-relative. The same paths work on any machine.

Artifact	Workspace-relative path	Producer
Enriched paper table	data/processed/wos_cleaned.csv	processing Stage B
Topic assignments	data/processed/paper_topics.csv	src/analyze_topics.py
Topic metadata (fine)	reports/topic_info_fine.csv	src/analyze_topics.py
Topic metadata (coarse)	reports/topic_info_coarse.csv	src/analyze_topics.py
Paper-author pairs	data/processed/paper_authors.csv	processing Stage C
Author summary	data/processed/authors_summary.csv	processing Stage C
Researcher flows	data/processed/researcher_flows.csv	src/analyze_mobility.py
Chapter figures	reports/figures/fig_*.png	chapter analysis scripts
Chapter tables	reports/tables/tab_*.csv	chapter analysis scripts
Final report	reports/{RESEARCH_TOPIC}_bibliometric_report.md	report assembly

Relationship To Existing Skills

• paper-data-processing → generates upstream artifacts.
• This skill → validates the handoff contract and drives analysis execution.
• paper-analysis-report → defines what analysis produces.
• paper-workflow-orchestrator → calls this skill as the mandatory stage gate.

Full Workflow

Stage 0: Pre-flight Interactive Inquiry

Before anything else, ask the user:

1. “您的项目根目录在哪里？” — 设置 PROJECT_ROOT
2. “本地 LLM 后端是 Ollama 还是 MLX？模型名称？” — Ollama: LLM_BACKEND=ollama(default)；MLX: LLM_BACKEND=openai + LLM_URL

Then classify the request:

• topic-analysis
• mobility-analysis
• chapter-report-analysis
• full-analysis-package (includes final report generation by default)

If ambiguous, infer the smallest valid path.

Stage 1: Inventory Available Artifacts

Check which files already exist at their workspace-relative paths. Note whether each is present, missing, or obviously stale.

Stage 2: Validate Core Contract

Do not proceed until these pass:

• data/processed/wos_cleaned.csv exists and is readable.
• UT column is present, non-empty, and unique at paper level.
• Required baseline fields exist: UT, PY, TI, AB, country/region fields.

Stage 3: Validate Path-Specific Readiness

topic-analysis:

• TI and AB sufficiently populated.
• Topic outputs regenerated if missing or stale.

mobility-analysis:

• Country, institution, region fields present in data/processed/wos_cleaned.csv.
• Author artifacts present if mobility logic depends on author disambiguation.

chapter-report-analysis:

• data/processed/paper_topics.csv exists.
• reports/topic_info_coarse.csv exists.
• Joinable by UT.

full-analysis-package:

• All of the above.
• Report generation inputs present or producible by preceding stages.

Stage 4: Decide Rerun Scope

Pick the smallest rerun:

• data/processed/wos_cleaned.csv broken → rerun processing.
• Author outputs missing → rerun author extraction only.
• Topic artifacts missing → rerun src/analyze_topics.py only.
• Chapter/report artifacts missing → rerun chapter scripts + report assembly.
• Schema changed upstream → rerun all dependent downstream.

Stage 5: Enforce Portability

Before executing any script:

1. Read the script file.
2. Search for absolute paths (e.g. Path(r"E:/…"), Path(r"C:/…")).
3. If found, replace with workspace-relative derivation: ROOT = Path(__file__).resolve().parent.parent.
4. Confirm the patched script reads/writes to standard workspace directories.

Stage 6: Execute In Safe Order

1. Validate processed canonical table.
2. Run missing upstream extraction if required.
3. Run src/analyze_topics.py if topic artifacts needed.
4. Run src/analyze_mobility.py if mobility outputs needed.
5. Run src/run_full_analysis.py or src/run_extended_analysis.py for chapter outputs.
6. Assemble final report at reports/{RESEARCH_TOPIC}_bibliometric_report.md.
7. Run skills/paper-analysis-report/scripts/report_quality_gate.py --report reports/{RESEARCH_TOPIC}_bibliometric_report.md.
8. Verify report-ready outputs exist.

Stage 7: Verify Produced Outputs

After each stage, verify expected outputs exist before continuing.

Stage 8: Emit Handoff Result

Always finish with structured output:

requested-path: <path-type>
decision-status: analysis-ready | ready-with-risks | blocked-needs-processing-rerun | blocked-needs-schema-fix
checked-artifacts:
  - data/processed/wos_cleaned.csv
  - data/processed/paper_topics.csv
  - ...
gates-passed:
  - core-processed-table
  - topic-readiness
gates-failed:
  - none
rerun-scope: none | <specific stages>
next-step: <command or script>
residual-risks: <description>

Decision Logic

Branch A: Topic Analysis

Required: data/processed/wos_cleaned.csv with populated TI/AB, stable UT. Action: run src/analyze_topics.py, verify topic outputs.

Branch B: Mobility Analysis

Required: data/processed/wos_cleaned.csv with country/region fields, author artifacts if needed. Action: run src/analyze_mobility.py, verify flow tables.

Branch C: Chapter Report Analysis

Required: data/processed/wos_cleaned.csv + data/processed/paper_topics.csv + reports/topic_info_coarse.csv. Action: run topic analysis first if missing, then chapter scripts, then report assembly.

Branch D: Full Analysis Package

Required: all above. Action: validate all gates, run only missing stages, assemble final report, verify report outputs.

Required Gate Checks

Gate 1: Core Processed Table

data/processed/wos_cleaned.csv exists, readable, UT valid.

Gate 2: Analysis-Specific Fields

Path-dependent column checks as described in Stage 3.

Gate 3: Joinability

Cross-table UT joins succeed without unexpected duplication.

Gate 4: Downstream Artifact Readiness

Verify intermediate outputs before running dependent scripts.

Gate 5: Final Report Readiness

For full-analysis-package: final report and chapter artifacts verified, and the report quality gate passes without blocking issues.

Rerun Rules

• UT contract broken → rerun processing.
• Auxiliary processing outputs missing → rerun extraction stages.
• Topic artifacts missing → rerun topic analysis.
• Report artifacts missing → rerun chapter scripts + report assembly.
• Schema changed → rerun all dependent stages.

Failure Handling

• Stop at first blocking gate failure.
• Name the failing artifact and missing columns explicitly.
• Report root cause first when multiple gates fail.
• If the report quality gate fails, treat it as a blocking downstream failure, not as a cosmetic issue.

Completion Criteria

• Requested path mapped to concrete artifacts.
• All gates checked with explicit status.
• User gets runnable next step or precise blocker list.
• No analysis started if processing contract is broken.
• full-analysis-package requires verified final report.

Example Prompts

• 检查处理结果能不能进入主题分析，不行就告诉我该重跑哪一步。
• Run the full analysis package from processed data through final report.
• 帮我做处理到分析的交接检查，给出最小重跑方案。
• Validate handoff and execute only the missing downstream stages.
• 从 WoS 数据开始走完整流程，包括最终报告生成。