Medical Review Writer Architect

Source: https://github.com/aipoch/medical-research-skills

Medical Review Writer (Architect)

When to Use

• The user explicitly wants to write a medical review, narrative review, or long-form review based on PubMed evidence.
• The user accepts a multi-stage process of outline, search, chapter-by-chapter writing, verification, and formatting.
• The user needs real intermediate files, rather than generating the final long document in one shot within the conversation.

When Not to Use

• When the user only needs a summary, single paragraph review, or brief background introduction, do not launch the full workflow.
• When the user has no topic, target audience, language requirements, or project directory, do not start writing directly — first collect the minimum inputs.
• When the current task does not allow creating or modifying intermediate files, do not use this skill, as its core workflow depends on real files and state machine checks.

Required Inputs

Output Contract

• Primary output: Review_Final.md and Review_Final_Formatted.md.
• Intermediate files: outline.md, references.json, introduction.md, section_*.md, abstract.md, conclusion.md.
• Citation format: Body text uses only [PMID: xxx] as intermediate citations, with final formatting applied later.
• If the process is interrupted: Must state which stage was completed, what is missing, and mark as PARTIAL.

User Checkpoints

• After the outline is completed, the user must confirm before entering the search and writing stages.
• After each chapter passes verification, report the current chapter status and obtain user confirmation before proceeding to the next chapter.

Core Workflow

Strictly follow the six-step process below. Core mechanism: After each script execution, the terminal prints a [State Machine] prompt — strictly read the current state and follow the "next step suggestion."

Stage 1: Outline Construction (Outline)

1. Analyze the topic and plan 3-5 major chapters (Body Sections).
2. Critical mandatory requirement: The outline must be detailed down to the sub-heading level (i.e., ### 1.1, ### 1.2, etc.). Each major chapter must have 2-4 pre-planned sub-headings with distinct logical divisions — writing only to the ## 1. Chapter Name level is never permitted.
3. Create outline.md. Must include: Title, Introduction, Body Sections (including all sub-headings), Conclusion.
4. Confirm the outline with the user before proceeding to the next step.

Detailed instructions: See references/workflow-details.md Stage 1

Stage 2: Data Retrieval and Library Construction

1. Design search strategies for each chapter (must include Introduction)
2. Execute searches: python scripts/pubmed_search.py "QUERY" --section "introduction|section_1|..."
   • Naming convention: --section must strictly correspond to file names (e.g., use introduction NOT Intro, use section_1 NOT Section1_TP53) so subsequent scripts can auto-match
   • Batch retrieval: The script has batch PMID detail fetching enabled for improved efficiency
   • Rate limiting: Automatically controls approximately 1 request/second for stability and API compliance
   • Default count: --max defaults to 20 articles; adjust as needed
   • Safety check: Automatically handles missing PMID or title fields
   • Important: references.json should be saved in the project directory (e.g., TP53/references.json), not the skill directory
3. Check counts: Run python scripts/count_references.py
   • Target: Ensure total Unique PMIDs in references.json reach at least 150
   • If insufficient, optimize search terms and perform additional searches
4. Ensure each chapter has adequate literature support

Detailed instructions: See references/workflow-details.md Stage 2

Stage 3: Chapter-by-Chapter Writing

1. Read chapter references: python scripts/read_references.py "SectionName"
2. Create introduction.md (Introduction) and section_1.md, section_2.md, etc. for body sections
3. Format and word count requirements (refer to assets/Review_Final.md):
   • Never write an entire Section as a single long paragraph! Each major chapter (e.g., ## 1. xxx) must be divided into 2-4 specific sub-headings (e.g., ### 1.1 xxx).
   • Content under each sub-heading must be developed into detailed, coherent academic paragraphs — using simple bullet-point shorthand is not permitted.
4. Literature citation marking: Every objective academic claim needs literature support, using [PMID: xxx] format.
5. Write-as-you-search (Dynamic Retrieval): If you find insufficient evidence, immediately perform supplementary searches:
   • python scripts/pubmed_search.py "Specific Query" --section "CurrentSection"
6. Post-writing verification and supplementation:
   • After completing a chapter, verify: python scripts/check_section.py "section_1.md"
   • If the state machine indicates insufficient citations, perform supplementary searches with the --post-write parameter as suggested.
   • If the state machine indicates word count below the predetermined requirement (i.e., < 7000 characters), expand the content depth of each sub-heading as needed.
   • If the state machine detects dense citations (i.e., a single sentence containing > 2 references), expand and revise that sentence to discuss multiple references separately — stacking more than 2 references at the end of one sentence is prohibited.
   • Mandatory requirement: Once verification fully passes (no count/word-count/density warnings), you must report the current chapter's writing status to the user and ask whether to continue — proceed to the next chapter only after receiving explicit user approval.
7. Document revision mechanism: If revisions are needed to the already-formatted final document, never directly modify the version with hyperlinks. First run python scripts/revert_citations.py Review_Final_Formatted.md -o draft.md to revert to [PMID: xxx] format. Pay attention to the state machine output regarding reference count — if it indicates insufficient references (e.g., < 30), also use pubmed_search.py with the --post-write parameter to supplement with new literature during revision, then re-run the formatting script.
8. Format reference: The body section portions of assets/Review_Final.md

Detailed instructions:

• Workflow: references/workflow-details.md Stage 3

• Citation standards: references/citation-guide.md