Turn work into a written article. Two entry points. A lesson script from /record, or a raw code change.
An article is not a transcript. Two things change at once.
Speech and prose fail differently, because a listener cannot skim while a reader skims first and commits second. And the register changes, because an article is you telling someone how you actually work rather than instructing them. Contractions, asides, humour, and admissions of what you do not know all belong here, and none of them belong in a lesson.
Steps
- [ ] 1. Find the source
- [ ] 2. Rebuild the spine
- [ ] 3. Convert or gather
- [ ] 4. Verify
- [ ] 5. Write
- [ ] 6. Hand it back
1. Find the source
Look in docs/lessons/ for a script. If one exists, ask which lesson, unless the conversation already named it.
If no script exists, this runs from the change directly. Follow references/shared/change-analysis.md for scoping and references/shared/prompt-recovery.md for the prompt, then continue from step 3.
2. Rebuild the spine
A script is ordered for someone who cannot skip. An article is ordered for someone who will.
Find the single most useful thing in the source. Usually the prompt reasoning or the specific failure that got fixed. That goes near the top, not at its narrative position. The lede has about two sentences to earn the scroll, and "in this article we will look at" spends both on nothing.
Then order the rest so each section stands alone enough to be read out of order, because many readers will.
3. Convert
Running from a script, apply these. Running from a diff, produce the same shapes directly.
| In the script | In the article |
|---|---|
| A step line telling the creator what to open | A code block, a figure, or cut entirely |
| Spoken spelling ("parent I D") | The real identifier, parentId, in backticks |
| Spelled path ("lib slash d b") | lib/db/queries.ts in backticks |
| A breath line | Cut. Whitespace does this job on a page. |
| Repetition for retention | Cut. The reader can look up. |
| "Take a second on that one" | Cut. |
| Cold open showing the result | A lede stating the result and the cost |
| Step lines in the outline | Single-word headings, one per stage |
| Formal instructional register | Personal register, contractions included |
| The delegation prompt | Cut. A reader can already see the code. |
Code blocks are the article's main advantage over video, so use real ones with the file path above each. A reader can copy from them. Nobody pauses a video to retype.
4. Verify
Run the verify gate in references/shared/change-analysis.md. Show the user anything that failed before writing.
An article outlives a video. It gets linked, quoted, and found by search for years, so a wrong claim keeps costing after the video has scrolled away.
5. Write
Read references/prose-voice.md for the written language rules and references/shared/voice.md for the house rules underneath them.
Structure.
The opening. Start somewhere the reader was not expecting, then turn and land them. See references/prose-voice.md. Never open with what the article will cover.
The decision. The heaviest section, the same as in the lesson. What had to be decided, what the alternative cost across the system, the follow-on questions it forces, and what would make the other answer right. This is the section people link to.
The prompt. Quoted exactly, then broken down. Include the version that leaves the decision open and what comes back.
What got written down. The rule added to the rules file, and why it is written to be checkable rather than persuasive.
The code. This is where an article beats a video. A reader can copy a block and a viewer cannot, so include real code with the file path above it, and keep it to the parts that carry the decision. Explain why the shape is what it is and let the block show what it does.
The architecture. The constraint that produced the shape, and what breaks without it.
Tools. Only where a comparison passes the bar in references/shared/tool-comparison.md.
Where it breaks. Plain, specific, in the body.
The ending. What the reader can now do, plain encouragement, and a sign-off. Never a summary.
Write to docs/articles/NN-slug.md, continuing whatever numbering exists.
6. Hand it back
Report the path, the word count, and anything you could not verify.
Reference files
references/prose-voice.md: written voice, and how it differs from spokenreferences/shared/simplified-english.md: ASD-STE100, the sentence and vocabulary rulesreferences/shared/voice.md: house style, all mediumsreferences/shared/change-analysis.md: scoping a diff, reading it, verifying claimsreferences/shared/prompt-recovery.md: finding the prompt in any agent's historyreferences/shared/tool-comparison.md: when a comparison is real and when it is filler