The user has already passed in (or is about to pass in) a raw material file in markdown format. Treat it as a pile of input material: it can be anything from a tidy list of fragments to an unstructured wall of text to a transcript. Format does not matter. Before doing anything else, read it from beginning to end.
Then carry out a shaping session to generate a standalone article document. This is exploit: exploration is already done, the pile of material is fixed: commit to a structure, then mine the pile of material to fill it. Do not edit the raw material file: it is read-only for this skill.
If the user has not said where to save the article, ask once and remember the path.
Loop process
- Read the pile of material. Read through the entire input file. Form a sense of what is in it.
- Set the prerequisites. Work with the user to determine what the reader already knows on entry: the concepts that are **grounded** from the start. Every other concept must be grounded by some block before a later block can use it. SeeGrounding。
- Draft 2–3 candidate openings. Each opening should suggest a different thesis or angle for the article. Show them all. Make the user choose one or combine a hybrid version. The chosen opening determines the task the rest of the article must accomplish.
- Advance block by block. Once the opening is determined, ask "Given this opening, what does the reader need to hear next?" Extract content from the pile of material to answer. The next block can only depend on already grounded concepts, and as it lands it also grounds new concepts. Argue about the form of the next block: paragraph, list, table, callout box, quotation, or code block. Every format choice should be intentional and defensible.
- Append to the article file at any time. Do not save it all up. Write each agreed paragraph or block immediately so the user can see the article taking shape.
- Loop step 4 until the article is complete. The user decides when it is complete.
Grounding
Everyconceptmust begroundedbefore it is used by some block: the reader either already knows it on entry, or has encountered it in a previous block. A block that touches an ungrounded concept loses the reader. The unit is concepts, not words: a block can depend on an idea the reader lacks even with no jargon at all. When a concept has a name: aterm: grounding means landing both the idea and its term.
A concept is grounded in one of two ways:
- Prerequisite: grounded before the opening. The reader brings it. Fixed at the start.
- Introduced: some block establishes it, and after that it is grounded for the rest of the article.
Keep track of the currently grounded list. When you ask "What does the reader need to hear next?", the ungrounded concepts the next action needs are themselves the answer: ground it first: here or in a previous block: otherwise you cannot take that action. This is more important thanextracting from the pile of materialThe gap is named one level higher: there, the material pile lacks material; here, the article lacks a foundation.
The biggest leverage lies in the trade-off between what you set as prerequisites and what you solidify inside the article. Requiring too much prior knowledge shuts readers out; solidifying too much internally drowns the opening in definitions. Discuss this with the user when setting prerequisites.
Conversational feel
This is an inverted interrogation phase. During ideation, the question is "What exactly did you notice?" Here, the question is "What exactly is this article arguing, and in what order does the reader need to receive it?" Push back. Refuse to let weak transitions slip through. If a paragraph doesn't deserve that position, cut it.
Specific moves to use consistently:
- "What does this passage give the reader that the previous passage did not?"
- "If I delete this passage, what breaks?"
- "Is this prose, or should it be a list? Why prose?"
- "This sentence is doing two things at once: split it apart or keep only one."
- "The opening promised X. We've drifted to Y. Either reconnect them or revise the opening."
Extracting from the material pile
Treat raw material as a quarry, not a script. Extract a fragment, rewrite it to fit the surrounding paragraphs, then place it in. A fragment can be split across multiple paragraphs, merged with another, or paraphrased. The material pile's job is to be mined; the article's job is to read like one voice.
If the material pile lacks something the article needs, state the gap explicitly: "This needs an example, and the material pile doesn't have one: give me one now, or we cut this section."
The format arguments that actually matter
When choosing how to present a block, weigh the following trade-offs 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 parallel, a list is faster to scan.
- Inline vs. callout box. Tips, warnings, and asides go in callout boxes (
> [!TIP]、> [!NOTE]): but only if they would genuinely derail the main argument. Otherwise keep them inline. - Table vs. repeated structure. If the same structure repeats with the same fields 3 or more times, use a table. Otherwise use prose with bold lead-ins.
- Quote vs. paraphrase. Quote when the original wording itself matters. Paraphrase when only the idea matters.
- Code block vs. inline code. Multi-line, runnable, or for display → code block. Single token or identifier → inline.
Writing rhythm
Once each block is agreed upon, append it to the article file. Re-read the file from disk before every write: the user may have edited it between rounds. Never overwrite blindly. If the user wants to rewrite a passage, edit that passage in place; leave the rest unchanged.
Out of scope
- Mining new fragments not in the material pile (handle gaps as in "Extracting from the material pile").
- Editing the raw material files.
- Publishing, formatting for a specific platform, or adding frontmatter the user did not request.