paper-spine

name paper-spine description Build, rewrite, audit, submit, revise, or transfer scholarly papers end to end, producing verified LaTeX/PDF/Word and target-specific publication packages. PaperSpine Orchestrator Use this skill as the suite entrypoint. PaperSpine exposes one main skill: paper-spine . Each stage is executed by reading the corresponding playbook under references/ . Update detection : If the user asks to update, upgrade, check for updates, or configure automatic updates, read references/update.md and execute without starting intake or the writing workflow. Automatic updates are opt-in only. Command Routing Trigger Read Default / full workflow This file (Non-Negotiable Route below) resume / continue / "continue from" references/resume.md update / "check for updates" / 手动更新 references/update.md `auto-update on off submission / "submission materials" / delivery package references/publication-cycle.md , then references/submission.md audit references/audit.md translate references/translate.md humanize references/humanize.md respond / rebuttal / minor or major revision references/publication-cycle.md , then references/respond.md rejection / resubmit / journal transfer / 转投 references/publication-cycle.md , then references/journal-transfer.md Automatic Update Preflight Before every normal workflow launch or resume, follow references/update.md and run the installed updater with --auto . The preflight is a local no-op unless the user has explicitly enabled automatic updates and the configured interval is due. Never enable it on the user's behalf. If the preflight installs a new version, stop before intake/research/writing and ask the user to reload or restart the host, then invoke PaperSpine again. If the preflight fails, warn once and continue with the current installation; do not turn an update-network failure into a paper-workflow blocker. For fine-grained stage execution, the orchestrator reads the playbook for each stage from references/ rather than requiring a separate skill invocation: Stage Playbook Intake / config references/intake.md Resume / checkpoint references/resume.md Research references/research.md Citation references/citation.md Review policy / autonomy references/review-policy.md Editorial completeness / manuscript scale references/editorial-completeness.md Semantic confirmation references/semantic-confirmation.md Contribution contract references/contribution.md Rewrite references/rewrite.md Build references/build.md Results validation references/results-validation.md Scientific evidence ledger references/scientific-evidence-ledger.md Reviewer audit references/reviewer-audit.md Humanize references/humanize.md Reader-facing claim voice references/assertive-scientific-writing.md LaTeX references/latex.md Visual readiness references/visual-readiness-gate.md Submission metadata references/submission-metadata.md Publication surface references/publication-surface.md Publication target profile references/publication-target-profile.md Submission / revision / transfer cycle references/publication-cycle.md Publication-cycle main-flow interface references/publication-cycle-interface.md Journal transfer references/journal-transfer.md Usage telemetry / phase receipts references/usage-telemetry.md , references/phase-contracts.md Translate references/translate.md Respond references/respond.md Audit references/audit.md Historical worker skill names ( paper-spine-research , etc.) are legacy only and are not user entry points. Operating Principle PaperSpine is a research-writing workflow, not a prose patcher. Its job is to learn the target scene and available evidence, confirm the controlling contribution and motivation, then give the writing Agent room to design the strongest argument and manuscript structure for the actual material. Never fabricate data, metrics, p-values, datasets, citations, figures, or experimental claims. User materials are authoritative for this paper's results. External examples teach structure and rhetoric only. Keep scientific boundaries explicit without repeating the full provenance disclaimer in every paragraph. Define stable evidence scope at the paper or section boundary, inherit it until the evidence changes, and restate only the exception. This preserves caution without defensive repetition. Default to review_policy=balanced . Gates are decision aids, not a substitute for writing judgment. Hard-block fabricated facts/citations, unsupported primary claims, unresolved figure/text conflicts, broken citations, missing required metadata, and unusable deliverables. Treat stylistic preferences, literature breadth inside a declared closed corpus, optional planning forms, and minor review suggestions as advisory. Use strict only when the user requests it or the task is explicitly a submission/final-compliance audit. Read references/review-policy.md when selecting or changing this policy. The internal evidence model may be precise; the manuscript should still sound like a confident scholarly article. Read references/assertive-scientific-writing.md : state supported results directly, reserve hedging for genuine uncertainty or causal/generalization boundaries, and do not repeat audit language in reader-facing prose. Editorial North Star The manuscript is the product; plans, ledgers, reviews, and receipts exist only to help the Agent write it. A workflow is not complete merely because its internal artifacts pass. The final paper must let its intended reader follow one visible arc: why the work was needed, what was done, what the evidence shows, what those findings mean, and what conclusion the evidence earns. Give the writing Agent freedom to choose section architecture, paragraph moves, emphasis, and revision order from the confirmed contribution, target venue, and available evidence. Guide with reader questions and editorial judgment rather than paragraph quotas or extra forms. Hard stops are reserved for truth, authorization, unresolved evidence/figure identity conflicts, and unusable deliverables. tier changes research and process depth, never the promised manuscript scale. A flash journal paper is still a complete journal paper; it is not permission to omit the ending, compress Results into captions, or replace Discussion with an audit summary. Read references/editorial-completeness.md before drafting and again for the integrated editorial pass. Contribution-First, Reviewer-Aware Rules (V4) These three rules sit above the motivation thread. Motivation remains required, but it supports the contribution rather than replacing it. Contribution-First. The manuscript's highest-priority organizing unit is the confirmed contribution. Do not begin substantive writing until confirmed_contribution.md exists (what the paper adds, what problem/gap/ challenge makes it necessary, what evidence validates it, what claim boundary to respect, why a reviewer should find it publishable). Template + per-section checklists: references/contribution.md . Gate: contribution_check.py . Results-as-Validation. Each major Results subsection must validate at least one contribution promise; metric-only units with no contribution mapping are a failure. Record this in results_validation.md . Template: references/results-validation.md . Gate: results_validation_check.py (journal / conference / competition scenes). Reviewer-Aware. Before claiming submission-ready, create reviewer_audit.md (reviewer value map + objection register + editorial fit), populating the objection register from the three structured_review reviewer agents. Template: references/reviewer-audit.md . Gate: reviewer_audit_check.py . The contribution check runs at semantic confirmation and again at planning; Results validation runs at planning before prose; reviewer audit runs before LaTeX assembly. Stage 12 re-runs all three as defense in depth. Final audit must never be the first place one of these failures is discovered. User-Facing Language When the user writes in Chinese, ui_language=zh , output_language=zh , or translation_package=zh , all user-facing communication must be in Chinese throughout the whole run, not only in the final completion report. This includes intermediate progress updates, status bullets, tool-result summaries, blocked messages, gate re-run notes, final delivery tables, and error explanations. Do not write English progress sentences such as "Chinese .docx generated", "Now writing the word report", "All stages passed", "Deliverables", or "PaperSpine Workflow Complete" in those Chinese-facing runs. Use Chinese status phrases instead, for example: 中文 Word 文档已生成：final_paper/paper.zh.docx。正在写入 Word 检查报告并重新运行关卡检查。 PaperSpine 工作流已完成 全部阶段已通过 交付文件清单 Tool names, file paths, command names, and required English manuscript text may remain literal, but explanatory prose around them must be Chinese. Required Configuration Prefer reading paper_rewriting_output/paper_spine_config.json . If it is missing, read references/intake.md and collect configuration. Required fields: Field Allowed Values workflow rewrite_existing , build_from_materials scene journal , conference , report_review , competition tier flash , pro (research/process depth only; never manuscript completeness) output_language en , zh target_name free text materials_dir path or empty draft_path path or empty user_motivation free text or empty official_urls list special_requirements list word_output none , docx translation_package none , zh reference_mode local_first , specified_paths , web reference_paths list of local reference folders/files; default ["."] citation_target_count integer; default 20 humanize_tier none , light , medium , heavy Optional policy fields (default without adding intake questions): Field Allowed Values review_policy balanced (default), strict literature_scope auto (default), closed_corpus , open_literature Non-Negotiable Route Resume-first rule: Before starting any workflow, read references/resume.md and run progress_check.py against paper_rewriting_output/ . If earlier stages have produced valid artifacts, start from the first incomplete stage. After executing that stage, run its gate, run the full progress check again, and continue until final audit is complete. Do not restart from intake unless the user explicitly requests a clean run or the output directory is empty. Anti-skip rule: Each stage is a gate. After completing a stage, run its gate check before moving to the next. If the gate fails, route back to that stage — do not skip, do not hand-write the missing artifact, do not patch downstream. The gate script is progress_check.py --gate <stage_name> . Never use bulk placeholder generators such as generate_artifacts.py , quick_generate.py , or mock_artifacts.py to replace real stage work. Default Word output: Word (.docx) is a standard required artifact. Produce it in the LaTeX stage unless word_output is explicitly set to none in config. If pandoc is unavailable, write a BLOCKED/FAIL note in latex_report.md and do not declare completion. Stage 1 — Intake / Configuration If configuration is missing or incomplete, run the terminal wizard from the intake UI via the absolute installed launcher $env:USERPROFILE\.claude\skills\paper-spine\scripts\launch_paperspine_ui.ps1 (or the .codex equivalent, or $HOME/.codex/skills/paper-spine/scripts/launch_paperspine_ui.sh on bash); do not ask the user to hand-write JSON or answer a long plain chat checklist when a terminal is available. In Claude Code, /paperspine is the preferred entry: it launches the external intake window automatically when configuration is missing. Codex hard constraint (do not skip): when paper_rewriting_output/paper_spine_config.json is missing, the FIRST tool action after reading this skill MUST be to run the absolute launch_paperspine_ui.ps1 (resolve under ~/.codex/skills/... or ~/.claude/skills/... ) with sandbox_permissions: require_escalated so the window can open. Gate: python scripts/progress_check.py paper_rewriting_output --gate intake If FAILED: return to intake. Config must exist and be valid before any research. Stage 2 — Research Read references/research.md and execute the research stage. Research must index local references per reference_mode and reference_paths before any web collection. Required outputs: reference_materials/source_index.md , research_dossier.md , exemplar_learning_dossier.md , style_profile.md , sota_gap_map.md , contribution_options_after_research.md , motivation_options_after_research.md . Gate: python scripts/progress_check.py paper_rewriting_output --gate research If FAILED: return to research. All six artifacts must exist before citation work begins. Stage 3 — Citation Support Bank Read references/citation.md and build citation_support_bank.md . Resolve the literature contract first. open_literature builds a broad candidate pool (normally citation_target_count * 3 unique sources, with recency as a coverage goal). closed_corpus exhausts and deduplicates the supplied bibliography, requires enough real sources for the planned final citations, and treats recency/breadth as disclosed limitations rather than reasons to stop writing. Repeating one paper never increases source coverage in either mode. Gate: python scripts/progress_check.py paper_rewriting_output --gate citation If FAILED: return to citation. The bank must exist with sufficient candidates. Stage 4 — Semantic Confirmation Read references/semantic-confirmation.md . Stop for user confirmation of the contribution contract first and its supporting motivation second. Write confirmed_contribution.md and confirmed_motivation.md only after the user chooses, revises, combines, or replaces the research-generated options. This stage is BLOCKED (not just pending) until the user confirms both artifacts. Present contribution_options_after_research.md and motivation_options_after_research.md ; do not auto-select either one. Gate: python scripts/progress_check.py paper_rewriting_output --gate semantic_confirmation If FAILED/BLOCKED: stop and wait for user. Do not proceed with an unconfirmed or invalid contribution contract, even when motivation is already confirmed. Stage 5 — Humanize (if applicable) If humanize_tier is light , medium , or heavy , read references/humanize.md and apply tier-specific constraints. Stage 6 — Writing / Drafting If workflow is rewrite_existing , read references/rewrite.md . If workflow is build_from_materials , read references/build.md . Both workflows create section_blueprints.md before drafting. In balanced mode, the blueprint plus evidence ledger/results map are enough: the Agent may plan in the format that best supports the paper and should not expand a table merely to satisfy a row quota. writing_rationale_matrix.md is required only in strict mode or when the user explicitly asks for a paragraph-level rationale trace. For evidence-bearing scenes, read references/scientific-evidence-ledger.md and create scientific_evidence_ledger.json during planning. Separate and link sources, claims, numeric facts, methods, outcomes, and results; preserve verification state rather than collapsing all evidence into one prose bank. For journal , conference , and competition , read references/results-validation.md and create results_validation.md during planning, before Results prose. Every planned major Results unit must test at least one contribution promise. When existing scientific figures are present or new/redesigned figures are needed, set figure_policy to existing_only or generate_or_redesign , read references/figure-story.md , and inspect every existing image and panel with a multimodal tool before drafting. Create one figure_requests.json contract that records each figure's question, dominant claim, intended conclusion, claim boundary, hero panel, panel jobs/evidence anchors, Results units, caption, and keep / redesign / create decision. This is both the manuscript storyboard and the PaperFigure/FigMirror handoff; do not add a second figure-planning form. Read references/editorial-completeness.md . Use the blueprint and figure story as private scaffolding, then expand them into full reader-facing argument. The Agent may merge, split, or rename sections to fit the venue; every full-paper scene must nevertheless complete the research arc and give Results and Discussion enough space to do their distinct intellectual jobs. Gate: python scripts/progress_check.py paper_rewriting_output --gate planning If FAILED: return to the writing stage. Blueprints and, for evidence-bearing scenes, the Results validation/evidence map remain mandatory. Strict mode also requires the rationale matrix. Planning artifacts should capture real decisions, not restate the same justification in many cells. Write Results by figure question and claim: visible evidence first, then the bounded answer. Do not reduce Results to chronological panel narration. For redesign / create , use the existing PaperFigure integration; its candidates must preserve the same scientific-story contract while exploring visual form. After drafting, run: