SuperAPI AI Directory
Partner中文AI newsFavorites
Skillswriting-plans

writing-plans

Writing & research

View repository

Updated 10-16 09:29

About this skill

Writing Plans

Overview

Convert an approved IMRAD outline into an executable task list for drafting. Input: .writing/outline.md (structure + key claims), .writing/metadata.yaml (reporting guideline + Zotero config), .writing/claims/section_*.md (stub claims per section). Output: .writing/plan.md — the single source of truth for drafting. The plan enumerates per-section prose tasks, per-figure generation tasks, per-table assembly tasks, an explicit dependency table, and a Parallelism Groups analysis that the drafting skill consumes when deciding how many sections to draft in parallel.

Write comprehensive plans assuming the drafter has zero context for the paper's argument and questionable taste. Document everything they need: which files to read and write for each task, which claims back each paragraph, how to verify. Bite-sized tasks. Claim-first. Frequent commits.

Announce at start: "I'm using the writing-plans skill to decompose the outline into an executable plan."

Context: Optionally runs in a dedicated worktree (user chooses during brainstorming).

Save plan to: .writing/plan.md

Claim-first protocol: see superpower-writing:main §Claim-First Protocol.

When to Use

  • outlining skill has produced .writing/outline.md and stub claims/section_*.md files, and the user is ready to draft.
  • User explicitly requests "make a writing plan", "decompose sections into tasks", "/writing:plan".
  • When a round of review introduces new sections or substantially new claims — re-plan the impacted subset rather than re-planning the whole paper.

Do NOT invoke this skill before outlining completes. A missing or TODO-laden outline means the plan has nothing to bind to — abort and route back to outlining.

Scope Check

If the outline covers multiple independent papers (e.g., a methods paper plus an applications paper sharing one outline doc), stop and suggest splitting it into separate plans — one per paper. Each plan should produce a detailed, evidence-backed manuscript skeleton for one paper on its own.

Historical Archive Check

Before writing the plan, check for relevant historical archives:

${CLAUDE_PLUGIN_ROOT}/scripts/archive-search.sh "<keyword>"
  1. If relevant archives are found, read the full archive directory (especially summary.md, findings.md) and incorporate relevant lessons into the plan.
  2. If none are relevant or no archives exist, skip silently.

Checklist

  • Preconditions verified: .writing/outline.md, .writing/metadata.yaml (no TODO), claims/section_*.md all exist
  • File structure locked: manuscript/ filenames enumerated with their stems matching claims/
  • Structure confirmed with user (write set + section choices) before authoring tasks — skip the prompt only for small unambiguous outlines
  • Per-section tasks written (draft + verify-claims + internal-review triplet per section)
  • Per-figure tasks written (one per schematic; delegates to scientific-schematics)
  • Per-table tasks written
  • Dependency table written (Methods → Results; Intro ↔ Discussion loose coupling; Abstract last)
  • Parallelism Groups analysis written
  • Evidence Gap Summary written (if outline carries [NEEDS-EVIDENCE] markers)
  • Self-review run inline (spec coverage, placeholder scan, type consistency, evidence gaps)
  • Execution handoff via AskUserQuestion (dynamic workflow vs manual batch)

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

  • "Resolve evidence for each stub claim in section_02_methods.md" — step
  • "Flip each resolved claim STATUS: stub → evidence_ready" — step
  • "Draft prose for section, reading writing-principles.md and style-cautions.md for guidance" — step
  • "Precede each load-bearing paragraph with a % claim: <id> LaTeX line comment" — step
  • "Commit" — step

The claim-first protocol is the writing-domain analog of test-first: each draft task's Step 1 is always "resolve claim evidence"; the Write tool call only appears after evidence is ready. The PreToolUse enforcement hook at ${CLAUDE_PLUGIN_ROOT}/hooks/enforce-claims.sh blocks writes against stub-status claims at the harness level, so a plan that sequences writes ahead of evidence resolution will fail at execution time — preempt that here.

Process

