Imported from guqingze/research-manuscript-workflow (SKILL.md). Install upstream with npx skills add guqingze/research-manuscript-workflow. Copyright stays with the author.

Research Manuscript Workflow

Core Principle

Separate the manuscript system into artifacts with distinct jobs. Do not let literature synthesis, analysis results, manuscript specification, and final prose collapse into one document.

Use this default artifact model unless the repo already has stronger conventions:

• Reference manager: canonical library for paper membership, metadata, attachments, and live citations.
• Literature search record: reproducible search strategy, screening decisions, and candidate source corpus before or alongside reference-manager import.
• Literature acquisition queue: human-in-the-loop full-text collection checklist that bridges searched candidates to a project reference-manager collection.
• Literature index: generated LLM-facing lookup table with citation keys, themes, roles, key claims, caveats, and local attachment status.
• Evidence-extraction cache: generated, committed, per-paper structured extraction (one record per cached full text) produced by fan-out worker subagents from the markdown cache; carries study characterization, anchored quantitative findings, and relevance tags so that gap synthesis, drafting, and QA read verified numbers without re-reading full text. Optional layer used when the corpus is large; sits between the literature index and gap synthesis.
• Gap synthesis: curated interpretation of the literature and the research gap.
• Planned-analyses roadmap: literature- and reviewer-motivated analyses not yet run, with an in-cohort/data availability audit and effort tiers; a cross-cutting artifact that feeds both gap synthesis and the Analysis Refresh Report during the research iteration loop.
• Analysis Refresh Report: current project results only, generated or updated from scripts and outputs, with provenance, interpretation, and manuscript handoff.
• Reflection memo: living mid-project discussion — current results argued against the gap synthesis, the external literature, and internal-meeting feedback — that identifies contradictions, drives planned-analyses and SAP updates, and eventually seeds the manuscript Discussion. Distinct from gap synthesis (which interprets external literature only) and from the Analysis Refresh Report (which carries results without framing).
• SAP/Outline Controller: controlling manuscript structure, analysis hierarchy, section claims, word counts, tables, figures, and main-vs-supplement decisions.
• Narrative deck: a framing-rehearsal slide outline built before drafting prose — storyline/spine, locked framing decisions, act/section structure, presenter notes, and open questions — used to pressure-test the narrative (often at an internal meeting) and gather feedback that re-enters the research iteration loop. An any-time branch off reflection, not a fixed linear stage.
• Manuscript Draft Package: draft document generated from the SAP/Outline Controller, gap synthesis, Analysis Refresh Report, and citation index.
• Style-Polished Manuscript Draft Package: readability and author-voice pass over a draft or revised draft, with preserved facts, citations, numbers, and scientific meaning.
• QA Gate Report: factual integrity and readiness audit for claims, citations, data outputs, tables, figures, and render status.
• Pre-Submission Review Report: reviewer-style critique of manuscript merit, journal fit, argument quality, and likely reviewer objections.
• Journal Submission Package: target-journal formatted first-submission bundle and submission checklist.
• Revision Roadmap: structured post-review plan built from editor, reviewer, or coauthor comments.
• Revised Manuscript Draft Package: revised draft plus revision log and response-to-reviewers draft.
• Response Package: resubmission bundle with revised manuscript, response letter, updated QA, and journal resubmission checklist.

Workflow Router

Choose the smallest mode that satisfies the user's request. Do not run the full workflow when the user asks for one layer only. Modes are grouped by the three macro-phases (see Workflow); setup is a cross-phase preamble.

If the request spans multiple modes, start at the earliest affected mode and state the planned sequence. If the user's current stage is ambiguous, inspect the repo workflow docs and existing manuscript artifacts before asking for clarification.

Literature Search Mode

Use literature-search when the user wants to find candidate papers before curating them in Zotero or generating the literature index. Borrow the discipline of ARS deep-research Phase 2, but keep the output repo-oriented and ready for reference-manager import and full-text acquisition.

This mode should produce a reproducible search record and a machine-auditable candidate corpus. It should not assume that PDFs are already available. In projects where the user retrieves full text through university or institutional access, make the next human action obvious for each retained source.

Minimum procedure:

1. Define search parameters: research question or scoped topic, databases or sources, keywords and synonyms, Boolean strategy, date range, languages, and document types.
2. Apply inclusion and exclusion criteria before screening results. Do not retrofit criteria to justify already-preferred papers.
3. Screen in two passes when enough metadata is available: title/abstract first, then full text or detailed metadata for retained sources.
4. Record reproducibility details: search date, database/source, query string, raw hit count, screened count, excluded count, and inclusion reasons for retained sources.
5. Verify candidate existence with DOI, publisher, PubMed, Crossref, Semantic Scholar, OpenAlex, or another authoritative record when feasible. Mark unresolved metadata explicitly instead of inventing it.
6. Make the retained corpus auditable by later literature-acquisition and literature-ingest runs. For each retained source, include stable fields such as source_id, tier or priority, title, first author, year, journal or source, PMID, DOI, URL, manuscript role, verification status, and unresolved metadata.
7. Add acquisition handoff fields when the next step is Zotero/PDF collection: target_collection, zotero_status, pdf_status, local_cache_status, and next_human_action. Default these to pending or unknown rather than implying that the paper has been collected.
8. Separate auditable core sources from reserve or conditional suggestions. Mark generic reserve suggestions, such as "add PRS-CS/LDpred2 methods papers if needed", as non-auditable so they are not counted as missing reference-manager items during later reconciliation.
9. Stop at candidate corpus and search documentation. Do not write the gap synthesis, manuscript prose, or literature index unless the user also asked for the next mode.

