# Write prose This page is one of the five skills that ship with Ramabana. A skill is a piece of markdown that the agent reads when a task calls for it, so that the guidance costs nothing in turns that do not need it. The system prompt lists every skill the session found with a one-line description, the `read_skill` tool returns one in full, and `/skill write_prose` prints it in a terminal session. The skill’s text is this module’s docstring. nbdev builds it from the description line above and the exported markdown cell below, and `pyproject.toml` registers the module under the `pyskills` entry point as `write_prose`, so any agent built on shalya can find it once Ramabana is installed. To change what the agent reads, edit the exported cell. The agent reads this skill before it writes prose with an author’s voice, such as a blog post or release notes. Its companion `write_docs` covers reference prose. Read this before writing narrative prose: blog posts, essays, announcements, talks, release notes with a voice, and anything else where the author is present on the page. For reference prose – docstrings, comments, READMEs, API docs, changelogs, PR descriptions, commit messages, messages to a colleague – read `write_docs` instead. The same slop is banned there; the register is voiceless. The standard here is The Economist’s. Here is a passage from The Economist: > No form of emissions reduction, though, can quickly bend the current > trajectory.\[1\]\[2\] Endurance is what remains.\[3\]\[14\] Making air > conditioning more efficient, cheap and widespread\[10\] saves > lives\[6\] and fits well with other policy goals, like making clean > electricity cheap to produce and consume.\[7\] Ten years ago a > commitment to phase out the fluorinated gases in cooling systems was > reached in Kigali, the capital of Rwanda.\[8\]\[9\] There is scope for > extra international efforts to improve the machinery that uses > them.\[7\]\[19\] This could double the cooling benefit of phasing out > the gases.\[6\] Each sentence sets out to say one thing, says it, and stops. It is plain English. It carries no byline and needs none. Plainness does the work. It is not selling anything. It lets the reader work out the takeaways. Write like that. Here is a horrendous rewrite, as sloppy as possible: > In this piece, we’ll dive deep into the fascinating world of > cooling\![1\] 🌡️\[15\] Here’s the thing:\[2\] emissions reduction > alone **isn’t going to cut it**. In today’s rapidly-warming > world,\[4\] it’s not about quick fixes — it’s about *endurance*.\[3\] > When it comes to\[5\] air conditioning, a technology that cools indoor > air,\[20\] one might argue\[5\] that a comprehensive, holistic > approach — making units more efficient, more affordable, and more > accessible\[10\] — could potentially help save countless lives in some > cases,\[6\] while seamlessly aligning with broader policy goals like > fostering\[7\] clean, affordable electricity for all, and also, it’s > worth noting,\[5\] building on the pivotal commitment to phase out > fluorinated gases that was reached ten years ago in Kigali — the > vibrant capital of Rwanda —\[16\] a commitment that has reshaped the > landscape of cooling policy and continues to empower stakeholders\[9\] > across the realm of climate diplomacy.\[8\] > > But here’s where it gets really exciting.\[11\] 🤯 The Kigali deal > isn’t just a treaty — it’s a **game-changer**.\[3\] Here’s what’s > fascinating:\[24\] the machinery that leverages\[7\] these gases gets > a myriad of enhancements via this framework,\[19\] consistent with the > glidepath,\[23\] which could unlock further benefits, and which, > honestly,\[5\] may potentially double the cooling upside of phasing > them out, depending on context.\[6\]\[8\] Getting there is just\[12\] > a matter of commitment. The reason is simple:\[22\] demand keeps > rising, and real progress rides on\[21\] frameworks like these. > Furthermore, as we can see,\[5\] the journey ahead is a rich tapestry > of innovation: the tech we build, the deals we strike, the grids we > green\[14\] — a testament\[7\] to what we can achieve when we navigate > this challenge together. In conclusion:\[5\] the bottom line?\[13\] > Endurance is the name of the game — in other words, success is all > about sticking with it for the long haul.\[14\] 💪 Do **NOT** write like that. The numbers below refer to the \[bracketed\] markers in both passages. Where a number appears in each, the pair is the sloppy and the plain version of the same thing. Entries 17, 18, 25 and 26 are tells at scales the one-paragraph sample cannot show. 1. Throat-clearing: an opener that announces the piece instead of starting with the subject. “In this piece, we’ll…”, “Let’s dive into…”, “In this section, we will…”. The first sentence should do real work. 2. Announce-then-deliver: a label and a colon in place of stating the fact (“The fix: retry on timeout”, “Here’s the thing: …”). The label is scaffolding. State the fact as a sentence: “Retrying on timeout fixes it.” 3. Not-X-but-Y: “It’s not X, it’s Y” / “isn’t just X, it’s Y”, the number one LLM rhetorical crutch. State the positive directly. Restructure every time. 4. Today’s-world opener: “In today’s fast-paced/digital/modern world…”. 5. Filler phrases, which add zero information. State the thing directly. “It’s worth noting that”, “It’s important to note that”, “Notably”, “Importantly”, “Interestingly”, “As we can see”, “As mentioned earlier”, “In conclusion”, “To summarize”, “When it comes to”, “In the realm of”, “One might argue that”, “It could be suggested that”. “A comprehensive/holistic/nuanced approach to” is “an approach to”. For “Furthermore”/“Moreover”/“Additionally” use “and”, “also”, or start a new sentence; if every paragraph opens with “However” or “Furthermore”, drop the transition and start with the subject. Two more, each with its own reason: - “honest”/“honestly”/“to be honest” as a throat-clear. In speech this flags a rare, significant admission. Sprinkled everywhere it is noise. Delete it in nearly every case. - “deliberately”/“intentionally”/“carefully”/“thoughtfully”: adverbs about the author’s mental state rather than the thing. In a design doc every recorded choice is already deliberate, and the explanation that follows does the work. Keep one only where the reader would otherwise suspect an accident and no explanation follows (“the file is deliberately empty”). 6. Hedging, the worst offender. “This approach may potentially help improve performance in some cases” means nothing. Say “this is faster”, or say “we haven’t benchmarked this yet”. The original commits: “saves lives”, “could double”. 7. Inflated diction: puffed-up words where plain ones exist. enhance/leverage for improve/use, plus seamlessly, fostering, pivotal, myriad, landscape, realm, empower, journey, tapestry, testament, navigate. The banned-word lists below are the fuller reference. 8. Sentence sprawl: one over-long sentence stacking clauses that should be separate sentences, chained with “so”, “which”, “but” and “and”, each extending or qualifying the last. One idea per sentence. When a draft sentence joins two thoughts, try the split. Keep the join only where the connection itself is the point. 9. Artifact-as-agent: the commitment “has reshaped the landscape” and “continues to empower”. People reached a commitment. Say what happened, with the actors in place. Three stacked habits make these sentences, as in “Your tests shaped the ones that landed”. An inanimate subject stands where the doer belongs (“this PR introduces”, “the change enables”), so the person who did the work vanishes. The object is pointed at through a relative clause or a metaphor (“the ones that landed”) rather than named (“our new tests”). And a who-did-what story is compressed into a single transitive clause, an aphorism that sounds polished because it discards the actors and the order of events, most often as a sentence-final flourish. Rewrite as the actual events with the actual actors: “I took your tests as inspiration and added some updates based on these changes.” 10. The AI triad: three parallel “more X” adjectives. The original varies its forms. LLMs cannot resist symmetry generally: three pros, three cons, five steps, equal-length sections, bullets where a sentence would do, every list item opening with the same grammatical structure. Catching yourself writing exactly three or five items is a reason to be suspicious. Nobody structures their actual thoughts that neatly. 11. Teaser pivot: “but here’s where it gets really exciting”, “X, but the main event is Y”, “but the real story is…”. A sibling of tell 3: a contrast flourish that withholds the point to build fake suspense. State the facts in order and let the emphasis come from what follows. 12. Minimizing “just” as a casual softener (“it’s just a wrapper”, “just works”). Usually delete it. Where the restriction genuinely matters, “only” is plainer. 13. Rhetorical wrap-up: a rhetorical question as a closing flourish. 14. Restatement: saying the same thing twice. The original says it once, in four words. The commonest form is a lead sentence that summarizes the paragraph it starts. Everything it says reappears, with more detail, in the sentences that follow. Delete it and nothing is lost: > Failures are visible now too. A startup failure used to > print to the server log and leave a half-booted dialog that looked > ready. It now raises, the user gets an error toast and a red > status dot, and the dialog stays editable. The mirror form is the closing sentence that summarizes the paragraph or the piece it ends. It is the taught essay shape, and the strongest LLM habit of the lot. End on the last fact. The same disease occurs inside a sentence, where a final clause restates the opening, and between a heading and its section’s first line. Its listy form puts a category phrase, a colon, then a parallel list unpacking it (“it should see what you have been doing: the cells you ran, what they printed, the plots you drew”). Cut whichever side of the colon says less. Ask whether deleting the phrase removes any information from the document. If not, delete it. Summaries earn their place at document scale, in an abstract or a TL;DR, not per paragraph. And prefer the shorter phrasing of the same fact. 15. Decoration: emoji, and decorative bold and italics. Bold and italics inside a paragraph are for very rare use. Avoid emoji and non-ASCII unicode unless the user asks otherwise: “-\>”, not an arrow glyph. 16. Splicing: em-dash interruptions and their kin. Avoid em dashes entirely. Substituting `-` or `--` is just as bad, being the same interrupted-clause habit with different punctuation. The clause after the splice is usually restatement, or an obvious implication of the one before it. Try deleting it first (tell 14). Where both clauses carry their own weight, split. Two short sentences nearly always read better than one spliced sentence. Phrase combiners like `:` and `;` should be rare in narrative prose. A colon introducing a list or an example is fine, subject to tell 14. A colon splicing two clauses is the habit to avoid, and swapping one in is no fix for an em dash. 17. Monotone rhythm: topic sentence, elaboration, example, wrap-up, paragraph after paragraph. Mix it up. Real writing is lumpy. Some sections run long because they need to. Others are two sentences because that is all there is to say. 18. False depth: restating the problem in fancier words, listing obvious considerations, concluding with “it depends”. Real depth comes from specifics, data and edge cases. 19. Recipient-as-subject: the thing that benefited is promoted to subject, the verb is “gets/gains/receives”, and the doer hides in a trailing “via”/“through”/“thanks to” phrase: “the parser gains three node kinds”. As in tell 9 the actor vanishes; the artifact moves from performing the action to receiving it. Either name the doer and the deed (“I added three node kinds to the parser”), or drop agency and state the new state (“there are now three node kinds in the parser”). The second avoids a drone of “I added…” sentences. What is banned is the middle form, where a fake event hides the real actor in a preposition. 20. Explaining the known: telling readers what they already know. Defining a term the audience uses daily (“air conditioning, a technology that cools indoor air”), spelling out an inference they make instantly, or stating a practice they take for granted. Tell 14 is repeating yourself. This is repeating the reader. What counts as known depends on the audience, so name the audience when writing or reviewing, and cut what that reader would skim past. 21. Decorative verbs: an inanimate subject whose verb is not what actually happens, with no person hidden. The sentence states a property or a mechanical event and the verb arrived for vividness: “native ids ride in summary rows”, “an id earns its place”. Nothing rides or earns. Say what happens: ids appear in rows, an id qualifies. The subject may stay inanimate. The verb has to be the plain word for the event. Standard technical vocabulary is not decoration: a span opens with its heading, you walk the tree, recursion bottoms out, a cache goes stale. Those are the words a maintainer says at a whiteboard, and that is the test. Would you say this verb at the whiteboard, or did it arrive for texture? The banned “land” and “shape” entries below are instances of this tell. 22. Explanation colons: a colon gluing an assertion to its explanation, both halves full clauses (“the address layer has no semantic gaps: every failure is a verification failure”). A colon is for introducing a list, an example or a definition. An explanation is a sentence, so give it a period. Tell 2 is the label form of this, where the left half is a stub rather than a clause. These accumulate one defensible instance at a time in dense technical prose, until every sentence has the same claim-colon-reason shape. 23. Undefined jargon, tell 20’s twin in the other direction. Tell 20 repeats what the audience knows; this assumes what it does not. A term of art dropped without definition (“consistent with the glidepath”, or “carrier” in a design doc) loses the reader from that sentence on. The tell covers locally-invented terms only: a project’s own coinages and internal vocabulary. Established external terms of art (kqueue, monad, CFRunLoop) are not violations however specialized, because the audience can look them up. A coinage cannot be looked up anywhere. The two tells are one audience judgment. Name the audience, cut what they know, and define what they do not at first use, or use a plain word instead. 24. Appraisal preamble: a clause that appraises the content it introduces instead of delivering it. “the reason is worth being precise about”, “here’s the key point”, “what’s interesting is”, “crucially”. The subject is a discourse object (“the reason”, “the point”, “the distinction”) carrying an appraisal (“worth”, “key”, “important”) and no domain content. Tell 2 announces with a label. This advertises with a compliment, usually mid-paragraph, dressed as emphasis. Deliver content, never advertise it. 25. Over-structuring: section headings imposed on a document too short to need them. Headings are navigation. A document that fits on a screen needs none. The document-scale form of tell 10’s symmetry habit. 26. Consequence glue: any clause joined by “, so”. Treat every occurrence as wrong. The appended clause is restatement, the obvious, or a link that does not hold; and on the rare occasion the consequence is real, it deserves its own sentence, where its logic has to survive on its own. Delete the clause or reorganise. “the zmq hop must be lossless, so shedding belongs to the client queue” becomes “the zmq hop must be lossless. Shedding belongs to the client queue.” Tells 9 and 19 are two faces of one device linguists call agent defocusing: grammar that pushes the true actor out of the subject seat. The passive is the third face. The positive rule is Williams’s characters-and-actions principle: make the doer the subject and the deed the verb. A tool subject with a mechanical verb (“the parser rejects malformed input”) is not defocusing. The tool really is that event’s actor, though its verb still has to pass tell 21. The tell fires when a person’s deed is narrated with the person missing. Tell 21 is the neighbour rather than another face. There, no person exists, and the verb rather than the subject seat is what goes wrong. Tells 1, 2, 11, 13 and 24, along with tell 5’s noting fillers, are all metadiscourse: text about the text rather than about the subject. Openers advertise the piece, labels advertise the fact, pivots advertise excitement, closers advertise closure, preambles advertise importance. Signposting earns its place at document scale, in a table of contents or an abstract, the same boundary tell 14 draws for summaries. ## Banned words Statistically overrepresented in LLM output. Replace or delete on sight. - Kill on sight: delve, utilize, leverage (verb), facilitate, elucidate, embark, endeavor, encompass, multifaceted, tapestry, “a testament to”, paradigm, synergy, holistic, catalyze, juxtapose, nuanced (as filler), realm, landscape (metaphorical), myriad, plethora, minted (metaphorical), and -bearing compounds such as load-bearing and text-bearing. Also shape/shaped as loose jargon for structure or influence (“same shape”, “the shape of the API”, “your tests shaped ours”); it is fine as a geometric term or for array dimensions, and for influence say what actually happened: adapted, copied, informed. Also land/landed/lands as metaphor (“the fix landed”, “a note lands in the output”); things do not land, so say merged, committed, pushed, released, appears. - Suspicious in clusters, so remove most of them: robust, comprehensive, seamless, cutting-edge, innovative, streamline, empower, foster, enhance, elevate, optimize, pivotal, intricate, profound, resonate, underscore, harness, navigate (metaphorical), cultivate, bolster, cornerstone, game-changer, invariant (usually “rule” or “guarantee”; keep it only where nothing plainer is accurate). - Replacements are almost always simpler words: utilize -\> use, leverage -\> use, facilitate -\> help, robust -\> strong, comprehensive -\> complete, seamless -\> smooth, empower -\> let, foster -\> encourage, enhance -\> improve, optimize -\> improve. The lists are examples of one rule: always reach for the simplest, most normal, least jargony word that is still correct. Much of the clarity core above is codified in ASD-STE100: one idea per sentence, active voice with the doer as subject, one meaning per term, and plain words over inflated ones. Borrow the discipline, not the sound. STE is voiceless and choppy by design, built for non-native mechanics under time pressure, and it would fail the standard the Economist passage sets. That sound is correct in reference prose, which `write_docs` covers. Never hard-wrap prose. Write each paragraph as one continuous line and let the display soft-wrap it. Manual line breaks mid-paragraph make text painful to reflow, edit and copy. In technical prose, put code symbols in backticks: function names, parameters, file paths, module and package names, and literal syntax. ## What good prose sounds like Good writing has a voice. You read it and someone is there. They have opinions. They are occasionally wrong. They will make a joke in the middle of a technical explanation and it works. The sentences are not all the same length. Most are short. An occasional longer one earns its length by carrying a single connected thought too big to split. That variation is what keeps a reader moving. LLMs cannot do it unprompted: every sentence comes out the same mid-length, the same mid-energy. Say what you mean. “This is broken”, not “there may be some areas for potential improvement”. Say “use”, not “utilize”. If a different topic could be swapped in and the paragraph still read fine, nothing has been said yet. Get specific. Not “improves developer productivity” but “saves me twenty minutes every deploy”. To have a draft checked, send these rules and the draft to a subagent with `delegate_search`. Name the audience, so tells 20 and 23 can be judged. Ask for flagged spans rather than a rewrite. Only do this when the user asks for a prose check.