Step 1: Verify preconditions

Stop and route back to the correct upstream skill if any precondition fails:

  1. .writing/outline.md exists and is non-empty. If missing → route to outlining.
  2. .writing/metadata.yaml has no TODO top-level keys (except multi-author v1 YAGNI list). If TODO present → instruct user to finish outlining/metadata pass first.
  3. .writing/claims/ contains one section_<NN>_<slug>.md per section listed in outline.md. If missing → route to outlining.
  4. .writing/manuscript/ subdir exists (created by init-writing-dir.sh).

Step 2: File-structure pass

Before task decomposition, list the exact manuscript files the plan will write to. One file per IMRAD section, default layout:

.writing/manuscript/
  00_abstract.tex
  01_introduction.tex
  02_background.tex       # CS / ML / systems default; omit for IMRAD-strict
  03_methods.tex
  04_results.tex
  05_discussion.tex
  06_conclusion.tex
  07_related_work.tex     # CS / ML / systems; placement varies by venue
  08_acknowledgments.tex  # optional

Optional sections (Supplementary, Acknowledgments, Data Availability Statement) appear only if the outline calls for them; IMRAD-strict medical/biology papers omit Background and Related Work. Each NN_slug.tex pairs 1:1 with claims/section_NN_<slug>.md — stems match exactly. File-structure pass output goes into the plan header so readers see the write set before tasks.

Design units with clear boundaries. Each file should have one clear responsibility. Prefer smaller, focused files over large files that do too much. Split by responsibility (a section is a claim set + prose), not by technical layer.

Step 2b: Confirm structure before committing the plan

The write set and section structure are the load-bearing decisions of the whole plan — every task, dependency edge, and parallelism group derives from them. Before authoring the full task decomposition (Steps 4–11), surface them for a quick user confirmation so structural mistakes are caught while they are still cheap to fix:

  1. Present the proposed manuscript file write set (the NN_slug.tex list from Step 2), the reporting guideline detected in metadata.yaml, and any non-default section choices (Background included/omitted, Related Work placement, optional sections, graphical abstract present/absent).
  2. Confirm via AskUserQuestion — offer "Proceed with this structure" and "Adjust structure first" — unless the outline is small and unambiguous (≤3 sections, no optional sections, default IMRAD layout), in which case state the structure in one line and proceed without a prompt to avoid friction.
  3. If the user adjusts, revise the write set and re-run this confirmation before continuing.

This is a structural gate only — do not draft prose, resolve claims, or write task bodies here; that work belongs to Steps 4–11. The end-of-skill Execution Handoff (Step 12) remains the separate, mandatory gate over how the plan executes.

Step 3: Auto-create .writing/

When writing a plan, automatically create the .writing/ directory if it does not already exist:

${CLAUDE_PLUGIN_ROOT}/scripts/init-writing-dir.sh

This creates progress.md, findings.md, metadata.yaml, outline.md, and the manuscript/, claims/, figures/, reviews/, archive/ subdirs.

Note: The plan in .writing/plan.md is the single source of truth for plan content. Execution status is tracked via the Task Status Dashboard in progress.md.

Step 4: Write the plan document

Use this exact header template:

# <Paper working title> — Writing Plan

> **For Claude:** Execute this plan via the path chosen during Execution Handoff (see end of plan) — a Claude Code dynamic workflow or a manual batch session. Drafting mechanics live in `superpower-writing:drafting`.
> Writing dir: .writing/

**Goal:** Draft a detailed, evidence-backed IMRAD manuscript skeleton (for the human author to refine) covering <one-sentence paper thesis from outline.md>.

**Architecture:** Section-per-file under `.writing/manuscript/`, claim-first drafting enforced by PreToolUse hook `${CLAUDE_PLUGIN_ROOT}/hooks/enforce-claims.sh`, figures delegated to `superpower-writing:scientific-schematics`, citations resolved through the Zotero→network dual source of truth configured in `metadata.yaml`.