Default output: a search strategy report plus a candidate source table suitable for Zotero import or manual curation. The table should be stable enough that a later run can compare it against a Zotero collection by DOI, PMID, URL, and normalized title without re-parsing prose.

Recommended candidate table columns:

source_id, audit_scope, tier, priority, title, first_author, year, journal_or_source, PMID, DOI, URL, manuscript_role, inclusion_reason, verification_status, target_collection, zotero_status, pdf_status, local_cache_status, next_human_action, notes.

Literature Acquisition Mode

Use literature-acquisition after candidate papers have been identified but before literature indexing. This mode supports a human-in-the-loop full-text collection workflow where the user may need institutional credentials to access publisher PDFs.

Minimum procedure:

1. Read the literature search record and identify the auditable core corpus. Keep reserve or non-auditable suggestions separate.
2. Resolve or confirm the target reference-manager collection name/key.
3. Generate or update an acquisition queue with stable source IDs, title, PMID, DOI, URL, tier or priority, manuscript role, reference-manager status, and PDF attachment status.
4. When the reference manager is reachable, compare the queue against the target collection by DOI, PMID, URL, and normalized title. Report missing collection items separately from items that exist but lack PDF attachments.
5. Help the user work the manual download queue by grouping missing items by priority and providing PubMed, DOI, or publisher URLs. If asked, open or list target links, but do not handle institutional credentials or bypass paywalls.
6. After the user confirms that records/PDFs have been added to the collection, hand off to literature-ingest to build the markdown cache from the collection's PDFs, write the manifest, and regenerate the literature index. PDFs stay in the reference manager; they are not copied into the repo.

Default output: an acquisition checklist or CSV plus a concise list of missing reference-manager records and missing PDF attachments.

Gap Synthesis Mode

Use gap-synthesis after literature-ingest has produced a stable literature index. This mode performs interpretation across indexed papers. It should make the manuscript's intellectual position explicit before SAP/outline or drafting.

Core rule: integrate across sources, do not summarize papers sequentially.

Minimum procedure:

1. Build or update a compact evidence matrix before writing prose. Include themes, supporting papers, contradicting papers, population or context, method type, evidence strength, and manuscript use.
2. Identify convergence, divergence, and silence:
   • convergence: where multiple sources support the same claim;
   • divergence: where sources conflict or imply different boundary conditions;
   • silence: where the indexed literature lacks evidence needed for the manuscript's question.
3. Resolve or explain contradictions where possible. Consider population, geography, endpoint/exposure definitions, methods, confounding control, follow-up period, study quality, and publication date.
4. Classify the gap instead of using vague gap language. Useful types include empirical, methodological, definition, temporal, geographic, translation, mechanistic, ancestry/population, prospective-cohort, endpoint-harmonization, and PRS/generalizability gaps.
5. Produce claim-evidence-reasoning (CER) chains for manuscript-facing claims: each claim needs cited evidence, reasoning, caveat or hedge, and suggested manuscript section.
6. Run a short stress test before finalizing:
   • Has the synthesis cherry-picked supportive papers?
   • Are contradictions interpreted rather than explained away?
   • Would the gap still stand if the strongest supporting paper were removed?
   • What would a skeptical reviewer say is overstated?
   • Does the proposed gap justify the project's actual analyses?
7. Hand off explicitly to sap-outline: state which introduction claims, methods justifications, primary analyses, discussion comparisons, and supplement-only claims should follow from the synthesis.
8. Stop at synthesis and handoff guidance. Do not write manuscript prose or decide final table/figure order unless the user also asked for the next mode.

Default output: an integrated gap synthesis with an evidence matrix, convergence/divergence map, gap taxonomy, positioning claim, CER chains, stress test notes, and SAP/outline implications.

Key-paper evidence extraction (subagent map-reduce)

Token cost — warn the user before running. Fanning out full-text extraction is one of the most token-expensive operations in this workflow: every selected paper is read in full by a worker, and larger sets multiply that cost. State the intended scope and that this step is token-heavy before starting, and default to a focused key-paper set rather than the whole corpus.

Reading a large full-text corpus directly into one context to synthesize it either overflows the context or silently regresses to abstract-level summary. Build the gap synthesis with an explicit map-reduce that first materializes a persistent, verifiable evidence-extraction cache for the papers that matter, then reduces from that cache.

Extract the identified key papers, not the whole corpus. Before fanning out, select the subset that actually bears on the manuscript's claims — anchor, counter-example, and benchmark papers (by role and theme in the literature index) plus any the user names. This is a human-in-the-loop step, especially when token-limited: propose the key-paper set with the reason each is "key", and let the user confirm, add, or trim it before extraction runs. Reserve full-corpus extraction for when the user explicitly wants exhaustive full-text grounding.

When to build a cache at all (vs reading the markdown cache directly in-context):

• the selected key-paper set is larger than roughly 25-30 papers, or
• the user explicitly asks for a full-text-grounded synthesis, or
• the same extracted numbers will be reused across reflection, drafting, and QA.

For a smaller key-paper set, read those markdown files directly in-context; the map-reduce overhead is not worth it.

Map (parallel worker subagents, engine-agnostic, workers write). Fan out the selected key papers in small batches (~5-6 papers per worker). Each worker reads only the assigned full-text markdown files and writes one committed record per paper into the evidence-extraction cache, following references/evidence-extraction-contract.md (schema, three-layer anchor rules, and the worker prompt template). The worker engine is pluggable and both session hosts are supported:

