Eliminating Patch Prose
Given a spec littered with patch-prose like:
"Previously, Weight was conflated with Heat in V1, which caused the OMEGA_DRIFT bug. We fixed this in V2 by separating them, though V2.1 briefly reintroduced the issue via the STRICT profile before the NATIVE profile corrected it again."
Rewrite as a clean present-tense definition:
"Weight and Heat are independent semantics. Weight governs [X]. Heat governs [Y]. They do not interact."
The history is gone. The correction is gone. Only the current truth remains.
Progress:
- Identify all patch-prose passages (see detection patterns below)
- For each passage, extract the current, correct meaning only
- Delete the historical/comparative framing entirely
- Rewrite as a direct present-tense statement of fact
- Verify no "used to," "previously," "was fixed," "no longer," "as opposed to the old" language remains
- Check that parallel/current variants (profiles, modes, dialects) are described as coexisting contracts, not an evolutionary sequence
- Confirm the document is single-file deployable with zero dependency on prior versions, archives, or changelogs to be understood
- Re-read as a first-time reader with no version history—does every construct make sense standalone?
Detection Patterns
Flag any sentence containing:
- "previously," "used to," "originally," "in the old version"
- "this was fixed/changed/corrected/updated"
- "as opposed to how it worked before"
- "V1/V2/V0.x said... but now..."
- References to archives, hashes, snapshots, or transcripts as if the reader has them
- Justifying a current rule by narrating the mistake it replaced
Rewrite Rule
One sentence, one truth, no ghost. State what something is. Never state what something was unless the document is explicitly a changelog or migration guide (a different artifact from the spec itself).
If multiple current variants exist (e.g., multiple profiles, dialects, or execution modes), present them as parallel contracts defined independently—not as stages in a story. Use a comparison table or separate sections, never a "first we had X, then Y replaced it" narrative.
Example 1: Input:
"The RGWVS-NATIVE profile was introduced after the Strict Omega profile proved too rigid for runtime orchestration. Strict Omega required..."
Output:
"RGWVS-NATIVE and Strict Omega are both current profiles. RGWVS-NATIVE governs runtime orchestration: [definition]. Strict Omega governs [its own domain]: [definition]."
Example 2: Input:
"Note: earlier drafts of this DSL allowed Visibility to be inferred from Weight. This is no longer permitted, since it caused ambiguity in T9 contexts. Visibility must now be declared explicitly."
Output:
"Visibility is always declared explicitly. It is never inferred from Weight or Heat."
Example 3: Input:
"See Appendix C for the full version-history hash inventory documenting how the single-authority principle emerged across releases 4 through 9."
Output: (deleted entirely — this is deployment-irrelevant provenance, not spec content)
- Treat the spec as read by someone who has never seen any prior version and never will.
- Development history belongs in a separate artifact (CHANGELOG.md, migration notes, internal archive)—never inside the deployable spec.
- When a single-authority or ownership principle exists (e.g., "native semantics own meaning, host shells only transport/render/persist"), state it as architecture, not as the resolution of a past turf war.
- Definitions should be testable in isolation: could a reader implement this construct correctly having read only this paragraph?
- Use tables for parallel current variants instead of prose that risks slipping into sequential/historical framing.
- Sneaking history back in via justification. "We require X because Y used to fail" is still patch-prose—just state "X is required."
- Partial purges. Removing the narrative but leaving footnotes, appendices, or "see archive" pointers that assume reader access to deprecated material.
- Conflating "current profile" with "final version of an evolving thing." Parallel current contracts are not a hierarchy or timeline—don't imply one supersedes another unless it truly does and the other is being deprecated (in which case, deprecation is a current fact, not a history lesson).
- Re-teaching the bug to explain the fix. If the fix is correct and complete, the bug never needs to be mentioned.