| name | write |
| description | Draft a fact-grounded, taste-gated review manuscript from an approved lean planning package. Uses references.bib, reference-map.json, review-plan.md, evidence-ledger.md, and table-figure-plan.md; use only after plan is approved. |
Plan-Grounded Review Drafting
Use this skill only after planning is approved. It turns the planning package into one integrated manuscript at workspace/<name>/write.md. It is not for re-planning, adding papers, filling evidence gaps from memory, or expanding scope.
The manuscript must satisfy two contracts:
- Evidence contract: every factual, mechanistic, clinical, table, figure, and trial claim stays within the approved evidence boundary.
- Taste contract: the manuscript preserves the plan's positive thesis, concept budget, cut rules, word/reference/display budgets, scale-floor and anti-padding rule, and anti-mechanical constraints.
If the approved plan lacks Taste Gate, Concept Budget, target word/reference range, display budget, scale-floor rule when requested, or section cut rules, return to plan.
Required inputs
Read: references.bib, reference-map.json, review-plan.md, evidence-ledger.md, table-figure-plan.md, and acquisition-log.md if present. Read trials/** only if trials are required or retained. If any first-five canonical file is missing or contradictory, stop and return to plan. Compatibility files are advisory only.
Pre-drafting gate
Extract from review-plan.md: positive thesis, primary conceptual axis, secondary evidence device, forbidden parallel frameworks, target word range, target reference range, scale-floor and anti-padding rule, display budget, allowed boxes, section cut rules, trial status, citation-network status, Taste Gate status, and Concept Budget status.
Do not draft if FRAME_STATUS is not approved; Taste Gate or Concept Budget is missing/failed; target budgets are missing; a requested scale floor lacks an anti-padding rule; section cards lack thesis moves or cut rules; multiple frameworks/ladders/funnels/matrices/roadmaps remain; or required trial/network layers are incomplete. Return CONTENT_STATUS: BLOCKED_BY_PLAN and NEXT_ACTION: return_orchestrator.
Evidence boundary
Use only citable citation keys permitted by reference-map.json and evidence-ledger.md. Do not cite unresolved, duplicate-only, blocked-without-metadata, needs_metadata_fix, or not_citable records. must_cite papers appear when their assigned claim/section requires them; cite_if_relevant papers may be omitted when no claim needs them. background_only papers cannot carry central claims. Excluded-but-citable, conflicting, taxonomy-boundary, adjacent, and method papers may be cited only for their assigned role. Trial records support currentness, phase, endpoint, recruitment, safety, or landscape claims; they do not replace papers. Use Pandoc citations such as [@Smith2024].
If a claim, section, table, figure, or trial statement lacks plan support, stop with a plan-gap note.
Taste boundary
Do not expose planning machinery in prose, headings, tables, or legends. Forbidden manuscript rhetoric: evidence boundary, claim license, section contract, cut rule, pair ID, planned asset, table-only, currentness-only, must-cite, concept budget, taste gate, framework audit.
Use apparatus terms only when scientifically necessary and allowed by the concept budget: framework, ladder, hierarchy, funnel, matrix, roadmap, criteria, readiness, standard, validation. If these terms begin to organize multiple sections in parallel, return to plan for editorial compression.
Manuscript rules
- Write from thesis moves, not evidence tables. Each section starts from its approved thesis move. Avoid “This section discusses,” “This review provides,” “The following framework,” and “Table 1 compresses.” Use conclusion-led scientific statements.
- Convert caution into positive interpretation. A limitation should become a claim about what the evidence can support. Do not make repeated caveats the prose engine.
- Respect the concept budget. Do not invent new schemas. Default: one primary axis, one secondary evidence device, 0-1 roadmap/funnel/matrix/hierarchy/readiness model, 0-1 definition box, only approved coined terms.
- Apply section cut rules. Obey cuts even when extra evidence exists: compress chronology, move registry-only material to Supplementary, delete repeated caveats, avoid redundant tables, block new frameworks.
- Maintain scale without padding. Draft to approved word/reference/display budgets. If the plan requests a substantive floor, aim for that scale through analytical depth, evidence comparison, mechanistic explanation, clinical interpretation, and synthesis. Do not solve an under-length or under-cited draft by adding repeated caveats, decorative background, overlapping citations, low-yield registry/abstract-only/metadata-only material, weak display items, generic background, or chronological catalogues. If the target scale cannot be reached without padding, return to
plan for scale-floor recalibration.
- Use display discipline. Use only approved display items within budget. Tables and figures need no one-to-one pairing unless the plan requires it. Pair IDs are internal. A display item must make a judgment prose cannot make more efficiently.
- Control weak evidence. Registry-only, abstract-only, and metadata-only records must not drive section architecture. State boundaries once when necessary, not repeatedly.
- Avoid AI cadence. Reduce repeated “not A but B,” defensive should/must/cannot/may/might/could, empty “Furthermore/Moreover/It is worth noting/Taken together,” and dash-heavy compression.
The target voice is a specialist who has weighed the evidence and is willing to rank interpretations.
Citation assets
Ensure valid YAML:
---
bibliography: references.bib
csl: csl/nature.csl
link-citations: true
reference-section-title: References
---
Use workspace CSL when available.
Drafting workflow
Manuscript prose may be delegated only to autor write-agent. Deterministic scripts are allowed for formatting, citation checks, QA inspection, figure-status checks, export, and document inspection.
Run:
autor write-agent orchestrate <name>
autor write-agent write <name>
autor write-agent polish <name>
autor write-agent critic-context <name> --round <N>
Use autor write-agent orchestrate <name> --clean only when restarting from the approved planning package.
Canonical manuscript: workspace/<name>/write.md. Do not use a canonical sections/ merge workflow; variants/ are non-canonical.
Audit and revision
Run autor write-agent audit <name>. Audit citation validity, must-cite coverage, word/reference/display budgets, scale-floor compliance without padding, Concept Budget compliance, repeated apparatus terms, defensive caveats, planning-term leakage, and section cut-rule violations.
If a section is locally weak, rerun that section. If the draft is overbuilt because the plan is overbuilt, return to plan with cause editorial_overbuild. Polish may improve language, rhythm, transitions, compression, and process-trace removal, but must not add facts, citations, sections, or new frameworks/ladders/funnels/matrices/readiness schemas.
Quality gates
Run critic and check for substantial manuscripts. Before promotion, run:
autor ws citation-coverage <name> --manuscript workspace/<name>/write.md --require must_cite --fail-if-missing
QA checks: evidence fidelity, citation validity, unsupported claims, weak-evidence misuse, trial integration, Concept Budget, Taste Gate, budgets, display-item value, defensive language, planning-term leakage, through-line, and dash overuse.
Routing: evidence/citation failures return to plan or targeted acquisition; inability to meet scale without padding returns to plan with scale_floor_recalibration; overbuilt structure, too many concepts, display inflation, or evidence-governance tone returns to plan with editorial_overbuild; local style only stays in write.
Figures and export
Generate only figures marked main_text_required or ready and only within the approved display budget. Do not assume a full review requires 7-8 figures. Use approved plotting/plot-enhance workflows, source figures from planned citekeys, save under workspace/<name>/figure/, and write figure-manifest.json. Before export, run autor ws figure-status <name> --fail-if-missing.
After QA passes, promote write.md to final.md. Export with Pandoc when requested:
cd workspace/<name> && pandoc final.md --citeproc -o final.docx
Final output
CONTENT_STATUS: APPROVED | REWRITE_FROM_WRITE | RETURN_TO_ORCHESTRATOR | BLOCKED_BY_PLAN | EXPORT_BLOCKED
WORKSPACE: <name>
FAILED_STAGE: none | preflight | write | polish | critic | check | figure | export
CAUSE_CLASS: none | missing_input | plan_gap | evidence | structure | style | citation | editorial_overbuild | figure_failure | export_failure
REFERENCE_POLICY: references.bib citation keys used throughout
TARGET_WORD_RANGE: <range>
TARGET_REFERENCE_RANGE: <range>
DISPLAY_BUDGET: <n main-text items>
SCALE_FLOOR_STATUS: PASSED | FAILED | NOT_REQUESTED
CONCEPT_BUDGET_STATUS: PASSED | FAILED | MISSING
TASTE_GATE_STATUS: PASSED | FAILED | MISSING
MANUSCRIPT_FILES: write.md, final.md if created, final.docx if created
QA_FILES: critic-ticket.md/check-report.md if created
OPEN_GAPS: <NONE or explicit list>
NEXT_ACTION: stop | rerun_write | return_orchestrator | return_to_plan_for_editorial_compression | export_after_user_approval