Codex worker invocation (read the papers, write records, scoped to the cache dir): codex exec -m <model> -c model_reasoning_effort=medium --sandbox workspace-write --cd <repo> -a never. Extraction is mechanical structured transcription against a fixed schema, so run workers one model tier below the reduce (a cheaper/faster model), keep the session's strongest model for the reduce, and confine worker writes to the extraction-cache directory (audit with git diff plus the anchor checker).

Make extraction idempotent: mirror the markdown-cache manifest into an extraction-cache manifest keyed to each source's SHA-256, and re-extract a paper only when its source SHA or the schema version changed (--force rebuilds all).

Verify (100% mechanical + targeted human). Before reducing, run the shared checker scripts/verify_extract_anchors.py over the whole cache: it decodes every quote anchor and substring-matches it against the source markdown, enforces the no-unanchored-number rule (any quantitative finding lacking a quote/section/ table anchor must be flagged verification_status: needs_pdf), and checks each record's source SHA against the manifest. Fix or quarantine every hard failure. Then re-read (human/orchestrator) only the numbers bound for the manuscript (the anchor comparators and any figure that will reach prose) to catch misinterpretation of otherwise-valid quotes.

Reduce (orchestrator, in-context, with project context). The session orchestrator — not a fresh cold subagent — reads the whole verified cache in one context and writes the gap synthesis. Doing the reduce in the session that holds the project's results, SAP, and positioning discussion is deliberate: a cold synthesis subagent re-derives the story from scratch and drifts toward stale or generic framing. If a corpus is too large for the cache to fit one context, fall back to a hierarchical reduce (batch-level partial syntheses from subagents, then an orchestrator merge) rather than handing the whole reduce to a subagent.

The reduce output is the same integrated gap synthesis specified above; the cache only changes how its evidence is sourced and verified, not the synthesis contract.

Analysis Refresh Mode

Use analysis-refresh when project results need to be regenerated, reconciled, interpreted, or prepared for manuscript planning. This mode consumes repo pipelines and generated outputs; it does not invent analyses outside the project's scripts or controlling SAP.

Core rule: produce a manuscript-ready analysis handoff, not just a prose results summary.

Minimum procedure:

1. Establish run provenance: commands run or inspected, run label/date, working directory, key script paths, input paths, output paths, and relevant environment or git context when useful.
2. Check cohort and data contracts: sample counts, exclusion flow, denominators, missingness, endpoint/exposure definitions, follow-up windows, and whether counts agree across generated tables and QC outputs.
3. Inventory result artifacts: tables, figures, model outputs, logs, and manuscript-facing summaries. Label each as primary, secondary, sensitivity, exploratory, supplement-only, or not-for-manuscript when the SAP or repo docs provide that distinction.
4. Interpret statistical outputs conservatively. Record effect estimates, confidence intervals, p-values when present, practical magnitude, direction, precision, model adjustment set, and whether assumptions or diagnostics are documented.
5. Run a focused fallacy and overclaim scan:
   • causal language unsupported by the design;
   • multiple comparisons without correction or clear exploratory framing;
   • subgroup, endpoint, or ancestry generalization beyond the data;
   • selection, survivorship, collider, or overadjustment concerns;
   • non-significant or imprecise estimates framed as definitive;
   • statistical significance reported without effect size or uncertainty.
6. Verify manuscript consistency: numbers in the report must match current generated outputs; table/figure references must exist; captions and denominators must match; primary/secondary labels must match the SAP or be flagged as unresolved.
7. Produce the handoff document, named conceptually Analysis Refresh Report. This report feeds sap-outline and draft and should separate Results-ready claims, Discussion-only interpretations, supplement-only findings, and unresolved blockers.
8. Stop at analysis reporting and handoff guidance. Do not revise the SAP, reorder tables/figures, or draft manuscript prose unless the user also asked for the next mode.

Default handoff document: Analysis Refresh Report with these sections:

• Run provenance
• Cohort and data checks
• Result artifact inventory
• Statistical interpretation
• Fallacy and overclaim scan
• Manuscript handoff
• Unresolved blockers and recommended next actions

SAP/Outline Mode

Use sap-outline after gap-synthesis and analysis-refresh have produced their handoff documents. This mode creates the controlling manuscript plan. It should decide what goes where, at what priority, and with what evidence; it should not draft polished prose.

Core rule: structure serves the manuscript argument and the available results.

Minimum procedure:

1. Select or confirm the manuscript structure pattern. For empirical cohort or clinical epidemiology work, default to IMRaD unless repo or journal instructions require another structure.
2. Define the central manuscript thesis or positioning claim from gap-synthesis, then decompose it into 3-5 section-level sub-arguments.
3. Map evidence and results to sections:
   • literature claims and CER chains from gap-synthesis;
   • Results-ready claims, Discussion-only interpretations, and supplement-only findings from the Analysis Refresh Report;
   • tables, figures, model outputs, and sensitivity analyses.
4. Allocate manuscript roles explicitly: primary, secondary, sensitivity, exploratory, supplement-only, or not-for-manuscript.
5. Build the section plan. For each section or subsection, record purpose, target word count, core claim, required evidence/results, table/figure references, citations or citation-key groups, and transition logic.
6. Check argument strength before handing off to drafting:
   • each core claim has evidence and reasoning;
   • counter-arguments or limitations are assigned to Discussion;
   • no Results claim exceeds the Analysis Refresh Report;
   • no Introduction or Discussion claim exceeds the gap synthesis;
   • unresolved decisions are listed instead of silently filled.
