Ma Manuscript Quarto

Workflow

The workflow has two phases: Outline first, then Write. Never skip Phase 1.

Phase 1: Outline & Checklist (MANDATORY before any writing)

Before writing any prose, build a complete outline that serves as the blueprint. The outline template is at assets/quarto/manuscript_outline.md — it contains 10 sections that must ALL be filled in with project-specific data.

Step 1.1: Initialize project structure

1. Initialize a Quarto project in 07_manuscript/.
   • Create 07_manuscript/_quarto.yml
   • Create 07_manuscript/index.qmd
2. Copy Quarto templates from assets/quarto/ and adapt to the project.
   • Copy assets/quarto/00_abstract.qmd → 07_manuscript/00_abstract.qmd
   • Copy assets/quarto/01_introduction.qmd → 07_manuscript/01_introduction.qmd
   • Copy templates 02-04 similarly
3. Copy assets/quarto/manuscript_outline.md to 07_manuscript/manuscript_outline.md.
   • Copy assets/quarto/manuscript_outline.md → 07_manuscript/manuscript_outline.md

Step 1.2: Gather evidence (read BEFORE filling outline)

4. Build a manuscript evidence map with scripts/build_evidence_map.py — review all analysis outputs.
   • Use scripts/build_evidence_map.py
   • Write to 07_manuscript/evidence_map.md
   • If the script fails: manually read 06_analysis/ R outputs, CSVs, and figure files to build the map.
   • If 06_analysis/ is incomplete: STOP. Return to /ma-meta-analysis to complete analysis first.
5. Initialize result_claims.csv with scripts/init_result_claims.py — map every result to its source.
   • Use scripts/init_result_claims.py
   • Write to 07_manuscript/result_claims.csv (columns: claim_id, outcome, effect_measure, estimate, ci_lower, ci_upper, p_value, i2, figure_ref, table_ref, r_script, citation_keys)
   • If the script fails: manually create the CSV with columns: claim_id, outcome, effect_measure, estimate, ci_lower, ci_upper, p_value, i2, figure_ref, table_ref, r_script, citation_keys.
6. Read ALL of the following before filling the outline:
   • 06_analysis/ — every R script output, CSV table, figure PNG
   • 05_extraction/extraction.csv — for study characteristics
   • 01_protocol/pico.yaml (L1-28: all fields) — for PICO details
   • 02_search/ — search dates, database counts
   • 03_screening/round-01/agreement.md — screening decisions, Cohen's kappa
   • 08_reviews/grade_summary.csv — GRADE summary if available
   • Prior reviews (search PubMed for existing systematic reviews on the topic)

Step 1.3: Fill in the outline (the core work of Phase 1)

7. Fill in every section of manuscript_outline.md:

   Section 1 — Project Info: Topic, journal, word limits, PROSPERO ID.

   Section 2 — Key Messages: Define 3-5 take-home messages. These drive the entire manuscript. Test: if a paragraph doesn't serve at least one key message, it shouldn't be in the paper.

   Section 3 — Narrative Arc: Define the story in 6 sentences (hook → gap → approach → finding → significance → bottom line). Test: read the 6 sentences aloud — they should tell a coherent story.

   Section 4 — Section Outlines:

   • Abstract: fill the data table with exact numbers from R outputs.
   • Introduction: plan paragraph-by-paragraph with specific citations.
   • Methods: fill PICO, databases, search dates, statistical details.
   • Results: fill one outcome block per quantitative result with claim_id, estimate, CI, p-value, I², figure/table refs, R script source.
   • Discussion: fill ALL subsections with minimum point counts:
     • Principal findings: >= 3 points
     • Topic-specific interpretation: >= 1 subsection with argument + evidence + implication
     • Comparison with prior work: >= 2 named prior studies/reviews
     • Limitations: >= 2 study-level + 2 review-level + 1 outcome-level + 1 statistical
     • Implications: >= 3 clinical + 3 future research (with specific study designs)
     • Conclusions: draft the 2-3 sentence conclusion

   Section 5 — Tables & Figures Plan: List every table and figure with source file, panels, and draft legends.

   Section 6 — References Plan: List ALL BibTeX keys that will appear in the manuscript.

   Section 7 — Word Count Targets: Set per-section targets matching the target journal.

   Section 8 — Supplementary Materials: Plan search strategies, PRISMA checklist, supplementary tables/figures.

   Section 9 — Pre-Writing Readiness Gate: Check ALL hard requirements (data, figures, tables, references, outline completeness).

