plan

name	plan
description	Plan a literature review before drafting. Build a lean evidence-bound, taste-gated package using references.bib, reference-map.json, review-plan.md, evidence-ledger.md, and table-figure-plan.md.

Review Planning Before Drafting

Use this skill to turn a workspace, topic, outline, candidate paper list, or user framework into a lean evidence-bound writing plan. Do not draft manuscript prose.

A plan must pass two tests: evidence reliability and editorial taste. If the evidence is thin, run targeted acquisition or return REPLAN_REQUIRED. If the structure is bloated, over-framed, over-visualized, or likely to produce mechanical prose, return REPLAN_REQUIRED with cause editorial_overbuild. Do not solve structural overgrowth by retrieving more papers.

Canonical files

Required: references.bib, reference-map.json, review-plan.md, evidence-ledger.md, table-figure-plan.md.

Optional: acquisition-log.md only when retrieval, trial search, or citation-network work occurred; sidecars/ only for raw auxiliary outputs.

references.bib is the citation-key authority. Compatibility files are generated only when a legacy tool explicitly requires them and must be marked as derived.

Required inputs

Record or safely infer: workspace, title/topic, language, article type, target journal/audience/style, scope profile, word range, reference range, display-item budget, scale-floor rule, user framework, candidate papers/PMIDs/DOIs/notes, must-keep topics, exclusions, and external-retrieval policy. Record assumptions in review-plan.md.

Allowed scope profiles: critical_review, full_review, focused_review, mini_review.

Workflow

1. Diagnose workspace

Check corpus size, stale files, unstable identifiers, missing L3/full text, unresolved records, duplicates, retractions, and whether external calibration is needed. Local search is orientation only. L3 is not a substitute for L4-backed evidence on controversial, clinical, or quantitative claims.

2. Set the article contract first

Before outlining, write in review-plan.md:

• article type, target journal/audience, style baseline, scope profile
• target word range and reference range
• main-text display-item budget and allowed boxes
• scale floor and anti-padding rule, if the user specifies minimum scholarly scale
• clinical/trial layer: required | optional | supplementary_only | not_applicable
• citation-network layer: required | targeted_check | not_applicable

Default calibration unless overridden:

• critical_review: 8,000-12,000 words, 80-110 references, 3-5 display items
• focused_review: 6,000-10,000 words, 60-100 references, 3-5 display items
• mini_review: 4,000-6,000 words, 35-70 references, 2-4 display items
• full_review: 12,000-16,000 words, 100-140 references, 4-7 display items

full_review must not automatically maximize references, figures, tables, or trial layers.

Scale Floor and Anti-Padding Rule

If the user requests a substantive Review floor, declare it in the Article Contract as a quality-constrained target range, not as permission to pad. For example:

• word target: approximately 12,000 words; acceptable range 11,500-12,500 unless journal rules differ
• cited-reference target: approximately 100 unique high-value citable references; acceptable range 90-110 unless journal rules differ
• display items: normally 4-5 main-text figures/tables/boxes combined unless the journal requires otherwise

The scale floor must be reached through analytical depth, evidence comparison, mechanistic explanation, clinical interpretation, and synthesis. It must not be reached by repeated caveats, low-value historical catalogue material, decorative citations, registry-only/abstract-only/metadata-only records, generic background paragraphs, display-item inflation, or multiplying frameworks, ladders, funnels, matrices, roadmaps, or readiness criteria.

If the plan cannot support the target word/reference range without padding or conceptual overgrowth, return REPLAN_REQUIRED with cause scale_floor_recalibration or editorial_overbuild; do not approve a padded plan.

3. Normalize references

Repair/export references.bib; create reference-map.json with one stable citekey per retained record. Minimum fields: citekey, title, year, PMID/DOI, corpus layer, bibliographic validity, review use, citation policy, sections, full-text status, notes. Use citation policies: must_cite, cite_if_relevant, background_only, do_not_cite. Never use UUIDs, PMIDs, DOIs, or directory names as planning identifiers.

4. Choose coverage mode

Use the smallest coverage mode that supports the article contract. critical_review is thesis-led and selective; full_review is coverage-first but still narrowed; focused_review is exhaustive inside scope; mini_review is representative and compact. Evidence gaps justify acquisition. Overbreadth and mechanical structure require compression.

5. Audit the user framework

For each supplied heading, axis, or hypothesis, choose: keep, merge, split, rename, reposition, compress, defer_to_supplement, or drop. Record: user unit, action, carried-forward form, evidence status, editorial reason, and cut rule.

Taste Gate

Run before approving the outline.

1. Inspiration pass. If examples exist under example/ or reference/, read 2-4 target-style reviews for rhythm, compression, pacing, and judgment density only. Do not import content, metaphors, structures, or claims.
2. Thesis-before-taxonomy. The plan must reduce to 1-2 positive propositions. It fails if its main value is only to classify evidence, provide a framework, or list validation levels.
3. Adjudication. Every major section must make a judgment: a claim, ranking, contrast, or interpretive shift. A section cannot mainly summarize, balance, or warn.
4. Anti-mechanical forecast. Scan planned headings and display titles for excessive apparatus language: framework, ladder, hierarchy, funnel, matrix, roadmap, criteria, readiness, standard, evidence appraisal, validation standard, evidence boundary, claim license. These terms are allowed sparingly, but fail the plan if they become parallel organizing devices.
5. Surface anti-leakage. Planning vocabulary such as section contract, cut rule, pair ID, planned asset, claim license, evidence boundary, table-only, and currentness-only must stay internal.