7. Produce the handoff document, named conceptually SAP/Outline Controller. This document is the authority for draft.
8. Stop at planning. Do not draft manuscript prose unless the user also asked for draft.

Default handoff document: SAP/Outline Controller with these sections:

• Manuscript target and structure pattern
• Central thesis or positioning claim
• Section-by-section outline with purpose and word counts
• Argument map and CER-to-section mapping
• Evidence/result/table/figure map
• Main-vs-supplement and primary-vs-secondary decisions
• Transition logic
• Drafting instructions and unresolved decisions

Analysis Plan Mode

Use analysis-plan inside the research iteration loop when the literature, a reflection memo, internal-meeting feedback, or a reviewer suggests analyses the project has not yet run. This mode decides what is worth running next and whether it is even possible with the project's data; it does not run the analyses or draft prose.

Core rule: audit availability before proposing. A proposed analysis that the cohort or linked data cannot support is a limitation to document, not a task to queue.

Minimum procedure:

1. Collect candidate analyses from the gap synthesis, reflection memo, meeting feedback, reviewer comments, and the covariate/measurement literature.
2. For each candidate, run an in-cohort/in-data availability audit: is the variable or assay present, at what completeness, in which subcohort, and is it a confounder, mediator, or collider relative to the current model? Distinguish "computable now from existing columns", "needs new derivation/linkage", and "not available in-cohort".
3. Classify each candidate by role (strengthens confounding control, orthogonal cross-check, mechanism, robustness/QC, descriptive) and by effort tier (straightforward now / intermediate needs generation or linkage / future research program).
4. Recommend which candidates to run this cycle, which to defer, and which to convert into stated limitations; keep non-auditable or speculative suggestions separate from the actionable queue.
5. Hand off: actionable Tier-1 items feed the repo pipeline and analysis-refresh; deferred and future items seed a Next-Steps/roadmap section for the SAP and eventual Discussion.
6. Stop at planning and triage. Do not run analyses or edit the SAP unless the user also asked for the next mode.

Default handoff document: Planned-analyses roadmap with these sections:

• Candidate analyses with driver/source
• In-cohort/in-data availability audit (completeness, subcohort, confounder/mediator/collider status)
• Role and effort-tier classification
• Run-now / defer / convert-to-limitation recommendation
• Non-auditable or speculative reserve (kept separate)

Reflection Mode

Use reflect inside the research iteration loop after analysis-refresh, when current results need to be argued against the external literature, the gap synthesis, and internal-meeting feedback. This is the living mid-project Discussion. It interprets and reconciles; it does not restate the numbers or draft final prose.

Core rule: reconcile, do not cherry-pick. Interpret contradictions between your results and the literature rather than explaining them away, and treat each as a possible driver of a new analysis, a framing change, or a stated limitation.

Minimum procedure:

1. Confirm inputs: Analysis Refresh Report, gap synthesis, literature index (and evidence-extraction cache when present), and any internal-meeting notes or coauthor feedback.
2. For each headline result, state where it converges with, diverges from, or is silent against the indexed literature. For divergence, interpret the likely reason (population, definitions, methods, adjustment set, measure-dependence) before deciding it is a real contribution.
3. Digest internal-meeting feedback: record decisions, objections, and requested analyses relevant to the analysis set or framing; convert each into a tracked action (analysis-plan candidate, SAP change, or open question).
4. Every literature or external claim asserted as established must anchor to a literature-index/evidence-cache record; verify it supports the specific outcome, subgroup, and direction being claimed (see citation-verification discipline in QA Gate Mode). Flag unresolved claims for PDF verification.
5. Produce drivers for the loop: what to send to analysis-plan, what SAP or framing changes to make, what to relegate to limitations, and what remains an open question for the next meeting or the eventual Discussion.
6. Stop at reflection. Do not run analyses, revise the SAP, or draft prose unless the user also asked for the next mode.

Default handoff document: Reflection memo with these sections:

• Result-by-result convergence/divergence/silence against the literature
• Interpreted contradictions (with likely reason)
• Internal-meeting feedback digest and resulting actions
• Drivers for analysis-plan and SAP updates
• Open questions and Discussion seeds

Narrative Deck Mode

Use narrative-deck as an any-time branch off reflection, before committing to manuscript prose, to pressure-test the storyline — commonly to build a slide outline for an internal meeting and gather feedback. This mode locks framing decisions and structure; it does not write the manuscript or invent results.

Core rule: the deck is a framing rehearsal, not the paper. Every number and citation on a slide must trace to the Analysis Refresh Report or a verified literature record, at the same standard as a draft.

Minimum procedure:

1. Confirm inputs: SAP/Outline Controller, Analysis Refresh Report, gap synthesis, reflection memo, and current figures/tables.
2. Choose and record the spine/storyline and the explicit framing decisions (what leads, what is secondary, what is shown vs relegated), including options considered and set aside so the group can see the forks.
3. Structure the deck into acts/sections with a one-line takeaway each; add presenter notes and mark reviewer-aware caveats to keep visible rather than compress.
4. Anchor every on-slide claim: results to the Analysis Refresh Report; external claims to verified literature records with the correct outcome/subgroup/ direction; prefer per-slide footnote-style citations over a single reference dump. Apply the citation-verification discipline (QA Gate Mode).
5. Collect open framing questions on a dedicated slide for the meeting; route the resulting feedback back into reflect and analysis-plan.
6. Stop at the framing outline. Do not draft the manuscript unless the user also asked for draft.

