The user has passed in (or will pass in) a raw material markdown file. Treat it as an input pile: it can be a tidy list of fragments, an unstructured wall of prose, a transcript, any format at all. Read it through completely first, then do anything else.
Then run a shaping session, producing a standalone article document. This is exploit: exploration is already done, the pile is fixed—commit to a structure and mine the pile to fill it. Do not edit the raw material file; for this skill it is read-only.
If the user has not specified where to save the article, ask only once and remember the path.
The loop
- Read the pile. Read the input file in full, forming an overall sense of the content.
- Establish the prerequisites. Determine with the user what the reader knows on entry—the concepts that are already grounded from the start. Everything else must first be grounded by some block before a later block can rely on it. See Grounding。
- Draft 2-3 candidate openings. Each opening should suggest a different thesis or angle for the article. Show them all, forcing the user to choose or combine a hybrid. The chosen opening defines what the rest of the article must accomplish.
- Grow paragraph by paragraph. Once the opening has landed, ask "given this opening, what does the reader need to hear next?" Draw material from the pile to answer. The next block may rely only on already grounded concepts, and grounds new concepts as it lands. Discuss whether the next block should be a paragraph, list, table, callout, quote, or code block. Every format choice should be deliberate and defensible.
- Append to the article file as you go. Do not batch. Write each agreed-upon paragraph or block immediately, so the user sees the article taking shape.
- Loop step 4 until the article is done. The user decides when it is done.
Grounding
Every concept must first be groundedbefore some block can rely on it: the reader either knows it on entry, or has encountered it in an earlier block. A block that reaches for an ungrounded concept loses the reader. The unit is the concept, not its wording—even if no term is in sight, a block may rely on an idea the reader does not have. When a concept has a name—a term—grounding it means landing the idea and the term together.
A concept is grounded in one of two ways:
- Prerequisite — grounded before the opening. The reader brings it. Fix it at the start.
- Introduced — some block establishes it, and from then on it is grounded for the rest of the article.
Maintain a list of what has been grounded so far. When you ask "what does the reader need to hear next?", an ungrounded concept that the next step needs is itself the answer: ground it first—here or in an earlier block—otherwise you cannot do this move. This is Pulling from the pile one level above gap-naming: there the pile lacks material; here the article lacks foundation.
The key leverage is what you set as a prerequisite and what you ground inside the article. Require too much at the start and you shut the reader out; ground too much internally and the opening drowns in definitions. Settle this with the user as you establish prerequisites.
Conversational feel
This is an inverted grilling session. Ideation asks "what are you actually noticing?" Here we ask "what is this article actually arguing, and in what order does the reader need to hear it?" Push back. Don't let weak transitions slide. If a paragraph hasn't earned its place, cut it.
Keep using these specific moves:
- "What does this paragraph do for the reader that the previous one didn't?"
- "If I cut this, what breaks?"
- "Is this prose, or should it be a list? Why prose?"
- "This sentence is doing two jobs — split it or pick one."
- "The opening promised X. We've drifted to Y. Either re-thread it or change the opening."
Pulling from the pile
Treat the raw material as a quarry, not a script. Extract fragments, rewrite them to fit the surrounding paragraphs, then place them in. A fragment can be split across multiple paragraphs, merged with another, or paraphrased. The pile's job is to be mined; the article's job is to read like one voice.
If the pile is missing something the article needs, state the gap explicitly: "We need an example here and the pile doesn't have one — give me one now or we cut this section."
Format arguments to actually have
When choosing how to present a block, discuss these tradeoffs out loud with the user rather than deciding silently:
- Prose vs. list. Prose carries argument; lists carry parallel items. If the items aren't truly parallel, prose is better. If they are, a list is easier to scan.
- Inline vs. callout. Tips, warnings, and asides go in callouts (
> [!TIP]、> [!NOTE]) but only when they would genuinely interrupt the main argument inline. Otherwise keep them inline. - Table vs. repeated structure. If the same shape repeats 3+ times with the same fields, use a table. Otherwise use prose with bold leads.
- Quote vs. paraphrase. Quote when the original wording is itself the point. Paraphrase when only the idea matters.
- Code block vs. inline code. Multi-line, runnable, or illustrative → block. Single token or identifier → inline.
Writing rhythm
Once each block is agreed on, append it to the article file. Before every write, re-read the file from disk; the user may have edited it between turns. Never blindly overwrite. If the user wants to rewrite a paragraph, edit that specific paragraph in place; leave the rest untouched.
Out of scope
- Mine new fragments that don't exist in the pile (handle gaps the way "Pulling from the pile" does).
- Edit the raw material file.
- Publish, format for a specific platform, or add frontmatter the user didn't ask for.