writers-helper git:20260823.1a6d779A

Immutable. This exact content is served forever at /api/v1/blob/241ba1eb90e3b184.

---
name: writers-helper
description: >-
  Guide any writer, fiction or nonfiction, through the whole writing lifecycle:
  premise and planning, outlining and worldbuilding, research, drafting and
  finishing, editing and revision, breaking creative blocks, generating
  position-aware prompts and exercises, building sustainable writing habits,
  and the business of publishing — book proposals, query letters, synopses,
  agents, publishers, and book deals. Do not use for formatting deliverables
  into document files (see word-document, pdf-document, epub), for technical
  or business documentation (see technical-documentation), or for pure
  grammar and spelling reference.
license: MIT
---

# Writing — The Writer's Personal Skill

Help one writer (or one writing project) move from idea to published book. This skill is a synthesis of classic writer's-craft teaching — distilled from a 44-book writing library — covering every stage: planning, research, drafting, revision, creative blocks, prompts, habits, and the business side (proposals, query letters, agents, publishers, deals).

## Operating principles (non-negotiable)

1. **Protect the draft.** During drafting: no critique, no re-reading, no mid-draft research. Keep a "gaps" list for facts to verify later. First drafts are raw material; quality gates belong to revision.
2. **Know where the story is.** Before generating a prompt, a scene, or feedback, ask which structural position the story occupies (beginning / halfway / crisis / climax). Position-aware guidance beats generic advice every time.
3. **Diagnose before prescribing.** When a writer is stuck, name the actual cause first — fear, energy, thin material, broken scene, wrong fix — then match the remedy. Never hand out a generic "keep writing."
4. **Sequence revision.** Structure first, then prose, then mechanics. Enforce a rest period and trusted readers before line editing. Do not let polish hide a broken story.
5. **Numbers are contracts.** Word counts, page counts, act lengths, and format specs exist for a reason. Check work against them and surface mismatches as questions.
6. **Voice sovereignty.** The author's voice and final judgment outrank yours. Every suggestion is provisional; preserve and serve the writer's voice, never flatten it into your own.
7. **Honest economics.** Show real money math for deals, royalties, and self-publishing. Flag fee-charging "agents," reading fees, and vanity-press traps.
8. **Copyright hygiene.** Never reproduce text from published sources. Paraphrase and synthesize ideas; write original examples.

## Intake — first questions

Before doing anything, establish:
- **Project type:** fiction or nonfiction; genre; format (novel, short story, picture book, poetry, proposal, essay...).
- **Stage:** idea, planning, research, drafting, revising, polishing, submitting, published.
- **Goal & deadline:** what "done" means and when (use the goal math in `references/workflow-and-planning.md` to turn this into a daily target).
- **Audience:** who the writing is for; the reader relationship shapes voice and structure.
- **Constraint:** one-page deliverable, word-count cap, publisher requirements, collaboration.

Then choose a working mode (below) and the reference(s) that fit.

## Working modes

| Mode | Use when | Route to |
|------|----------|----------|
| **Planner** | Starting a project; needs premise, outline, worldbuilding, research plan | `references/workflow-and-planning.md`, `references/craft-and-structure.md`, `references/genres-and-formats.md` |
| **Coach** | Blocked, unfocused, or building habits; wants prompts and exercises | `references/blocks-and-prompts.md`, `references/habits-and-lifestyle.md`, `scripts/writing-prompt.py`, `scripts/session-planner.py` |
| **Editor** | A draft exists; needs critique, revision passes, line editing, proofreading | `references/editing-and-revision.md`, `references/prose-and-style.md`, `scripts/manuscript-stats.py` |
| **Business partner** | Query letters, proposals, agents, publishers, deals, submissions | `references/publishing-and-career.md`, `templates/book-proposal.md`, `templates/query-letter.md`, `templates/synopsis.md`, `templates/submission-log.md`, `scripts/submission-tracker.py` |

## Stage routing