Default handoff artifact: Narrative deck with these sections:

• Spine/storyline and locked framing decisions (with options set aside)
• Act/section structure with per-slide takeaways and presenter notes
• On-slide claims anchored to results/literature, with per-slide citations
• Open framing questions for the group
• Feedback routed back to reflection/analysis-plan

Draft Mode

Use draft after a SAP/Outline Controller exists, or when the user explicitly asks for a partial section draft from available controlling materials. This mode executes prose from the controller; it does not rediscover the argument.

Core rule: follow the SAP/Outline Controller. If the controller conflicts with the gap synthesis or Analysis Refresh Report, flag the conflict before drafting the affected claim.

Minimum procedure:

1. Confirm inputs: SAP/Outline Controller, gap synthesis, Analysis Refresh Report, literature index/reference collection, current tables/figures, and any journal or word-count instructions. Read paper content from the markdown cache; open the reference-manager PDF only to verify exact wording or numbers.
2. Draft section by section. For each section, use the controller's purpose, assigned claims, citations, results, tables/figures, word count, and transition logic.
3. Use source-specific inputs by section:
   • Introduction: gap synthesis, positioning claim, and verified literature index entries.
   • Methods: SAP, cohort/data definitions, endpoint/exposure definitions, and analysis provenance.
   • Results: Analysis Refresh Report only; avoid interpretation that belongs in Discussion.
   • Discussion: gap synthesis plus Analysis Refresh Report; separate evidence, inference, limitations, implications, and future work.
4. Track placeholders and unresolved items inline or in a draft log. Do not invent citations, numbers, table references, or methods details.
5. Preserve citation discipline. Use citation keys or live-reference workflow when available, and keep claims traceable to the literature index or analysis outputs.
6. Track word counts by section and report deviations from the controller.
7. Run a pre-QA self-check before handoff:
   • every major claim has a citation or analysis-output source;
   • table/figure references exist;
   • Results wording does not overinterpret;
   • Discussion hedging matches evidence strength;
   • unresolved placeholders are listed.
8. Produce the handoff artifact, named conceptually Manuscript Draft Package. This package feeds style-polish when prose quality or author voice needs attention, otherwise qa.

Default handoff artifact: Manuscript Draft Package with these sections or metadata:

• Draft path and render path if available
• Source inputs used
• Section word counts and deviations
• Citation workflow used
• Table/figure references used
• Placeholder and unresolved-item log
• Known limitations before QA

Style Polish Mode

Use style-polish after draft or revise when the manuscript needs a readability, tone, or author-voice pass before QA. This mode improves prose quality without changing the scientific argument, results, citations, or disclosure obligations.

Core rule: polish for clarity and author voice, not for AI-detector evasion or to hide AI assistance. If the project or target journal requires AI-use disclosure, preserve or flag that requirement.

Minimum procedure:

1. Establish inputs: Manuscript Draft Package or Revised Manuscript Draft Package, SAP/Outline Controller, gap synthesis, Analysis Refresh Report, literature index, author writing samples if available, target journal style if known, and render workflow.
2. Lock scientific content before editing. Preserve numbers, denominators, effect estimates, confidence intervals, p-values, endpoint definitions, table/figure references, citation keys, and section-level claims unless the user explicitly requests scientific revision through draft or revise.
3. Calibrate style from author samples when available. Treat the style profile as a soft guide; discipline conventions, journal instructions, and factual clarity override personal style preferences.
4. Run a writing-quality sweep inspired by ARS writing-quality checks:
   • replace generic high-frequency academic filler only when a more precise phrase is available;
   • remove throat-clearing openers and meta-commentary such as "this section discusses" when the section can simply make the point;
   • reduce inflated novelty or importance language not supported by the gap synthesis or Analysis Refresh Report;
   • avoid monotonous rule-of-three lists, repeated paragraph templates, synonym cycling, and overused binary contrasts;
   • control punctuation tics such as excessive em dashes, semicolons, and colon-list sequences;
   • vary sentence and paragraph rhythm where doing so improves readability, while accepting more uniform prose in procedural Methods text.
5. Preserve academic register. Do not make epidemiology, clinical, statistical, or methods prose conversational when precision is more important than rhythm. For epidemiology, clinical-epidemiology, or population-health manuscripts, also read references/epidemiology-manuscript-discipline.md and apply its section discipline, causal-language restraint, internal-language scrub, and phrase replacements; consult the project's epi revision-lessons file if one exists.
6. Maintain traceability. If a sentence becomes smoother but less obviously tied to a citation or output, revise again or flag it for QA rather than leaving a polished but unsupported claim.
7. Record risky edits separately. If polishing would require changing meaning, adding interpretation, deleting a caveat, or weakening a required limitation, leave the passage unchanged and list it as an unresolved awkward passage.
8. Produce the handoff artifact, named conceptually Style-Polished Manuscript Draft Package. This package feeds qa.

Default handoff artifact: Style-Polished Manuscript Draft Package with these sections or metadata:

• Source draft or revised draft path
• Polished draft path and render path if available
• Author style sample status
• Style changes summary
• Preserved facts, citations, numbers, and table/figure references check
• Section word count changes
• Unresolved awkward passages
• Warnings where polishing risks changing meaning
• Disclosure or journal-style notes