**Reporting guideline:** <CONSORT | STROBE | PRISMA | ARRIVE | none> (from metadata.yaml).

---

## File Write Set
<bulleted list of manuscript/*.tex and figures/*.pdf (or *.eps / *.svg) the plan produces>

---

## Tasks
<per-section / per-figure / per-table tasks — see templates below>

---

## Dependencies
<table>

---

## Parallelism Groups
<analysis>

---

## Evidence Gap Summary
<table — only if outline carries [NEEDS-EVIDENCE] markers>

---

## Self-Review
<inline checklist>

---

## Execution Handoff
<two options via AskUserQuestion: Dynamic Workflow / Manual Batch>

Steps 5-7: Per-section / per-figure / per-table task templates

Every section, figure, and table in the outline becomes a task (or task triplet) in the plan. The exact Markdown templates — per-section draft / verify / internal-review triplet, per-figure F task, per-table T task — live in references/task-templates.md. Read that file when generating the Tasks block of .writing/plan.md; copy the templates verbatim, substituting the IMRAD section letter (I/M/R/D/C/A) and numbering. The graphical abstract gets a Task F0 only when the outline lists one (systems papers usually omit it).

Step 8: Dependency table

Write this table in the plan. It encodes which tasks block which, mirroring the IMRAD causal chain:

## Dependencies

| Task | Blocks | Rationale |
|------|--------|-----------|
| M.1 Draft Methods | R.1 Draft Results | Results reference Methods procedures; Methods must exist first. |
| M.1 Draft Methods | F<n> Figures that depict methodology | Figure captions cite Methods paragraphs. |
| R.1 Draft Results | D.1 Draft Discussion | Discussion interprets Results. |
| F<n> (data figures) | R.1 Draft Results | Results inline data figures; figure assets must exist first. |
| F0 Graphical Abstract | A.1 Draft Abstract | Graphical abstract often informs abstract framing. |
| I.1 Draft Introduction | D.1 Draft Discussion | Discussion closes loops opened in Introduction (shadow dependency — not hard). |
| All section drafts | A.1 Draft Abstract | Abstract summarizes the whole paper; draft last. |
| All section verifies | claim-verification | The skeleton-ready gate flags any claim still not STATUS=verified. |

The I.1 → D.1 edge is marked "shadow dependency" because Introduction and Discussion can be drafted concurrently (the dynamic workflow's parallel path) — but the user should expect a pass-two edit of Introduction after Discussion lands, since Introduction sets up loops that Discussion closes.

Step 9: Parallelism Groups

Every plan MUST include a parallelism analysis after the dependency table. Identify which tasks can run in parallel (no shared files, no shared claim sets, no sequential dependencies) and group them:

## Parallelism Groups

- **Group P0** (serial, blocks everything): precondition check + file-structure confirmation.
- **Group P1** (parallel, <k> tasks): M.1 Draft Methods, I.1 Draft Introduction, F0 Graphical Abstract, T<n> data-only tables (those not dependent on Results interpretation).
- **Group P2** (parallel, after P1): F<data-figures> Figures, R.1 Draft Results.
- **Group P3** (parallel, after P2): D.1 Draft Discussion, C.1 Draft Conclusion.
- **Group P4** (serial, after P3): A.1 Draft Abstract (summarizes everything).
- **Group P5** (parallel per section, after each draft): verify-claims tasks (M.2, R.2, D.2, …).
- **Group P6** (parallel per section, after verify): internal-review tasks (M.3, R.3, …).

**Parallelism score:** <N> of <Total> tasks run in parallel groups; max width <K> in Group P2.

Tips for maximizing parallelism:

  • Split work along section boundaries (each task touches a different manuscript file and a different claims file).
  • Introduction and Methods share no claim overlap → always parallel.
  • Figures can run in parallel with Results only if the figures do not depend on yet-to-be-written Results interpretation; outline.md should have pre-computed whether each figure is data-driven (parallelizable) or interpretation-driven (serial after R.1).
  • Verify-claims and internal-review are per-section independent.
  • Extract shared evidence-resolution steps into an early serial task only when the same citation set feeds multiple sections.

The parallelism score helps the user choose the right execution mode in the hand-off step.

Step 10: Evidence Gap Summary

Before self-review, scan .writing/outline.md and .writing/design.md (if present) for all [NEEDS-EVIDENCE] markers. For each one:

  1. Classify timing: before drafting (blocking) / during drafting / after first pass.
  2. Define what's needed: cohort size confirmation, missing reference, analysis re-run, dataset access, etc.
  3. Assign to a task: "before drafting" items become prerequisite tasks (numbered Task 0.x) in the plan; others are noted inline in the relevant task.

Include an Evidence Gap Summary section in the plan:

## Evidence Gap Summary

| # | Decision | Evidence Needed | Timing | Task |
|---|----------|-----------------|--------|------|
| 1 | Effect size for primary outcome | Re-run analysis with updated cohort | Before drafting | Task 0.1 |
| 2 | Reference for novel assay protocol | Locate or request from collaborator | During drafting | Task M.1 |

If no [NEEDS-EVIDENCE] markers exist in outline or design, skip this section silently.

Step 11: Self-Review (inline)

After writing the complete plan, review it yourself with fresh eyes. This is a checklist you run inline — not a subagent dispatch.

  1. Spec coverage: Does every section listed in .writing/outline.md have a draft / verify / review triplet? Does every figure in the outline have a matching F task? Does every table? Does the graphical abstract have a task? List gaps and fix.
  2. Placeholder scan: No TBD, TODO, add appropriate X, similar to task Y, or fill in details. Every task names exact files it reads and writes. No "similar to Task N" back-references — repeat the pattern, since the drafter may be reading tasks out of order.
  3. Type consistency: The claim ids used in the prose-drafting steps must match the ids declared in claims/section_*.md files produced by outlining. Section numbering (02_methods) must match across the plan. A claim id referenced as METH-3 in Task M.1 but as methods-3 in Task M.2 is a bug.
  4. Evidence gaps: Are [NEEDS-EVIDENCE] items from outline/design tracked and properly timed in the Evidence Gap Summary?

If any check fails, fix inline. No need to re-review — just fix and move on. If a spec requirement has no task, add the task.

Placeholder ban (part of the self-review): every step must contain the actual content a drafter needs. Reject and rewrite any of the following on sight — they are plan failures:

  • "TBD", "TODO", "implement later", "fill in details", "draft later"
  • "Add appropriate citations" / "add evidence" / "handle edge cases"
  • "Write the Methods prose" without naming the exact claims file, outline section, and target manuscript path
  • "Similar to Task N" — repeat the pattern, since the drafter may be reading tasks out of order
  • Steps that describe what to do without showing how (for evidence-resolution steps, list the exact claim ids and resolution mechanism: Zotero, DOI lookup, manuscript re-check)
  • References to claims, figures, or tables not defined in any task or in claims/section_*.md

Step 12: Execution Handoff via AskUserQuestion

After saving the plan and completing the self-review, present the execution strategy via AskUserQuestion. Both options always shown.

  • Claude Code Dynamic Workflow (recommended for multi-section papers) — ask Claude to run a workflow that executes .writing/plan.md (include the word "workflow" in the request so Claude writes one), or turn on /effort ultracode. The workflow drafts independent sections in parallel with the superpower-writing:section-drafter agent, then runs the two-stage review as a pipeline: superpower-writing:spec-reviewer for outline/claim alignment, then superpower-writing:manuscript-reviewer for writing quality. It reads .writing/plan.md, .writing/outline.md, and .writing/findings.md, and writes drafted prose, progress, and findings back into .writing/. The claim-first PreToolUse hook fires on every section write.
  • Manual Batch Session → superpower-writing:executing-plans. A separate or manual session that drafts plan batches and stops at checkpoints. Best when workflows are unavailable or the user wants explicit per-batch review.

Recommendation logic (add "(Recommended)" to the best option's label, but never remove options):

  • Parallelism score ≥ 60% OR section count ≥ 5 → recommend Dynamic Workflow.
  • The user wants manual checkpoints across days, or workflow support is unavailable → recommend Manual Batch Session.

After the user chooses, invoke Skill(skill="superpower-writing:drafting") with the path to .writing/plan.md. Drafting owns the per-section claim-first prompt and the evidence loop; it hands the actual orchestration to the chosen path.

Key Principles

Task unit is the artifact, not the file

Writing plans think in sections, figures, and tables — each is a research artifact with its own verification contract. A single section task still touches a single file, but the Why of the task is the artifact (this argument, this figure, this claim set), not the file path. Planning by artifact keeps claim integrity visible; planning by file alone lets load-bearing evidence slip through.

Claim-first is the test-first analog — bake it in

Every draft task's Step 1 must be "resolve claim evidence" before Step 2 "write prose". The PreToolUse hook enforces this at the harness level, but a good plan preempts it by sequencing evidence resolution ahead of the Write tool call. A plan that lists Step 1 as "write Methods prose" will be blocked by the hook and the user will blame the plan, not their skipped evidence work.

Dependencies encode causal order, not just file order

Methods blocks Results because the scientific argument requires it — not because they happen to share a claim file. The dependency table makes this explicit so the parallelism analysis downstream reflects real constraints, not accidental file ordering.

Parallelism score is an honest number

Do not inflate parallelism by declaring tasks parallel that really share context. Introduction and Methods are genuinely parallel (disjoint claim sets, disjoint literature). Results and Discussion are NOT parallel — Discussion interprets Results. Be honest; downstream drafting mode selection depends on this being accurate.

The plan does not write prose

This skill is a planner. It never drafts prose itself. Every prose-writing Step appears in a task that drafting will execute later. Keep the separation clean: plans are orchestration, drafting is production.

Shadow dependencies (I ↔ D) are loose, not hard

Introduction and Discussion reference each other thematically — Intro opens loops, Discussion closes them. When drafting sequentially, always draft I → M → R → D → A. When I and D are drafted concurrently (the dynamic workflow's parallel path), expect a pass-two Intro edit after Discussion lands. Such plans must schedule this edit as an explicit R.4 / I.4 touch-up task.

.writing/ is the canonical persistent-state directory

This plan lives at .writing/plan.md. The plugin keeps all persistent per-project state under .writing/ — manuscripts, claims, figures, reviews, progress, findings, archive, stash. Do not write plans or status to any other location.

Hand-off is mandatory

Never finish the skill without presenting the execution options via AskUserQuestion. The plan is useless until the user picks how to execute it — the choice drives whether a dynamic workflow or a manual batch session runs next.

Remember

  • Exact file paths always (.writing/manuscript/03_methods.tex, not "the methods file").
  • Complete content in every step — no placeholders (see "No Placeholders" section).
  • Exact commands with expected output (bash snippets for init and commit steps; claim id lists for evidence-resolution steps).
  • Every task includes a plain git commit command — author identity comes from the user's git config, not from skill-injected overrides.
  • Prefixed skill names for plugin-local domain skills (superpower-writing:scientific-schematics, superpower-writing:citation-management, superpower-writing:research-lookup). Zotero access goes through the zotero-mcp MCP server (tools: zotero_search_items etc.), registered in the plugin's .mcp.json — not through a skill. Local execution-engine references also use the superpower-writing: prefix.
  • Every task reminds: "Log discoveries, decisions, and insights to .writing/findings.md".
  • Always include the parallelism groups analysis.
  • Lock file boundaries and responsibilities before task decomposition.
  • Plan size budget: one file, one pass. If the plan exceeds ~800 lines, split into sub-plans by IMRAD phase (e.g., plan-part-methods.md, plan-part-results.md) and reference from a top-level index.
  • .writing/plan.md is source of truth for drafting; status tracking lives in .writing/progress.md.