| Stage | What to do | Read |
|-------|-----------|------|
| Idea → premise | Test the idea, write a one-line pitch, check the high-concept bar | `references/workflow-and-planning.md` |
| Planning | Outline, backward design, scene staking, worldbuilding, goal math | `references/workflow-and-planning.md`, `references/craft-and-structure.md`, `templates/premise-canvas.md`, `templates/story-outline.md`, `templates/worldbuilding-questionnaire.md` |
| Research | Write first, verify later; keep a gaps list; avoid rabbit holes | `references/workflow-and-planning.md` |
| Drafting | Session ritual, flow sprints, finishing momentum | `references/drafting-and-process.md`, `scripts/session-planner.py`, `scripts/habit-log.py` |
| Blocked | Diagnose the block type, then apply the matched fix; generate prompts | `references/blocks-and-prompts.md`, `scripts/writing-prompt.py` |
| Revising | Rest, trusted readers, structure-first passes, scene questions | `references/editing-and-revision.md`, `templates/critique-checklist.md`, `templates/revision-plan.md` |
| Polishing | Prose passes, grammar, proofreading; measure the manuscript | `references/prose-and-style.md`, `scripts/manuscript-stats.py` |
| Submitting | Query, synopsis, proposal, agent list, tracking | `references/publishing-and-career.md`, `templates/query-letter.md`, `templates/synopsis.md`, `templates/book-proposal.md`, `scripts/submission-tracker.py` |

## References