QA Gate Mode

Use qa after a Manuscript Draft Package, Style-Polished Manuscript Draft Package, or Revised Manuscript Draft Package exists. This mode is the manuscript integrity and readiness gate. It verifies that the draft is traceable to the reference collection, literature index, Analysis Refresh Report, generated outputs, and SAP/Outline Controller.

Core rule: audit factual readiness, not manuscript merit. Do not perform peer review, editorial scoring, or broad rewriting unless the user also asks for a revision mode.

Minimum procedure:

1. Establish QA inputs: Manuscript Draft Package, Style-Polished Manuscript Draft Package, or Revised Manuscript Draft Package, draft/render paths, SAP/Outline Controller, gap synthesis, Analysis Refresh Report, literature index/reference collection, generated tables/figures, and render workflow.
2. Run claim QA:
   • classify major claims as literature-backed, analysis-backed, mixed, or unsupported;
   • verify that analysis-backed claims match the Analysis Refresh Report and generated outputs;
   • verify that literature-backed claims map to citation keys or reference records;
   • flag overreach, especially causal language, exaggerated novelty, or Discussion claims stronger than the evidence;
   • for epidemiology, clinical-epidemiology, or population-health manuscripts, apply references/epidemiology-manuscript-discipline.md: verify Results carry no interpretation or limitations, causal wording matches the design, internal/data-layer language is absent from prose, and references are numbered by first appearance.
3. Run citation QA:
   • check in-text citations against the reference collection or literature index;
   • identify orphan in-text citations and orphan references when a reference list is present;
   • check DOI/PMID/URL or metadata completeness when available;
   • flag cited sources with missing PDFs/cache entries if the repo requires local source verification.
