We built a TypeScript schema that encodes Bluesky's 300-character cap, a zero-hashtag policy, and a banned-phrase list inside one configuration object. Before that, our system maintained prompt instructions in one location and quality validation checks in another. When an editor modified the prompt to adjust structural tone, the evaluator kept rejecting output for failing the old requirements. The engine drafting the text and the engine reviewing it were reading different sources of truth, forcing generated copy into a continuous loop of failed checks.
Moving channel constraints into a single specification changes how copy is produced and verified. A surface spec acts as the authoritative contract for a target network. It sets exact character bounds, structural rules, inline link handling, and prohibited expressions. When an automated system drafts copy, it serializes the spec directly into the prompt context. When an evaluation step grades the output, it imports that same spec object to execute programmatic assertions.
One contract for both sides of the pipe
In automated editorial systems, prompt design and quality assurance usually drift apart. A system prompt instructs a model to stay under 280 characters, skip hashtags, and open on a concrete detail. Farther down the pipeline, a test suite evaluates the returned string using a separate regular expression or a distinct grading prompt.
When these descriptions do not align perfectly, failures recur without clear cause. A prompt might successfully direct a language model to craft a multi-paragraph breakdown for LinkedIn, but if the validator expects fewer than three lines, the pipeline flags an error. Updating the prompt to fix one style issue while leaving the downstream validator untouched creates silent failures or systemic rejection loops.
A surface spec resolves this misalignment by supplying both sides of the system from one file. The system prompt does not contain static, handwritten instructions for platform formatting; it imports the surface spec object and transforms its properties into structured rules within the model context. Simultaneously, the grading module consumes the identical object, mapping keys like maxLength, allowHashtags, and requiredOpeningType to unit tests. When a platform constraint changes, updating one schema file immediately aligns both generation and evaluation.
Encoding editorial style as data
Editorial guidelines often feel subjective until they are broken down into programmatic checks. A surface spec translates editorial standards into unambiguous data structures.
Different networks enforce distinct structural mechanics. A post written for Bluesky demands concise character budgets and zero hashtags, whereas a LinkedIn update requires line breaks between distinct thoughts and space for contextual detail. Rather than writing separate documentation files for each platform, a surface spec captures those differences as schema properties:
- Character limits establish strict bounds on raw text, accounting for platform-specific link wrapping behavior.
- Tagging rules determine whether hashtags and mentions are allowed, stripped, or converted into plain text.
- Opening constraints mandate the precise structure of the first line, requiring a concrete fact over introductory preamble.
- Banned framings list specific phrases and tropes that trigger an immediate failing mark during grading.
Representing these rules as typed data allows systems to run deterministic validation passes before copy reaches an editorial queue or a publishing API.
Eliminating the generator-critic disconnect
Language models generate cleaner copy when provided with explicit boundary conditions. Automated evaluators judge output accurately only when measuring against those same boundaries. If the evaluator applies a stricter rubric than the prompt provided, every draft gets discarded. If the evaluator applies looser criteria, low-quality copy passes through unchecked.
A shared surface spec aligns the context window of the generator with the criteria of the critic. If the evaluator rejects a candidate because the opening line contains abstract narrative framing—such as describing a project as "a broad shift"—it references the exact rule key defined in the surface spec. The pipeline then attaches that failing key to the retry context, giving the generator explicit instructions on which constraint was violated.
This feedback loop grounds quality control in objective criteria. The generator works against defined parameters, and the critic verifies the output against the same contract.
Systemic clarity across channels
Defining platform rules as codebase configuration changes how publishing pipelines scale. Adapting to network policy shifts no longer requires auditing multiple prompt files or updating disconnected test scripts.
If a platform modifies its character limits or adjusts how link card preview length affects string totals, modifying the surface spec updates the entire workflow. The generation context adapts, the downstream validator adjusts its assertions, and the testing suite reflects the update immediately without touching application code.
When the generator and the critic execute against the exact same contract, published output stays consistent across every channel.
Weekly Briefing
The studio briefing.
What we’re building across the portfolio, every Monday.
By subscribing, you agree to receive occasional studio updates from Total Ventures. No spam. Unsubscribe anytime. Privacy Policy
Written by
Founder, Total Ventures
Solo-founder building and operating a multi-brand product studio with AI agents. Writing about building, operating, and shipping.