Required review-plan.md fields: Positive thesis, Primary conceptual axis, TASTE_GATE_STATUS.

Concept Budget

Mandatory unless the user or journal explicitly requires otherwise:

• primary conceptual axis: max 1
• secondary evidence-classification device: max 1
• roadmap/funnel/matrix/hierarchy/readiness model: choose 0-1 total
• main-text definition boxes: normally max 1
• new coined terms: max 2, only if they reduce complexity

Failure conditions: competing frameworks, several ladders/funnels/matrices/roadmaps, separate schemas for methods/clinical/evidence/future sections, or any plan that reads like a reporting guideline rather than a review argument. Return REPLAN_REQUIRED with cause editorial_overbuild.

Cut Rules

Every section card must include at least one binding cut rule, such as: do not repeat the global caveat; do not summarize history chronologically; do not include registry-only records in main text unless they change the thesis; do not create a table if prose is more efficient; do not introduce a new framework.

External acquisition

Use external acquisition only for real evidence gaps: missing landmarks, missing recent papers, missing supplied identifiers, unsupported controversies, mechanisms, or display items. Do not retrieve more literature to solve overbreadth, mechanical prose, over-framing, decorative citations, or structural sprawl.

If retrieval occurs, acquisition-log.md records only decision-relevant query branches, candidate counts, inclusion/exclusion decisions, retained citekeys, and unresolved gaps.

Planning file schemas

review-plan.md

Must include: task brief; article contract; scale floor and anti-padding rule if applicable; positive thesis and concept budget; scope and boundaries; framework audit; final outline; section cards; corpus summary; evidence gaps and true research gaps; writing contract; handoff.

Each section card has only six fields:

• Section ID / Title
• Thesis move
• Evidence base
• Key citation keys
• Display item, if needed
• Cut rule

The writing contract must include allowed evidence uses, forbidden manuscript rhetoric, word/reference/display budgets, scale-floor and anti-padding rules, cut rules, and plan-gap return conditions.

evidence-ledger.md

Selective source of truth. Always include corpus layers, core/contested/weak evidence, excluded/unresolved records, and trial evidence if retained. Full section evidence tables are required only for core, contested, weak, or easily misused evidence. Background-only papers do not need full claim ledgers.

Minimum tables:

• Corpus Layers: citekey, layer, status, review use, citation policy, primary section, full-text status, L3 mode
• Core / Contested / Weak Evidence: section, citekey, evidence type, usable claim, key limitation, evidence origin

table-figure-plan.md

This is a display plan, not a table-figure pairing machine. Include display budget, main-text display items, supplementary-only assets, and an optional pairing matrix only when pairing improves synthesis.

Rules: no one-to-one table/figure requirement; no decorative assets; Pair IDs internal only; delete any display item that creates a new conceptual axis; every display item must make a judgment that prose cannot make more efficiently.

Trials and citation network

Trials are used only when clinical development is central or explicitly useful. Status: REQUIRED | OPTIONAL | SUPPLEMENTARY_ONLY | NOT_APPLICABLE | BLOCKED. Trial records are parallel evidence and must not drive main-text structure unless clinical development is central.

Citation-network analysis is conditional. Status: REQUIRED | TARGETED_CHECK | NOT_APPLICABLE | BLOCKED. Use it when field boundaries, landmarks, or lineages are uncertain; otherwise run targeted landmark/currentness checks.

Final check before approval

Evidence checks: retained citekeys exist in references.bib and reference-map.json; citable rows have bibliographic validity, review use, and citation policy; must_cite, core, and working papers map to sections; exclusions have reasons; trial/network status matches the article contract.

Editorial checks: one thesis and one primary axis; Concept Budget passed; Taste Gate passed; scale floor passed without padding if applicable; display budget not exceeded; every section has thesis move and cut rule; weak evidence types do not drive architecture; no section exists mainly for caution, taxonomy, or evidence policing; no asset exists only because a budget expected it; target word/reference ranges fit the journal.

If editorial checks fail, return REPLAN_REQUIRED with cause editorial_overbuild.

Final output

Return:

FRAME_STATUS: APPROVED | REPLAN_REQUIRED | BLOCKED
WORKSPACE: <name>
LANGUAGE: <language>
ARTICLE_TYPE: <type>
STYLE_BASELINE: <style>
REVIEW_SCOPE_PROFILE: <scope>
TARGET_WORD_RANGE: <range>
TARGET_REFERENCE_RANGE: <range>
DISPLAY_BUDGET: <n main-text items>
SCALE_FLOOR_STATUS: PASSED | FAILED | NOT_REQUESTED
TRIALS_STATUS: REQUIRED | OPTIONAL | SUPPLEMENTARY_ONLY | NOT_APPLICABLE | BLOCKED
CITATION_NETWORK_STATUS: REQUIRED | TARGETED_CHECK | NOT_APPLICABLE | BLOCKED
VALID_REFERENCE_COUNT: <n>
CORE_HYPOTHESIS: <1-2 sentences>
PRIMARY_CONCEPTUAL_AXIS: <one axis>
CONCEPT_BUDGET_STATUS: PASSED | FAILED
TASTE_GATE_STATUS: PASSED | FAILED
REFERENCE_POLICY: references.bib citation keys are canonical
CORPUS_COUNTS: universe / working / core / excluded / unresolved
HANDOFF_FILES: canonical files listed above
OPEN_GAPS: <NONE or explicit list>
NEXT_ACTION: ready_for_manuscript_drafting | run_targeted_acquisition | editorial_compression | return_to_user

If FRAME_STATUS is not APPROVED, do not permit downstream writing.