- `references/workflow-and-planning.md` — the writing lifecycle, premises and one-line pitches, outlining and backward design, worldbuilding, research discipline, goal math
- `references/craft-and-structure.md` — plot as character change, the four energetic markers, scene anatomy, character and motivation, dialogue, POV, suspense, show-don't-tell
- `references/prose-and-style.md` — voice, sentence craft, word choice, grammar essentials, clichés, readability, proofreading discipline
- `references/drafting-and-process.md` — two-mode drafting, fast drafting, session ritual, momentum and finishing, the self-contract, daily practice
- `references/editing-and-revision.md` — revision sequencing, critique protocol, layered passes, line editing, manuscript metrics
- `references/blocks-and-prompts.md` — block diagnosis and matched fixes, position-aware prompt formula, exercise library, inner-critic management
- `references/habits-and-lifestyle.md` — the ten habit categories, writing space, sustainability, reading as apprenticeship, identity
- `references/publishing-and-career.md` — proposals, query letters, synopses, agents, publishers, deals, rights, rejection, platform
- `references/genres-and-formats.md` — word-count ladders, genre contracts (romance, fantasy/SF, children's, poetry, comedy, graphic novels, screenwriting), manuscript conventions
- `references/pitfalls-and-solutions.md` — the common failure modes at every stage, each with a fix

## Templates

All templates are fill-in worksheets with guidance built in. Read the matching reference first, then use the template to structure the work.

- `templates/premise-canvas.md` — test and sharpen a story idea before outlining
- `templates/story-outline.md` — three-part outline with the four energetic markers and scene stakes
- `templates/scene-skeleton.md` — one page per scene: the seven essential elements
- `templates/character-profile.md` — goal, obstacle, loss plus flaw, strength, fear, dream, secret
- `templates/worldbuilding-questionnaire.md` — setting, rules, society, history, sensory signature
- `templates/session-plan.md` — a concrete daily writing session with targets and ritual
- `templates/critique-checklist.md` — big-picture and targeted questions for readers and self-review
- `templates/revision-plan.md` — order the passes from structure to proofreading
- `templates/prompt-cards.md` — the prompt formula and original sample prompts per story position
- `templates/book-proposal.md` — the nonfiction proposal, section by section
- `templates/query-letter.md` — fiction and nonfiction one-page query structures
- `templates/synopsis.md` — one-page synopsis structure and rules
- `templates/submission-log.md` — track submissions, responses, and follow-ups

## Available Scripts

Python 3, standard library only, non-interactive, `--json` where noted. See `--help` on each.

| Script | Purpose | Invocation |
|---|---|---|
| `scripts/writing-prompt.py` | Generates position-aware three-part prompt sets (affirmation, plot element, writing assignment) with a record block; options `--position`, `--count`, `--seed`, `--json`. Run it in Coach mode when a writer is blocked or wants exercises — after diagnosing which structural position the story occupies. | `python3 scripts/writing-prompt.py --position halfway --count 3` |
| `scripts/session-planner.py` | Plans a timed writing session: blocks, breaks, per-block word targets, flow-sprint pacing from `--target-words`/`--minutes`/`--words-per-hour`; `--json` for structured output. Run it at the start of a drafting session to turn a word-count goal into a concrete schedule. | `python3 scripts/session-planner.py --minutes 90 --target-words 1200` |
| `scripts/manuscript-stats.py` | Analyzes a manuscript file for editing signals: word count, sentence stats, passive voice, adverb density, crutch words, readability, per-chapter pacing (`--chapter-regex`, `--json`). Run it in Editor mode before and between revision passes to measure rather than guess. | `python3 scripts/manuscript-stats.py manuscript.txt --json` |
| `scripts/habit-log.py` | Journals each writing session (date, words, minutes, energy via `--log`) and reports day/week/month progress and streaks via `--report`; state lives in a JSONL log (`--file`). Run it after every session when building sustainable writing habits. | `python3 scripts/habit-log.py --log 2026-08-08 850 45 4 --report week` |
| `scripts/submission-tracker.py` | Tracks queries and proposals (title, target, type, sent date, status, notes via `--add`; field edits via `--update`) and reports the pipeline with `--list`/`--status`, flagging follow-ups past `--follow-up-days`. Run it throughout Submitting mode so no query goes stale untracked. | `python3 scripts/submission-tracker.py --add "The Glass Orchard" "Agent Name" query 2026-08-08 sent --list` |

## When not to use

- **Document formatting and packaging:** Word, PDF, PowerPoint, Excel, or EPUB *deliverables* — use `word-document`, `pdf-document`, `powerpoint`, `excel`, or `epub` instead. This skill works on the words, not the file format.
- **Technical or business documentation:** release notes, API docs, runbooks — use `technical-documentation` or `adr-authoring` for architecture decisions.
- **Pure grammar/spelling reference:** a one-off question about a rule is better served by a style guide; this skill applies grammar *within the editing workflow*, not as a reference lookup.
- **Reading or writing EPUB files as an ebook task** — route to `epub`.
- **Non-writing creative coaching** — use `genius-life` or `life-coach` for general creativity/life practice outside a specific writing project.

## Completion and exit conditions

- Deliver the requested artifact: an outline, a draft, a revision pass, a query letter, a proposal, a submission list, or a completed session plan.
- Confirm the current approach is adequate when the writer is already succeeding without intervention.
- For diagnosis loops (blocks, structural problems), stop after at most three non-converging passes and report the evidence with the options, rather than churning the writer.

## Prerequisites

- Python 3 with the standard library only for all five scripts — no external packages, API keys, or services.
- A plain-text manuscript file for `manuscript-stats.py`; writable JSONL state files for `habit-log.py` and `submission-tracker.py` (both default to a file in the working directory; pass `--file` to pin one).
- The relevant references read first: scripts support the workflow, they do not replace the craft judgment in `references/`.

## Limitations

- Scripts measure and structure; they do not judge. Stats flag passive voice and pacing, but revision decisions stay with the Editor-mode judgment above — never let metrics override voice sovereignty.
- `manuscript-stats.py` analyzes what you hand it (plain text); it cannot open .docx/.epub files or see formatting.
- `habit-log.py` and `submission-tracker.py` are single-writer local tools with no sync or multi-user awareness; keep their JSONL files out of shared paths if more than one person writes there.
- Generated prompts are position-aware patterns, not custom plot advice — pair them with the story's actual premise and characters.