| name | writing-architect |
| description | Macro-first pipeline for multi-page documents where structure matters as much as prose (proposals, papers, grants, reports): intake -> outline contract -> draft -> developmental, structural, specificity, voice, and persona reviews -> human-writer copy pass. Trigger on "deep writing pass", "this reads like AI even with no AI tells", or any long-form piece for a specialist audience. Under ~1 page use human-writer; for critique only, editor. |
Writing Architect
Your job is to make a long document read like the person who actually does
the work wrote it. Not like a competent AI that summarized their abstracts.
The bar: a domain expert reviewer reads the result and never wonders if a
human wrote it. They might disagree with the argument, but they will not
suspect the author of being an outsider.
human-writer catches sentence-level AI tells. This skill catches the
problems that survive a clean copy edit:
- Over-explaining things the audience already knows.
- Naming categories where a specialist would name instances ("DFT" with no
functional, "ligands" with no specific ligands, "broader pairs" with no
pairs named).
- Hedging on anything the AI couldn't invent, instead of asking the user
for the real value.
- Sections that don't earn their place. Arguments that accrete rather
than build.
- Voice that drifts from how the user actually writes when they're not
being assisted.
Run the stages in order. Each stage assumes the prior stage is clean. Do
not skip stages because the draft "looks fine" — the failures this skill
targets are invisible without these passes.
Boundary with adjacent skills
human-writer runs inside this skill at the copy-edit stage. Do
not invoke it earlier. Do not duplicate its work here.editor runs at the very end as a final critique. Useful when the
user wants a notes-style review before they call the doc done.deep-planner is upstream of this skill. It plans what the doc
should be; this skill picks up from "we know what we want to write."
If the user is still figuring out what to write, redirect to deep-planner.presentation-designer owns slide decks. Long-form prose only here.
When to engage versus pass
Engage when:
- Document is more than ~1 page and structure could be the issue.
- Audience is specialist (peers, reviewers, technical readers).
- The user says the prose "reads like AI" but can't point to specific tells.
- A previous human-writer pass produced output the user didn't trust.
Pass to human-writer when:
- It's an email, Slack message, short post, single paragraph.
- The user wants a fast rewrite, not a multi-pass review.
- The draft is short enough that there's no structure to review.
If unsure, ask one question: "How long is the document, and who's the
audience?" The answer makes the call.
Stage 0: Intake
Before any drafting or review work, gather four things. Ask only what you
need — if the user already provided some of this in their initial message,
don't ask again.
Document profile
- What kind of document? (proposal, paper, memo, report, etc.)
- Page or word limit, required sections, deadline.
- Is there an existing draft, or are we starting from scratch?
Audience profile
- Who reads this? Their job, their expertise, what they already know,
what they care about, what they'll skim versus read carefully.
- For a grant: the panel composition. For a paper: the journal's typical
reviewer. For a memo: the specific recipient.
The audience profile drives the specificity audit. Without it, the skill
can't tell over-explanation from helpful explanation. Press for specifics
if the user gives vague answers ("smart technical people" is not enough —
which field? what subfield? what's their daily work?).
Voice samples
Ask the user to paste or point to 2–3 paragraphs of their own prose in
the same register — published work, prior abstracts, a paragraph from a
paper they wrote. Not topic-related summaries, not AI-assisted prose
they already accepted. Their own writing, raw.
These samples drive voice-matching in the later passes. If the user has
no samples (first-time author, new register), say so and proceed without
voice priming — the skill works without it but is more reliable with it.
Cannot-invent list
The most important intake step. Enumerate the domain commitments the
AI must not invent. The list depends on the doc type. For each category,
ask whether the user has the real value or wants to mark it TBD.
Load references/intake-templates.md when starting intake. It
contains starting-point cannot-invent lists for the common document
types: computational chemistry, ML/AI paper, biomedical proposal,
general academic paper, internal memo, technical white paper. Pick the
template that matches the user's doc, walk it category by category,
and adapt where the user's work differs from the template.
If the user's doc type isn't in the templates file, build the list
from scratch using the framework at the top of that file ("what
specific values would a domain reviewer expect to see, and what would
they conclude if I made them up?").
Treat the user's answers as ground truth. Anything not supplied gets a
placeholder like [FUNCTIONAL: TBD] in the draft, never silently
filled with a plausible-sounding default.
This step alone fixes the worst failure mode. Most AI proposal drafts
fail because the AI wrote around uninventables instead of marking them.
Stage 1: Outline contract
For any doc longer than two pages, produce a structured outline before
drafting. Sign-off required.
Format:
Section 1: <name>
Intent: <one sentence on what this section accomplishes>
Key facts to land: <2–4 bullets of the specific content>
Section 2: <name>
...
Present the outline. Ask the user three questions:
- Are any sections missing?
- Are any sections doing nothing the reader needs?
- Does the order build, or does it just accrete?
Wait for explicit confirmation before drafting prose. Structural problems
are cheapest to fix here.
Stage 2: Drafting
Draft section by section, in order. Each section uses:
- The audience profile (so register is calibrated from the start).
- The voice samples (so register matches the user's actual writing).
- The cannot-invent list (so placeholders go in instead of inventions).
After each section, do not move to the next until you have:
- A draft of that section in the doc.
- A short status line: "Section drafted. Placeholders inserted for: X, Y, Z."
Then check in with the user. They can correct or supply missing values
before you draft the next section.
This is slower than batch-drafting the whole doc. That is deliberate.
Catching problems early costs less than rewriting.
If the user already has a draft and wants you to operate on it, skip
drafting and proceed to Stage 3.
Stage 3: Developmental review
Run this once the full draft exists. Macro only. Dispatch the
developmental-reviewer sub-agent via the Agent tool — do not run
this pass inline in your own context. Context isolation is the point;
if you do it inline, sentence-level concerns bleed into a job that
should only see structure.
Invocation:
Agent({
description: "Developmental review of draft",
subagent_type: "developmental-reviewer",
prompt: <self-contained prompt including draft path, audience profile,
outline, document type. Sub-agent has its own context — give
it everything it needs in one shot.>
})
The sub-agent returns a strict JSON object with five fields:
reverse_outline, alignment_issues, missing_sections,
argument_flow, claims. See agents/developmental-reviewer.md for
the schema.
Your job once it returns:
- Show the reverse outline to the user first. This is the
highest-leverage single artifact. Ask: "Does this sequence read like
a coherent argument? Anything missing, redundant, or out of place?"
- Then present alignment issues, missing sections, argument-flow
breaks — tiered by severity. Hand-waved claims go in a separate
pile.
- Wait for user direction. They tell you which to fix, which to
leave. Apply the structural changes they approve.
- Do not proceed to Stage 4 until structural changes are applied.
A structural change can invalidate every later finding.
If the sub-agent returns {"error": "missing_input", ...}, gather what
it needs and re-invoke. Don't try to do the work yourself.
Stage 4: Structural review
After the user has acted on the developmental findings. Dispatch the
structural-reviewer sub-agent.
Invocation:
Agent({
description: "Structural review of draft",
subagent_type: "structural-reviewer",
prompt: <self-contained: draft path, outline, optionally the
developmental-reviewer's reverse outline from Stage 3.>
})
The sub-agent returns JSON with section_spine, spine_breaks,
promise_payoff, and a flat findings list (each finding tiered as
critical / important / minor). See agents/structural-reviewer.md for
the schema.
Present findings tiered. Critical findings need user direction before
proceeding. Important and minor can be batched. Wait for user direction
before Stage 5.
Stage 5: Specificity audit and voice match (parallel)
Two passes run together, in parallel, because they're independent
and answer different questions:
- Specificity audit catches outsider-voice patterns (categories
without instances, methods without parameters, over-explanation,
hedging on countables). The pass tuned to the failure mode this
skill exists for.
- Voice match catches "this isn't how the user actually writes"
patterns by comparing against their published samples.
The specificity-auditor needs the audience profile and cannot-invent
list. The voice-matcher needs the voice samples from intake. If
either is missing, gather first or skip that pass and tell the user.
Dispatch both in one message via two parallel Agent calls:
Agent({
description: "Specificity audit for outsider voice",
subagent_type: "specificity-auditor",
prompt: <self-contained: draft path, full audience profile,
full cannot-invent list.>
})
Agent({
description: "Voice match against user samples",
subagent_type: "voice-matcher",
prompt: <self-contained: draft path, voice samples (inline),
audience profile context.>
})
The specificity-auditor returns:
fix_able — findings the skill can act on without inventing domain
commitments. Each entry includes suggested_fix as the actual
replacement text.requires_user — findings that need a real domain value from the
user. Each entry includes question_for_user and which cannot-invent
item it maps to.
The voice-matcher returns:
sample_profile — the user's voice characterized along four axes
(vocabulary register, sentence rhythm, specificity habits, voice
markers). Useful to show the user as a sanity check.divergences — per-paragraph flags where the draft drifts from the
sample profile, with the specific axis and (where possible) a
rephrase drawn from the samples.
See agents/specificity-auditor.md and agents/voice-matcher.md for
full schemas.
Your job once both return (the two reports have different schemas —
don't literally merge them; coordinate them):
- Collapse duplicates across the two reports before presenting.
When a specificity finding and a voice divergence point at the same
paragraph or sentence, present them as one finding so the user sees
each problem once. Everything else stays in its own list.
- Batch all
requires_user questions from specificity into one
message. Don't ask them one at a time — they came up in one pass,
answer them in one pass. A voice divergence whose rephrase depends
on one of those answers is provisional: get the domain value first,
then generate the rephrase.
- Present
fix_able and voice divergences together as a list of
proposed changes. Let the user accept all, reject some, or edit
individually.
- Apply approved fixes and user-supplied answers to the draft.
Anything the user can't supply right now becomes a placeholder, not
an invented value.
If voice samples were not provided at intake, run only the
specificity-auditor and skip the voice-matcher. Note that to the user
so they know voice was not checked.
If both passes return near-zero findings, the draft is either already
specialist-grade or the inputs are too lenient. Sanity-check by asking
the user if the draft now reads like a peer wrote it.
Stage 6: Persona-reader simulation
After the draft has been structurally and specificity-corrected, read
it through the eyes of its actual audience segments. This catches
reader-experience problems the prior passes can't see — what feels
thin, what reads as posturing, what's missing for this reader even
though the document is structurally complete.
Dispatch one persona-reader sub-agent per audience segment, in
parallel. For a typical grant proposal, that's two or three
personas: the technical reviewer, the panel chair, the program officer.
For a paper: the conservative referee, the enthusiastic referee, the
journal editor. For a memo: the recipient, anyone else copied who
might intervene.
Load references/persona-library.md to find a starting-point
persona for each audience segment. The library covers common readers:
grant panel reviewer (ACCESS/NSF/DOE), NIH study section reviewer,
journal referee (conservative and enthusiastic variants), conference
reviewer, program officer, executive on a memo, lay reader. Each
entry includes role, expertise, what they're scored on, how they
read, and what trips their skepticism.
Pick the library persona that matches each segment and adapt it to
the specific context — name the field, the venue, the agency, the
person if known. If a segment isn't in the library, build the persona
from scratch using the framework at the top of that file. A usable
persona spec needs all of:
- Role / job title
- Domain expertise (what they know cold)
- What they are scored on
- How they read in this context (skim vs. deep, rubric-based?)
- What they've seen before
- What trips their skepticism
If the audience profile from intake isn't specific enough to
construct two or three distinct personas, ask the user before
dispatching. A generic "the panel" is not a usable spec.
Dispatch in parallel:
Agent({
description: "Persona read: technical reviewer",
subagent_type: "persona-reader",
prompt: <self-contained: draft path, persona spec for technical
reviewer, audience profile context.>
})
Agent({
description: "Persona read: panel chair",
subagent_type: "persona-reader",
prompt: <self-contained: draft path, persona spec for panel chair,
audience profile context.>
})
Each agent returns six dimensions per persona: initial reaction, what
works, critical gaps, credibility issues, missing examples, one
critical fix. See agents/persona-reader.md for the schema.
Your job once they return:
- Synthesize across personas. Where multiple personas flag the
same issue, surface it once with high priority. Where personas
diverge (one praises, another panics), surface the divergence
directly — it usually means the doc is calibrated for one segment
at the expense of another, and the user needs to decide.
- Highlight each persona's
one_critical_fix even if it didn't
appear elsewhere. That field is the persona's highest-leverage ask.
- Wait for user direction. Critical gaps and credibility issues
often loop back to Stage 3 or Stage 5; cosmetic fixes can proceed
to Stage 7.
If the personas converge on critical issues, recommend looping back
to Stage 3 before proceeding to copy-edit. A structurally-thin
proposal does not benefit from a tighter copy edit.
Stage 7: Copy-edit handoff
The draft is now structurally sound, audience-calibrated, specific,
and persona-tested. This is where human-writer does its sentence-
level pass:
- AI tells (vocabulary, sentence patterns, em dashes, etc.)
- Rhythm and cadence
- Throat-clearing and boilerplate closings
Delegate explicitly. Do not duplicate human-writer's checks here. Pass
the draft and the voice samples; let it run.
Then optionally pass to editor for a final critique-style review. If
editor returns clean, the doc is done. If it returns findings, those
are typically structural problems that slipped through earlier stages —
loop back to Stage 3 if so.
Stage 8: Iterate or finalize
Two halt conditions:
- User calls it done.
- Critical findings list is empty across Stages 3, 4, 5, 6, and 7.
If looping, return to the earliest stage with unaddressed findings. A
new section addition triggers a fresh Stage 1 outline check on the
affected area; a structural rewrite triggers Stage 3 on the rewritten
sections; specificity or voice findings without structural changes can
loop inside Stage 5. Persona-reader divergence usually loops back to
Stage 3 or 5, not just a copy edit.
Cap at three full pipeline iterations per session. If the doc still
isn't right after three, the underlying problem is usually that the
intake was wrong — incomplete audience profile, missing voice samples,
or an unrealistic outline. Surface that and re-intake.
Producing the clean copy
A working draft carries scaffolding the final document must not: TODO
callouts, [bracketed] placeholders, intake notes, leftover
cannot-invent reminders. Finalizing strips all of it into a clean copy,
either a separate file (paper-clean.md) or, once the doc is in Word, by
deleting the callout paragraphs in place. Do this only when the user
calls the content done. Every placeholder must be filled or cut first: a
clean copy with an invented value is worse than a visible TODO.
Operating notes
Default editing surface, and the handoff to Word
Markdown first, not Word. The office-mcp friction with paragraph styles,
heading insertion, and font sizing eats time, so draft in .md, run
every review pass on .md, and convert to .docx only when the content
is settled.
Convert with a reference doc when the venue dictates formatting. Grant
applications usually mandate margins and a minimum font size (ACCESS, for
example, requires 1-inch margins and 11pt or larger), and pandoc's
default docx honors neither reliably. Build a reference doc once and
reuse it:
pandoc --print-default-data-file reference.docx > reference.docx
# set 1-inch margins (w:pgMar 1440) and the body font in reference.docx, then:
pandoc -o paper.docx --reference-doc=reference.docx paper.md
Pandoc's md-to-docx conversion also leaves artifacts worth a cleanup
pass: thematic breaks (---) can render as a stray / line, and bullet
lists sometimes collapse to inline - markers inside one paragraph.
Open the converted docx and fix these before handing it over.
The handoff is one-directional. Once the user starts editing the .docx
in Word, that file becomes the source of truth. Do not regenerate it from
the .md, which would clobber their edits; read the live document (via
the office MCP) before changing anything, edit it in place, and treat the
.md as stale. If they only want light Word edits up front, warn that
live editing is slower and confirm before mid-document inserts.
Structured output between stages
Each review pass produces JSON with a known schema (see each sub-agent's
own file). The skill consumes that JSON and presents findings to the
user — it does not paraphrase the sub-agent's review back into free
prose. Free prose loses the location and evidence-quote fields the user
needs to act.
Sub-agent dispatch
Stages 3 through 6 dispatch to sub-agents in ~/.claude/agents/:
developmental-reviewer, structural-reviewer, specificity-auditor,
voice-matcher, persona-reader. Each runs in its own context, returns
JSON, then the skill synthesizes for the user. If a sub-agent returns
{"error": "missing_input"}, gather the inputs and re-invoke — do not
fall back to running the pass inline in the main context, since the
point of the dispatch is context isolation.
Parallelization plan:
- Stage 3 runs alone. Its output (reverse outline, alignment audit)
can change what every later stage looks at.
- Stage 4 runs alone, after the user has acted on Stage 3 findings.
- Stage 5 fires
specificity-auditor and voice-matcher in
parallel — they're independent and read the same draft from
different lenses. Two Agent calls in one message.
- Stage 6 fires
persona-reader once per audience segment, in
parallel. Two or three Agent calls in one message is typical.
Within a stage, dispatching sub-agents in parallel is the right move —
they're independent jobs and the orchestrator just merges results.
Across stages, run sequentially — later passes depend on earlier
findings being applied.
What to skip on a short doc
For a 1–2 page memo:
- Skip Stage 1 (outline contract).
- Skip Stage 3 reverse outline (too short to matter).
- Run Stages 4, 5, and 7 (copy-edit). Skip Stage 6 personas unless the
reader stakes are high (a memo going to one specific exec is the
exception — run a single persona-reader call for that one reader).
For anything 3 pages or longer, run the full pipeline.
Voice samples are optional but high-leverage
The skill works without them. With them, the voice-matcher pass runs
(it requires samples) and the copy-edit handoff is noticeably more
accurate. If the user says they have no samples and have never written
in this register, accept it, skip the voice-matcher in Stage 5, and
proceed. Don't insist.
For repeat users, suggest keeping voice samples in a known location
so they don't re-paste each session. A simple convention:
~/.claude/voice-samples/<register-name>.md (e.g.,
technical-proposals.md, internal-memos.md). At intake, ask the
user if they have stored samples; if yes, read from there. If they
want to save new samples after intake, offer to write them out for
future sessions.
Honesty about what's invented
If a value gets filled in that the user didn't supply (a hedge replaced
with a specific number, a name swapped in), flag it explicitly: "I
filled in X — confirm before submitting." Never silently invent.
Final check before declaring done
- Reverse outline reads like a coherent argument.
- Promise-payoff: every intro commitment delivered.
- No cannot-invent placeholders left unfilled.
- No category-without-instance flagged in specificity audit.
- No over-explanation to the audience profile.
- Voice-matcher (if run) shows no critical divergences from samples.
- Persona-reader critical gaps and credibility issues addressed or
acknowledged.
human-writer pass clean.editor pass returns no critical findings.
If any of these fails, name the failure and loop back to its stage. Do
not declare done with open critical findings.
