<what-to-do>
The user has uploaded (or will upload) a raw material file in markdown format. Treat it as an input material pile—it can be anything from a neat list of fragments to an unstructured wall of text to a transcript. Format doesn't matter. Read it from start to finish before doing anything else.
Then conduct a shaping session to generate a standalone article document. This is exploit: Exploration is complete, the material pile is fixed—commit to a structure, then mine the material pile to fill it. Do not edit the raw material file—it is read-only for this skill.
If the user does not specify where to save the article, ask once and remember the path.
</what-to-do>
<supporting-info>
Cycle Process
- Read the material pile. Read through the entire input file. Form a sense of what it contains.
- Set prerequisites. Confirm with the user what readers already know when they start—the concepts that are grounded from the beginning. All other concepts must be grounded by a section before subsequent sections can use them. See Grounding.
- Draft 2–3 candidate openings. Each opening should hint at a different argument or angle of the article. Present all of them. Make the user choose or combine a hybrid version. The selected opening determines the tasks the rest of the article must fulfill.
- Advance section by section. Once the opening is confirmed, ask "Given this opening, what does the reader need to hear next?" Extract content from the material pile to answer. The next section can only rely on already grounded concepts, and new concepts are grounded as they are introduced. Argue about the form of the next section—paragraph, list, table, callout, quote, or code block. Every format choice should be intentional and justifiable.
- Append to the article file at any time. Don't save up content. Write each agreed-upon paragraph or section immediately so the user can see the article take shape gradually.
- Repeat step 4 until the article is complete. The user decides when it's finished.
Grounding
Each concept must be grounded before being used in a section: either readers already know it when they start, or they encountered it in a previous section. A section that touches an ungrounded concept will lose the reader. The unit is the concept, not the word—a section can rely on an idea the reader lacks even if there's no jargon at all. When a concept has a name—a term—grounding means establishing both the idea and its term.
Concepts are grounded in one of two ways:
- Prerequisite—Grounded before the opening. Readers bring this knowledge with them. Fixed at the start.
- Introduced—Established by a section, and thereafter grounded for the rest of the article.
Keep track of the current list of grounded concepts. When you ask "What does the reader need to hear next?", the ungrounded concepts required for the next action are the answer itself: ground them first—either here or in a previous section—otherwise you can't take that action. This is one level higher than naming gaps in
Extracting from the Material Pile: there, the material pile lacks content; here, the article lacks foundational knowledge.
The greatest leverage lies in the trade-off between what you set as prerequisites and what you ground within the article. Asking for too much prior knowledge will shut readers out; grounding too much internally will drown the opening in definitions. Consult with the user on this when setting prerequisites.
Conversational Tone
This is an inverted interrogation session. When brainstorming, the question is "What exactly did you notice?" but here the question is "What is this article actually arguing, and in what order do readers need to receive it?" Push back. Refuse to let weak transitions slide. If a paragraph doesn't deserve that spot, cut it.
Specific tactics to use consistently:
- "What does this text provide that the previous paragraph didn't?"
- "If I cut this section, what breaks?"
- "Is this prose, or should it be a list? Why prose?"
- "This sentence is doing two things at once—split it or keep only one."
- "The opening promised X. We've drifted to Y. Either reconnect it or revise the opening."
Extracting from the Material Pile
Treat raw materials as a quarry, not a script. Extract a fragment, rewrite it to fit the surrounding paragraphs, then insert it. 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 a single voice.
If the material pile lacks something the article needs, clearly point out the gap: "An example is needed here, and it's not in the material pile—give me one now, or we'll cut this section."
Format Debates to Actually Have
When choosing how to present a section, openly weigh the following trade-offs with the user instead of deciding privately:
- Prose vs. Lists. Prose carries arguments; lists carry parallel items. If items are not truly parallel, prose is better. If they are parallel, lists are faster to scan.
- Inline vs. Callouts. Tips, warnings, and asides go into callouts (, )—but only if they would truly derail the main argument. Otherwise, keep them inline.
- Tables vs. Repeating Structures. If the same structure repeats with the same fields more than 3 times, use a table. Otherwise, use prose with bolded lead-in sentences.
- Quotes vs. Paraphrasing. Quote when the original wording itself matters. Paraphrase when only the idea is important.
- Code Blocks vs. Inline Code. Multi-line, runnable, or for demonstration → code block. Single token or identifier → inline.
Writing Rhythm
Append each agreed-upon section to the article file immediately after consensus is reached. Re-read the file from disk before each write—the user may have edited it between rounds. Never blindly overwrite. If the user wants to rewrite a section, edit that section in place; leave the rest unchanged.
Out of Scope
- Digging up new fragments not in the material pile (handle gaps per "Extracting from the Material Pile").
- Editing the raw material file.
- Publishing, formatting for specific platforms, or adding frontmatter not requested by the user.
</supporting-info>