4. Run claim-source alignment on important cited claims (the citation-verification discipline, applied here and during draft, reflect, and narrative-deck). Distinguish "reference exists" from "the source supports this sentence." Use the markdown cache for context and the canonical reference-manager PDF or authoritative metadata to verify exact wording; mark unverified items explicitly. Specifically:
   • verify the source supports the specific outcome, subgroup, direction, and magnitude claimed — not merely the general topic (a real failure mode is a citation that is right about the topic but wrong about which outcome or group, e.g. attributing a steatosis finding to a paper's fibrosis result);
   • catch misattribution across papers and fabricated or drifted numbers;
   • for a "well-established"/"known" claim asserted without a cite, either anchor it to a record already in the library or flag that a source must be added — do not invent a citation not in the reference collection;
   • prefer per-claim citation so each assertion is independently checkable.
5. Run data and output QA:
   • numbers, denominators, cohort counts, model labels, and p-values/CIs must match generated outputs;
   • table and figure references must point to existing files;
   • captions must match the current output and denominator;
   • main-vs-supplement placement must match the SAP/Outline Controller.
6. Run draft package QA:
   • section word counts and deviations are recorded;
   • placeholders and unresolved items are listed;
   • table/figure references and citation workflow are documented;
   • render status is checked when a render path or command exists.
7. Assign a gate verdict:
   • PASS: ready for the next packaging/review mode;
   • PASS_WITH_WARNINGS: usable, with listed warnings for human review;
   • BLOCKED: must fix blockers before packaging or handoff.
8. Produce the handoff document, named conceptually QA Gate Report. This report feeds pre-submission-review, journal-package, or response-package depending on the lifecycle branch.

Default handoff document: QA Gate Report with these sections:

• Verdict
• Claim QA
• Citation QA
• Claim-source alignment checks
• Data and output QA
• Draft package and render QA
• Blockers
• Warnings
• Handoff readiness

Pre-Submission Review Mode

Use pre-submission-review after qa and before journal-package when the user wants reviewer-style critique before first submission. This mode evaluates manuscript merit and likely reviewer concerns; it does not replace QA and does not rewrite the manuscript unless the user asks for a follow-on revision.

Core rule: critique the manuscript as a manuscript, not as a data audit.

Minimum procedure:

1. Establish review inputs: QA-passed Manuscript Draft Package or Style-Polished Manuscript Draft Package, QA Gate Report, SAP/Outline Controller, gap synthesis, Analysis Refresh Report, target journal or article type if known, and any author priorities.
2. Assess journal fit and contribution: audience, novelty, scope, article type, and whether the stated contribution follows from the literature gap and results.
3. Assess manuscript argument: Introduction problem framing, Results logic, Discussion interpretation, limitation handling, and whether the strongest claims are defensible.
4. Assess methods and reporting clarity at a manuscript level. Do not rerun analyses; instead flag unclear design, missing reporting, or weak explanation that a reviewer would notice.
5. Identify strongest likely reviewer objections, including methodology, novelty, generalizability, causal overreach, endpoint definitions, analysis hierarchy, and missing literature comparisons.
6. Prioritize recommended fixes as must-fix, should-fix, or optional. Keep factual integrity issues linked back to the QA Gate Report.
7. Produce the handoff document, named conceptually Pre-Submission Review Report. This report can feed draft for targeted improvements or journal-package if only minor warnings remain.

Default handoff document: Pre-Submission Review Report with these sections:

• Journal fit and contribution
• Major strengths
• Must-fix issues before submission
• Should-fix issues
• Optional improvements
• Likely reviewer objections
• Recommended next mode: draft, qa, or journal-package

Journal Package Mode

Use journal-package after QA and optional pre-submission review are complete. This mode prepares first-submission files for a target journal or a generic submission bundle. It is formatting and packaging oriented; content changes should be raised as blockers rather than silently made.

Core rule: preserve content while enforcing target-journal packaging requirements.

Minimum procedure:

1. Establish package inputs: QA Gate Report, Manuscript Draft Package or Style-Polished Manuscript Draft Package, target journal or article type, citation style, author/title page needs, figure and supplement files, and render workflow.
2. Check target-journal requirements when supplied: word limits, abstract structure, reference style, figure/table placement, reporting checklist, funding, COI, ethics, data availability, code availability, acknowledgments, AI disclosure, and supplementary-material rules.
3. Render or assemble requested formats when tooling exists, such as DOCX, PDF, Markdown, LaTeX, bibliography, figures, and supplements.
4. Prepare submission text assets: title page, abstract/keywords when not already final, cover letter draft, author contributions, funding/COI/data availability/ethics statements, and AI disclosure when needed.
5. Produce a submission checklist. If content-level issues appear, return to draft or qa; do not hide them in formatting.
6. Produce the handoff artifact, named conceptually Journal Submission Package.

Default handoff artifact: Journal Submission Package with these sections or metadata:

• Target journal and article type
• Final manuscript file paths
• Figure/table/supplement file paths
• Cover letter path or text
• Required statements
• Citation/reference style status
• Journal checklist and blockers
• Commands run and render status

Revision Plan Mode

Use revision-plan after external editor/reviewer comments or major coauthor comments arrive. This mode parses unstructured feedback into an actionable roadmap. It should not revise the manuscript directly.

Core rule: no comment left behind.

Minimum procedure:

1. Collect reviewer/editor/coauthor comments, decision letter if available, the submitted manuscript or Journal Submission Package, and any journal deadline.
2. Parse comments into atomic items. Split comments that contain multiple actionable requests.
3. Preserve reviewer intent: keep raw comment text, reviewer/editor source, paraphrased summary, and ambiguity flags.
4. Classify each item as major, minor, editorial, positive, or unclear. Assign priority: must-fix, should-fix, or consider. Promote items raised by the editor or multiple reviewers.
5. Map each item to manuscript sections, tables, figures, analyses, references, response-letter needs, and whether new analysis or literature work is required.
6. Produce a suggested revision order and response-letter skeleton. Flag contradictory reviewer requests for user decision.
7. Produce the handoff document, named conceptually Revision Roadmap. This report feeds revise.

Default handoff document: Revision Roadmap with these sections:

• Decision and revision context
• Parsed comment inventory
• Must-fix / should-fix / consider tables
• Cross-reviewer patterns
• Section/action map
• New analysis or literature needs
• Suggested revision order
• Response-letter skeleton

Revise Mode

Use revise after a Revision Roadmap exists and the user has approved the revision strategy. This mode applies the roadmap to the manuscript and records what changed. It should preserve traceability from each revision to the reviewer/editor comment it addresses.

Core rule: revise against the approved roadmap, not opportunistically.

Minimum procedure:

1. Establish revision inputs: Revision Roadmap, submitted or current Manuscript Draft Package or Style-Polished Manuscript Draft Package, Journal Submission Package if available, QA Gate Report, and any newly generated analysis or literature artifacts.
2. Address must-fix items first, then should-fix items, then optional items if appropriate. Do not silently drop any roadmap item.
3. For each revision item, record action taken, manuscript location, source material used, status, and whether the response letter needs explanation.
4. Keep Results revisions tied to the Analysis Refresh Report or regenerated outputs; keep literature revisions tied to the literature index or verified PDFs.
5. Produce or update response-to-reviewers draft text alongside manuscript changes.
6. List unresolved items and rationale. If a comment cannot be addressed without new analysis, new literature, or author decision, mark it as blocked.
7. Produce the handoff artifact, named conceptually Revised Manuscript Draft Package. This package feeds style-polish before qa when prose changed substantially or when the user requests a readability pass; otherwise it feeds qa.

Default handoff artifact: Revised Manuscript Draft Package with these sections or metadata:

• Revised draft path and render path if available
• Revision log mapped to comment IDs
• Resolved, partially resolved, unresolved, and blocked items
• Response-to-reviewers draft
• Updated placeholders and limitations
• Source inputs and commands used
• Recommended next mode: qa

Response Package Mode

Use response-package after a revised manuscript has passed QA. This mode prepares the resubmission bundle. It is distinct from first-submission journal-package because it must include point-by-point responses and revision traceability.

Core rule: every reviewer/editor item in the Revision Roadmap must be accounted for in the response package.

Minimum procedure:

1. Establish response inputs: Revised Manuscript Draft Package, Revision Roadmap, QA Gate Report, target journal/resubmission requirements, and any requested clean/tracked manuscript files.
2. Finalize point-by-point response letter: quote or summarize each comment, state response, state changes made, and list manuscript locations.
3. Assemble clean revised manuscript and tracked/change-log version when available or requested.
4. Update cover letter/editor note, required statements, supplement list, and figure/table files as needed.
5. Check that all must-fix items are resolved or explicitly justified.
6. Produce the handoff artifact, named conceptually Response Package.

Default handoff artifact: Response Package with these sections or metadata:

• Revised manuscript file paths
• Clean/tracked/change-log file paths when available
• Response-to-reviewers letter
• Editor cover letter or resubmission note
• Comment-resolution checklist
• Updated QA Gate Report path
• Journal resubmission checklist and blockers

Artifact Contracts

Keep contracts lightweight. Use the repo's existing formats when available, but ensure each artifact carries the fields needed for later sessions to consume it without re-discovering everything.

• Literature search record: research question or scoped topic, databases or sources searched, search date, query strings, inclusion/exclusion criteria, raw and screened counts, retained candidate sources with stable IDs and PMID/DOI/URL metadata, exclusion notes, non-auditable reserve suggestions, and unresolved metadata.
• Literature acquisition queue: source_id, tier or priority, title, PMID, DOI, URL, manuscript role, target collection, reference-manager status, PDF attachment status, local cache status, and next human action.
• Literature index: citation_key, title, year, paper role, themes, key claims, caveats, reference-manager item key, and markdown-cache status (md path, conversion method, source PDF checksum).
• Markdown cache manifest: per paper — reference-manager item key and attachment key, collection, source PDF path, md path, source SHA-256, conversion method (markdown | plaintext_fallback | needs_ocr), status, and char count. PDFs remain in the reference manager and are not committed to the repo.
• Evidence-extraction cache: per paper — citation_key, source md path and SHA-256 (mirrored from the markdown-cache manifest), schema_version, study characterization (design, setting, population, N, modality, cutoffs), an evidence grade, a list of anchored quantitative findings (each: claim, value, CI/p, adjustment set, and a quote/section/table anchor), relevance tags (manuscript role, which claim it bears on, convergence/divergence note, caveat), and verification_status. Full field-level schema, anchor rules, and the worker prompt template live in references/evidence-extraction-contract.md; a mirrored SHA-keyed extraction-cache manifest makes rebuilds idempotent. Anchors are verified by scripts/verify_extract_anchors.py.
• Gap synthesis: evidence matrix, key themes, convergence/divergence map, contradiction table, gap taxonomy, positioning claim, CER chains, synthesis limitations, SAP/outline implications, and claims requiring PDF verification before drafting.
• Planned-analyses roadmap: candidate analyses with driver/source; per-candidate in-cohort/in-data availability audit (completeness, subcohort, confounder/mediator/collider status); role and effort-tier classification; run-now/defer/convert-to-limitation recommendation; and a separated non-auditable/speculative reserve.
• Analysis Refresh Report: commands run or inspected, run label/date, relevant input and output paths, cohort/sample definitions, exclusion flow, denominators, result artifact inventory, primary/secondary/sensitivity labels, statistical interpretation, fallacy and overclaim scan, table/figure provenance, Results-ready claims, Discussion-only interpretations, supplement-only findings, unresolved blockers, and recommended next actions.
• Reflection memo: per-result convergence/divergence/silence against the indexed literature; interpreted contradictions with likely reason; internal- meeting feedback digest and resulting actions; drivers for planned-analyses and SAP updates; and open questions and Discussion seeds.
• SAP/Outline Controller: target journal or audience if known, manuscript structure pattern, central thesis or positioning claim, section outline, section purposes, word count allocation, argument map, CER-to-section mapping, evidence/result/table/figure map, primary and secondary analyses, sensitivity and exploratory labels, supplement placement, transition logic, drafting instructions, and unresolved decisions.
• Narrative deck: spine/storyline and locked framing decisions (with options considered and set aside); act/section structure with per-slide takeaways and presenter notes; on-slide claims anchored to the Analysis Refresh Report or verified literature records with per-slide citations; open framing questions for the group; and feedback routed back to reflection/analysis-plan.
• Manuscript Draft Package: source inputs used, draft/render path, citation workflow used, section word counts, table/figure references, placeholder and unresolved-item log, and known limitations before QA.
• Style-Polished Manuscript Draft Package: source draft path, polished draft/render path, author style sample status, style changes summary, preserved facts/citations/numbers/table-figure references check, section word count changes, unresolved awkward passages, warnings where polishing risks changing meaning, and disclosure or journal-style notes.
• QA Gate Report: gate verdict, claim QA, citation QA, claim-source alignment checks, data and output QA, draft package and render QA, blockers, warnings, and handoff readiness.
• Pre-Submission Review Report: journal fit, contribution assessment, manuscript strengths, must-fix issues, should-fix issues, optional improvements, likely reviewer objections, and recommended next mode.
• Journal Submission Package: target journal, article type, final manuscript paths, figure/table/supplement paths, cover letter, required statements, citation/reference status, journal checklist, blockers, commands run, and render status.
• Revision Roadmap: decision context, parsed comment inventory, raw comment text, reviewer/editor source, severity, priority, target section, suggested action, cross-reviewer patterns, new analysis/literature needs, suggested revision order, and response-letter skeleton.
• Revised Manuscript Draft Package: revised draft/render paths, revision log mapped to comment IDs, resolved/unresolved/blocked items, response-to-reviewers draft, updated placeholders, source inputs, commands used, and recommended next mode.
• Response Package: revised manuscript paths, clean/tracked/change-log paths when available, response-to-reviewers letter, editor cover letter or resubmission note, comment-resolution checklist, updated QA Gate Report path, and journal resubmission checklist.
• Handoff note: final artifact paths, commands run, outputs changed, known limitations, and next human actions.

Workflow

Use this sequence for new projects, broad audit requests, or a full literature-to-manuscript run. It has three macro-phases: a mostly linear Phase 1 — Literature foundation; an iterative Phase 2 — Research iteration loop that cycles until results are publication-ready; and a mostly linear **Phase 3

Truncated - read the full file at https://github.com/guqingze/research-manuscript-workflow/blob/61672d686be4c9905ab1283c01af1d4c7a9367ce/SKILL.md.