a-green-hand-jack/paper-writing-contract-planner

Paper Writing Contract Planner

Create the paper's writing contract: a durable agreement about what the paper is, what each section must do, which claims are allowed, what evidence each claim requires, and how later writing skills should execute the draft. This skill plans the "paper formula" before prose writing.

Use this skill for:

• locking the target venue, paper archetype, and positioning
• choosing the section order and paragraph roles
• mapping claims to required evidence slots
• assigning jobs to figures, tables, captions, and result paragraphs
• defining related-work boundaries and limitation policy
• selecting exemplar patterns and writing style rules
• defining writing-layer permissions for layout, fluency, argument, technical consistency, style consistency, venue adaptation, and final polish
• forbidding unsupported claims, tone, or result language
• creating or updating paper/.agent/writing-contract.md

Do not use this skill to write full paper prose. Use paper-writing-assistant after the contract exists. Use paper-writing-memory-manager after creating or updating the contract so section status, dependencies, style rules, and open writing threads reflect the new agreement. Use paper-positioning-planner first if the primary contribution is still undecided. Use paper-evidence-board if the main task is a claim/evidence inventory. Use experiment-design-planner when missing evidence needs a runnable experiment plan.

Writing Phase Entry Point

This is the recommended starting skill for the writing phase. Typical sequence:

paper-positioning-planner       ← decide what the paper sells (if not settled)
paper-writing-contract-planner  ← lock archetype, section order, evidence slots  ← START HERE
paper-writing-memory-manager    ← initialize section ledger and dependencies
paper-writing-assistant         ← draft prose section by section
  └─ paper-introduction-argument-writer   ← intro-specific argument chain
  └─ method-section-explainer             ← method prose and notation
  └─ experiment-story-writer              ← results prose from tables/figures
  └─ related-work-positioning-writer      ← novelty-boundary related work
  └─ limitations-scope-writer             ← limitations and scope caveats
  └─ abstract-title-contribution-writer   ← abstract/title after sections exist
paper-draft-consistency-editor  ← align all sections before submission

Skip paper-positioning-planner only if the paper archetype, primary claim, and venue are already settled. Run paper-draft-consistency-editor at least once before submitting.

Skill Directory Layout

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── contract-schema.md
│   └── update-protocol.md
└── templates/
    └── writing-contract.md

Progressive Loading

• Always read references/contract-schema.md and templates/writing-contract.md.
• Read references/update-protocol.md when updating an existing contract or when the draft/results changed.
• Read paper-writing-assistant/references/evidence-recipes.md when available and the contract needs archetype-specific evidence slots.
• Read paper-writing-assistant/references/style-selection.md and paper-writing-assistant/references/exemplar-index.md when venue/topic style or exemplar patterns matter.
• Read paper-writing-assistant/references/paper-quality-heuristics.md when the contract needs quality gates for core idea, readability, evidence integrity, or figure/table interpretation.
• Read or update paper/.agent/writing-memory/ through paper-writing-memory-manager when the contract changes section order, paragraph roles, claim strength, writing layers, style rules, notation rules, or forbidden claims.
• Read paper/.agent/writing-style.md, paper/.agent/notation-contract.md, and paper/.agent/writing-memory/style-and-terminology.md when present.
• Read paper-positioning-planner outputs when present, such as positioning reports, claim decisions, or narrative architecture.

Core Principles

• A writing contract is a constraint file, not a prose draft.
• Choose one primary archetype and at most one secondary archetype.
• Every main claim needs a section location, evidence slot, and allowed wording strength.
• Every section needs a job. Every important paragraph needs a role.
• Every main figure/table needs a paper job before captions are polished.
• Missing evidence should become an explicit placeholder, action, narrowed claim, or forbidden claim.
• The contract should identify the paper's dominant sell as insight, performance, or capability, then make every section support that sell.
• The contract should make evidence-integrity risks visible: compute, data, training duration, tuning budget, hardware, prompt, evaluation, and selection rules belong in evidence slots when they affect comparisons.
• The contract should be compact enough to stay useful while drafting.
• Later writing should follow the contract unless new evidence changes the contract first.
• Later writing should declare the active writing layer and protect the invariants assigned to that layer.