Step 1.4: Validate and approve

8. Self-validate the outline:
   • Search for {{ in the file — must return 0 hits (no unfilled placeholders).
   • Verify Discussion has >= 3 points in each subsection.
   • Verify every outcome block in Results has claim_id, estimate, CI, p-value, figure ref.
   • Verify Section 9 (Readiness Gate) is fully checked.
9. Present the outline to the user for review.
   • Summarize: key messages, number of outcomes, number of tables/figures, word count targets.
   • Ask: "Is this outline approved? Any changes needed?"
10. Do NOT proceed to Phase 2 until the user explicitly approves.

Phase 2: Write from Outline

Once the outline is approved, write each section following it exactly.

Writing style: All prose MUST follow references/academic-writing-style.md. Key rules:

• AMA style (default) — superscript numbered citations, american-medical-association.csl, serial comma, generic drug names
• No contractions (do not, cannot — never don't, can't)
• No vague language (determine, not "figure out"; possibly, not "maybe")
• No imperative mood ("The analysis was performed" — not "Run the analysis")
• No sentence fragments in prose ("No data were available" — not "No data.")
• Passive voice for Methods/Results; active voice for interpretation
• Formal transitions (However, Therefore — not But, So)
• Precise terminology (adverse events, not side effects; mortality, not death)
• Complete statistics (every claim needs estimate + 95% CI + p-value)
• AMA numbers — numerals with units, spell out at sentence start, "%" not "percent"
• AMA abbreviations — define at first use in abstract AND body; no abbreviations in title
• No AI-flavored vocabulary — cross-check with human-write skill after writing

Writing order (this order is intentional — write data-driven sections first):

1. Methods (most formulaic, establishes scope)
2. Results (data-driven, references Methods)
3. Discussion (interprets Results)
4. Introduction (frames the story, written after you know the results)
5. Abstract (summary of everything, written last)

Step 2.1: Generate structural components

11. Generate the PRISMA flow summary with scripts/prisma_flow.py via uv run, optionally writing an SVG. Use --strict for final renders.
    • If the script fails: manually create PRISMA flow from screening/fulltext data.
12. Insert the search report and audit hashes into Methods with scripts/insert_search_report.py.
    • If the script fails: manually copy search report content into the Methods information sources section.
13. Generate Results paragraph stubs with scripts/build_result_paragraphs.py.
    • If the script fails: manually write paragraph stubs from result_claims.csv.
14. Build study characteristics table with scripts/build_study_characteristics.py.
    • If the script fails: manually extract from extraction.csv.
15. Insert the traceability table into Methods with scripts/insert_traceability_table.py.
    • If the script fails: manually create: protocol registered → N databases searched → N records → N screened → N included.

Step 2.2: Write sections (follow outline exactly)

16. Write Methods (02_methods.qmd):

    • Follow outline Section 4.3 point by point.
    • Include all statistical analysis sub-items.
    • Reference traceability table and PRISMA flow.
    • Checkpoint: verify every Methods paragraph maps to an outline checkbox.

17. Write Results (03_results.qmd):

    • Follow outline Section 4.4 in the specified writing order.
    • For each outcome: copy claim_id, estimate, CI, p-value, I² from the outline.
    • Every quantitative claim MUST include: effect estimate + 95% CI + p-value.
    • Reference the specific figure and table for each outcome.
    • Use [@key] citations from the outline's BibTeX key lists.
    • Checkpoint: run scripts/results_consistency_report.py — must have 0 missing items.

18. Write Discussion (04_discussion.qmd):

    • Follow outline Section 4.5 subsection by subsection.
    • Write ONLY the points listed in the outline. Do NOT improvise new arguments.
    • Each subsection must have the minimum word count specified.
    • Checkpoint: verify every Discussion claim traces to a Result.

19. Write Introduction (01_introduction.qmd):

    • Follow outline Section 4.2 paragraph by paragraph.
    • Ensure objectives match Methods and Results reporting order.
    • Checkpoint: verify objectives list matches Results section structure.

20. Write Abstract (00_abstract.qmd):

    • Follow outline Section 4.1 and the data table.
    • Every number MUST match the Results section exactly.
    • Checkpoint: cross-check every number in Abstract against Results.

Step 2.3: Assemble, validate, render

21. Assemble Results into 03_results.qmd with scripts/assemble_results.py (also inserts result_summary_table.md).
22. Populate the bibliography and ensure all [@key] citations in all QMD files have matching entries in references.bib.
23. Verify DOI existence with scripts/verify_doi.py:

    uv run ma-manuscript-quarto/scripts/verify_doi.py \
      --bib projects/<project>/07_manuscript/references.bib \
      --out projects/<project>/09_qa/doi_verification_report.md \
      --email "[email protected]"
    

    • Must exit with code 0 (>= 90% DOI coverage, 0 invalid DOIs).
    • For missing DOIs, review candidates and patch: add --patch --min-confidence 85.
    • If exit code 1: add missing DOIs manually or via --patch.
    • If exit code 2: fix invalid DOIs before proceeding.
24. Generate a results consistency report with scripts/results_consistency_report.py.
    • If any missing items: fix before proceeding.
25. Initialize the submission checklist with scripts/init_submission_checklist.py.
26. Run scripts/lint_qmd.py --dir 07_manuscript/ — must pass with exit code 0 (no errors).
    • If errors: fix with --fix flag, then re-run to confirm.
27. Sync, validate, and render with the all-in-one build script:

    bash ma-manuscript-quarto/scripts/build_manuscript.sh --project <name> --all
    

    Alternatively, use Makefile: make all from 07_manuscript/.
    • If render fails: check Quarto error output, fix broken references/includes, re-render.

Step 2.4: Post-writing validation

28. Run cross-section consistency checks (outline Section 10):
    • Abstract numbers match Results numbers exactly.
    • Introduction objectives match Methods match Results reporting order.
    • Every figure/table referenced in text exists.
    • Every Discussion claim traces to a Result.
    • Conclusions contain no new findings.
    • Word counts within journal targets.
    • All citation keys resolve.
29. Update the outline: mark all checklist items as done, fill in actual word counts in Section 7.
30. Report to user: section word counts, any issues found, rendered output files.

Build & Sync Workflow

Two build options: build_manuscript.sh (recommended, all-in-one) or Makefile (render only).

build_manuscript.sh (Recommended)

All-in-one validation + sync + lint + render script. Runs standalone without AI — output goes to stdout.

# From repo root:
bash ma-manuscript-quarto/scripts/build_manuscript.sh --project <name>           # Validate only (fast)
bash ma-manuscript-quarto/scripts/build_manuscript.sh --project <name> --fix      # Auto-fix lint
bash ma-manuscript-quarto/scripts/build_manuscript.sh --project <name> --render   # Validate + render
bash ma-manuscript-quarto/scripts/build_manuscript.sh --project <name> --all      # Fix + render
bash ma-manuscript-quarto/scripts/build_manuscript.sh --project <name> --render --formats docx  # DOCX only

7-step validation pipeline (all results to stdout):

Exit codes: 0 = all passed, N = number of errors found.

No --project? Lists all available projects:

$ bash ma-manuscript-quarto/scripts/build_manuscript.sh
Available projects:
  --project hrd-parp-inhibitors
  --project ici-breast-cancer

Why Sync?

Analysis scripts in 06_analysis/ produce figures (PNG) and tables (PNG + CSV + HTML + DOCX via gt/flextable). The manuscript in 07_manuscript/ references local copies so Quarto can embed them. The sync step copies the latest outputs before every render, ensuring the manuscript always reflects current analysis.

Makefile (Alternative)

For projects that prefer make, create a Makefile in 07_manuscript/:

.PHONY: all html pdf docx clean sync

ANALYSIS_DIR := ../06_analysis