One File, Two Modes: Why I Dropped the Split Guide Plan
An article's source does not determine its type, the brief's content does. Detect the mode from content, keep one canonical guide, never duplicate enforcement.
TL;DR
The author nearly split their writing guide into two prompt files, one technical and one reflective, before realizing an article's type comes from the brief's content, not its source. A commit can spark a reflection; a dossier can spark a troubleshooting piece. One adaptive guide with two detected modes beats two files that drift.
The addendum for non-technical articles landed in this blog's writing style guide, and my first temptation showed up immediately: create a second prompt file just for them. Two parallel guides, one for technical pieces, one for reflections. It felt really tidy in my head.
I thought splitting them was the cleanest solution. The technical prompt full of commands and code, the non-technical prompt full of analysis and opinion. Just call the right file, done.
That guess was badly wrong. An article's source, whether a commit diff or a research dossier, does not determine its type at all. What determines it is the content of the brief. A commit can trigger a non-technical reflection about an architecture decision, while a research dossier can trigger a technical troubleshooting article. If I forced two parallel guides into existence, the only result would be duplicated logic that drifts over time.
Why two files are a trap
The simpler solution: detect the mode from the brief's content, and keep one guide, two modes in a single file. This resembles the feature detection principle MDN recommends [1]. Rather than guessing from origin identity, like browser sniffing from user-agent strings, which is very hard to do reliably and often a cause of bugs, you test the relevant property and condition behavior on the result [4]. I don't need to know where the brief came from, only what can be done with it.
Splitting the guide into two files also violates the Single Source of Truth principle: every data element is mastered in one place, which prevents inconsistency and simplifies version control [2]. Imagine a new redaction rule arrives. With two files, I have to remember to change both. The risk of forgetting is very real.
Anthropic's prompting documentation stresses something similar [3]: provide context and motivation inside the instruction, then let the model generalize from it. Instead of rigid instruction branches, I only need to explain that the mode is detected from the brief's content. Technical mode means the brief holds things a reader can run or check themselves. Non-technical mode means the evidence is a concrete trace of weighing, plus an equivalent artifact like a table or a checklist.
One file, two modes, mapped
The redaction gate applies just as strictly in both modes, no exemption just because an article is non-technical. One more thing often missed: the addendum's enforcement section was not duplicated into the prompt. That rule already lives in the check_redaction function from commit bd55ff0. One mechanism, one place. No need to rewrite it in the guide.
So it's easy to picture, here is how a single guide handles two different modes:
| Aspect | Technical Mode | Non-Technical Mode |
|---|---|---|
| Detection trigger | Brief holds commands, config, or code | Brief holds research, opinion, or evaluation |
| Evidence form | A sample script the reader can run | A decision checklist or trade-off table |
| Language style | Imperative: run, check | Concretely argumentative: I weighed X vs Y |
A checklist for your system
If you are designing a similar system and can't decide between route-by-property versus route-by-origin, use this five-point checklist:
- Can the origin identity be faked or change in the future? If yes, don't make it the only deciding factor.
- Is the property you check genuinely relevant to the outcome you want? Focus on what can be done, not who did it.
- Do multiple data sources claim the same thing? If so, pick one source of truth and treat the rest as reading material.
- Does this detection logic need updating in more than one place? If yes, your design has started to drift and needs consolidating.
- Can you explain the routing choice to a new developer in one sentence without naming a vendor? If not, the logic is too context-bound.
I personally avoid "it depends" solutions with no clear criteria. Choosing to detect the mode from the brief's content, not from the source's label, is a decision I made because classification by source proved fragile. One adaptive guide with two modes beats two guides that eventually contradict each other.
Writing a guide for yourself is just like writing code. If you find yourself copy-pasting the same logic into a new file just because the case differs, that is not refactoring. That is technical debt you are building with your own hands.