Step 1 - Gather Inputs

Find:

• paper root: paper/, current directory, or user-provided path
• existing paper/.agent/writing-contract.md
• paper draft files: main.tex, paper.tex, sections/*.tex
• project memory: memory/claim-board.md, memory/evidence-board.md, memory/action-board.md
• paper-local state: paper/.agent/paper-evidence-board.md, paper/.agent/paper-status.md, paper/.agent/provisional-results.md
• positioning reports, result reports, figure/table maps, reviewer risks, and literature notes

If the user provides only an idea, produce a draft contract and mark uncertain fields as TBD or needs-decision.

Step 2 - Decide Contract Mode

Use one of:

• create: no contract exists or the paper is being repositioned
• update: revise an existing contract after new results, new venue, new claims, or draft changes
• audit: check whether a contract matches the current draft and evidence

If no mode is specified, default to create when no contract exists and update when one exists.

Step 3 - Select Archetype and Structure

Read references/contract-schema.md.

Choose:

• primary archetype: method, theory-guided method, empirical study, benchmark/dataset, systems/tooling, analysis/diagnostic, application, negative result/limitation, or hybrid
• target venue and audience
• dominant contribution type: insight, performance, or capability
• section order
• per-section job
• paragraph roles for introduction, method/setup, experiments/results, related work, and limitations

If the archetype is uncertain, write the competing options and the evidence needed to choose, but still pick a provisional primary archetype for the contract.

Step 4 - Map Claims to Evidence Slots

For every main and secondary claim, record:

- Claim ID:
- Claim wording:
- Allowed strength:
- Paper locations:
- Required evidence slots:
- Current evidence status:
- Missing evidence action:
- Forbidden overclaim:

Use evidence slot statuses: filled, user-stated, planned, running, provisional, missing, contradicted, or not-needed.

If an evidence slot is a blocker for the selected archetype, mark the corresponding claim as blocked or narrowed.

Step 5 - Define Writing Rules

Specify:

• title direction
• abstract moves
• intro paragraph recipe
• readability gates: logical strength, defensibility, confusion-time reduction, and information density
• main figure/table roles
• result section order
• related-work boundary
• limitation policy
• provisional result policy
• writing-layer policy: what layout, fluency, argument, technical-consistency, style-consistency, venue-adaptation, and final-polish edits may change
• allowed tone and forbidden tone
• terms, method names, dataset names, and baseline names to use consistently
• exemplar patterns to borrow, if any

Do not include long exemplar quotes.

Step 6 - Write or Update Contract

Use templates/writing-contract.md.

Save to:

paper/.agent/writing-contract.md

If there is no paper/ directory and the current directory is the paper repo, save to:

.agent/writing-contract.md

When updating, preserve useful stable decisions and add a compact change note instead of rewriting history.

Step 7 - Route Follow-Ups

Route unresolved items:

• paper-writing-assistant: write or revise sections under the contract
• paper-writing-memory-manager: initialize or update writing memory after contract creation or revision — record contract version, locked section order, evidence slots per claim, forbidden claims, writing-layer permissions, notation rules, and which sections are now unblocked for drafting
• paper-evidence-board: synchronize claim/evidence/action IDs
• experiment-design-planner: plan missing evidence slots
• baseline-selection-audit: defend required baselines
• figure-results-review: validate figure jobs and captions
• table-results-review: validate table jobs and provenance
• paper-positioning-planner: revisit primary archetype or claim scope
• paper-reviewer-simulator: stress-test the contract before full drafting

Final Sanity Check

Before finalizing:

• one primary archetype is selected
• one dominant contribution type is recorded or explicitly marked unresolved
• section order and paragraph roles are explicit
• main claims have evidence slots and allowed strength
• evidence-integrity fields cover comparison-affecting compute, data, tuning, hardware, evaluation, and selection rules
• missing blocker evidence creates actions or narrowed claims
• figure/table jobs are defined before prose polishing
• related-work and limitation boundaries are explicit
• unsupported claims and forbidden tones are listed
• writing-layer permissions and protected invariants are explicit enough for later editors
• output path and next writing action are clear