Why One Writing Prompt Was Split Into a Contract and Mode Files
A 228-line prompt that fought itself became a 205-line shared contract plus four swappable mode files. The design logic, explained.
TL;DR
Splitting one bloated 228-line prompt solved conflicting instructions by separating rule ownership: a shared contract locks universal invariants like citation and privacy rules, while swappable mode files handle tone and structure. Four modes—report, news, tutorial, explainer—are chosen by the promise made to readers. Hard structure limits and strict evidence requirements keep every output consistent and checkable.
In the early stages of system development, a single writing prompt file grew to reach 228 lines of mutually conflicting instructions. When reviewing the file, it was clear that the instruction to open the article with a casual tone directly clashed with the instruction commanding that every judgment must be attributed to a specific speaker. These two commands fought each other in the same space, resulting in an inconsistent and confusing draft for the reader. The applied solution was not to delete one of the rules, but to strictly separate rule ownership. The system now uses a shared contract that governs invariants, plus one swappable mode file according to the article's needs.
The fundamental reason why a single writing prompt is split lies in the conflict between the need for consistency and flexibility. When all rules are placed in a single monolithic container, a change in one aspect often unexpectedly breaks another. This separation adopts a mindset similar to stylesheets in web programming. Just as a stylesheet overrides base rules only on specific elements, the mode file overrides the base contract only on register and structure aspects that genuinely need to vary. This approach ensures that core rules remain intact while style variations can be managed in isolation without the risk of instruction conflicts.
Separation of Rule Ownership
The shared contract, now totaling 205 lines, handles all aspects that must not change, regardless of the type of article being written. These aspects include facts discipline, citation systems, structure gates, redaction of sensitive data, search engine optimization, and text-to-speech friendliness. All these rules apply universally to every system output, creating a stable foundation for the writing process.
Facts discipline requires every paragraph carrying an argumentative load to bring concrete evidence. The citation system ensures every key number or claim has a link to a source registered in the research ledger. Structure gates limit visual complexity, such as restricting the number of subheadings to maintain narrative flow. Sensitive data redaction enforces an absolute ban on using real IP addresses, whether public or private. The system always replaces these addresses with documentation ranges like 203.0.113.0/24 or 198.51.100.0/24 according to RFC 5737. Real API keys, tokens, or passwords are always replaced with explicit placeholders like
Text-to-speech friendliness ensures that non-standard abbreviations are written out in full and links use meaningful word anchors, not raw URLs that would be read awkwardly by machines. Inline code is limited to a maximum of three per paragraph with short, speakable content, preventing screen readers from monotonously spelling out character by character.
The mode file, by contrast, handles aspects that must adapt. The register mandate has completely flipped. Formal Indonesian is now the default standard. Particles like "sih", "nih", "dong", and "lho" are prohibited. Slang forms like "nggak", "udah", "gimana", and "pakai" are also not allowed. This shift ensures the writing tone remains professional, predictable, and aligned with modern technical documentation standards.
The writer's persona is also removed by default. The voice used is impersonal and neutral. Sentences like "I traced" are changed to "the claim was tested". This approach places evidence at the center of attention, not the writer's personal experience. The opinion budget is strictly regulated based on the selected mode, preventing unfounded personal opinions from entering the writing.
Four Modes and the Promise to the Reader
Mode selection is not determined by the source material, whether it is a commit note or a research dossier. Mode selection is entirely determined by the promise the material makes to its reader. If the reader expects a verdict on a claim, the system uses the report mode. If the reader needs to understand how a concept works, the system uses the explainer mode. This principle ensures that the writing structure always aligns with reader expectations from the very first paragraph.
| Promise to the Reader | Selected Mode | Main Focus |
|---|---|---|
| Reader gets a verdict on a claim | Report | Claim-by-claim status, method box |
| Reader learns what happened | News | Inverted pyramid, clear attribution |
| Reader will run something | Tutorial | One step equals one action |
| Reader needs to understand a concept | Explainer | Fact hook, zero background assumptions |
Understanding why a single writing prompt is split helps the writer choose the right tool before starting to draft. The report mode allows exactly one sourced judgment in the closing section, providing room for final synthesis without becoming empty opinion. The news mode requires every judgment to be attributed to its speaker, maintaining the objectivity of event reporting. The tutorial and explainer modes take no personal stance whatsoever, focusing entirely on the clarity of instructions or concept explanation.
The tutorial mode, for example, adopts vocabulary from the Diataxis framework. Each technical section follows the sequence of concrete problem, concrete steps, and a result the reader can verify. The explainer mode uses a fact hook at the beginning and assumes zero background knowledge, ensuring complex concepts are accessible to general readers without sacrificing technical accuracy. The news mode adopts an inverted pyramid structure, placing the most important information in the opening paragraph that answers the basic elements of the event, followed by supporting details and clear attribution.
Structure Limits and Evidence Discipline
Hard structure gates are applied to maintain output quality and prevent unnecessary fragmentation. For articles under 1000 words, the number of H2 subheadings is limited to a maximum of three. This restriction forces the narrative to flow naturally rather than breaking into isolated small pieces. Tables are limited to a maximum of one, and are only used if the data makes no sense when written as ordinary sentences. A closing section with an explicit title is strictly forbidden to avoid writing patterns that feel like machine-made templates.
Evidence discipline is an absolute requirement in every mode. Every paragraph carrying an argumentative load must bring concrete evidence. This evidence can be a cited number, a quoted sentence with attribution, a command with expected output, or a named decision with its trade-off. Pure description without checkable artifacts is considered a draft defect. Phrases like "according to official documentation, the steps are" without including a specific link or command do not meet this standard.
Non-technical articles still require equivalent evidence artifacts. This can be a comparison table with real numbers from research, a decision checklist that readers can apply to their own situations, or an explicit trade-off framework. The phrase "depending on needs" without clear criteria is not accepted as a valid argument. Readers must always have a way to test the presented claims against their own situation, ensuring the writing provides practical value and not just general opinion.
When an article draft is completed, the remaining question is no longer whether the instructions are long enough or whether the template has been fulfilled, but rather what promise the writing actually makes to its reader and whether the presented evidence is sufficient to fulfill that promise. This split is also not a return to separate guides for each technical topic; it is a clean separation of responsibilities.
Sources: