Writing rules and prompt composition

@voice/writing-rules provides 20 contextual review rules, four task profiles and English/German examples. Use it to prepare review instructions or locate a small set of visible wording cues. Each rule includes an acceptable counterexample and the conditions under which its suggested revision preserves the meaning.

Recognize the negative pattern#

Each rule starts with an antiPattern: a concrete name, the observable symptom and its cost to the reader, in EN and DE. Names include Development diary, Not X, but Y, Hedge stacking, Summary loops, Unearned praise, False balance, Unprioritized laundry list and Forced triads and canned Q&A. The positive title and prompt describe how to review or remedy it.

A pattern is a contextual criticism, not proof that AI wrote the passage. A real comparison, useful history, uncertainty caused by missing or conflicting evidence or deliberate style choice can remain. relatedRuleIds identifies overlap: a laundry list concerns relevance and priority; formatting overload concerns presentation; a forced template can repeat form even when its facts differ.

Choose the reader's task#

Each profile selects six rules. The four added patterns are available through individual rule IDs and do not enlarge those defaults. A host can select individual rule IDs instead. For example, concrete-subject asks what an abstract phrase actually refers to; calibrated-uncertainty protects real uncertainty while questioning redundant qualifiers. Neither rule declares the word “preferred” inherently wrong.

The package builds from this workspace:

npm --prefix packages/writing-rules run build
npm --prefix packages/writing-rules test

The package is local and has not been published to npm. TypeScript declarations and JSDoc ship with its ESM build. JavaScript consumers can use // @ts-check.

Find candidate spans#

import { findWritingSignals } from '@voice/writing-rules';

const text = '😀 A powerful example.';
const result = findWritingSignals(text, { language: 'en' });
const first = result.signals[0];
// quote: "powerful", start: 5, end: 13, encoding: "utf16"
// kind: "surface-cue", reviewRequired: true

console.log(result.coverage.scannedRuleIds);
console.log(result.coverage.unscannedRuleIds);

The scanner uses 16 published regular expressions covering eight rules across EN/DE. The other twelve rules require contextual review. They find candidates such as stock adjectives, paired hedges or familiar contrast openings. They do not determine whether a qualifier is unnecessary, whether a claim is true or whether a document has a useful structure.

Offsets are zero-based, half-open UTF-16 positions in the supplied string. Quoted examples and code are included. Before converting a candidate into a Studio finding, the host must validate its unit, exact quote, source mapping and source version. The scanner does not write Finding objects, save feedback or edit source files.

maxSignals defaults to 50 and accepts 1–500. The returned truncated flag identifies omitted matches. Input is limited to 250,000 UTF-16 units. A selected rule without a lexical pattern appears in unscannedRuleIds; empty results do not establish that the text is good. These are writing signals, not evidence of authorship. See AI text signals and their limits.

Compose review instructions#

import { composeWritingReviewPrompt } from '@voice/writing-rules';

const review = composeWritingReviewPrompt({
  profile: 'public-docs',
  audience: 'Developers using Studio for the first time',
  goal: 'Open a source folder and complete one review',
  language: 'en',
  maxFindings: 5
});

console.log(review.catalogueVersion, review.ruleIds);
console.log(review.prompt);

Composition happens locally. The result contains instructions, selected rule IDs and the catalogue version. No model, provider or Runner starts. Audience and goal are trusted host configuration; supply source material separately as review data.

The prompt requests exact quotes, source locators, impact on the reader's task and reasons. Where a change is warranted, it asks for one to three distinct alternatives; otherwise it permits a justified keep decision. Examples never authorize invented facts or automatic replacement. Necessary qualifications, technical terms and accepted decisions remain protected.

The host chooses execution, validates any model response and presents the decision. This package does not validate generated findings or guarantee a model's output count. maxFindings is an instruction, not a cost or token limit.

Read the catalogue directly#

import {
  writingCatalogue, getWritingRule, selectWritingRules
} from '@voice/writing-rules';

const rule = getWritingRule('concrete-subject');
const rules = selectWritingRules({
  profile: 'public-docs',
  ruleIds: ['current-state', 'calibrated-uncertainty']
});

Selection keeps catalogue order and removes duplicate IDs. Unknown IDs and profiles throw. If both a profile and IDs are supplied, each ID must belong to that profile. An empty selection is allowed for inspection, but prompt composition requires at least one rule. Objects returned by the API are deeply frozen. The separate JSON exports are ordinary data objects; modifying them does not configure the API.

The package also exports @voice/writing-rules/catalogue.json and @voice/writing-rules/surface-patterns.json. Browser hosts can serve the built index.js directly or bundle its ESM entry. That module embeds private data and works independently of the optional JSON downloads. There are no runtime dependencies or network calls.

Sources and model-specific guidance#

Every rule links to source records with a URL, access date, relevant section, supported point and limitation. The relation separates provider prompt advice, editorial guidance, Voice's editorial derivation and contextual research. The bilingual examples are Voice-authored applications, except for the identified user-provided Voice documentation passage under Development diary. None is presented as an unlabelled captured model output or a measured model defect.

OpenAI's style guidance and Anthropic's prompting guidance inform prompt composition. They do not establish that every Claude or OpenAI/Codex output shares the same weaknesses. The host retains its actual model identity and evaluates the selected profile on its own task examples.

Microsoft's documentation guidance and Google's tense guidance inform the documentation profiles. The cited linguistic study provides research context; its aggregate observations are not a quality test for an individual passage.

OpenAI's April 2025 sycophancy report documents a particular rolled-back GPT-4o update. It supports examining unearned agreement, not assigning that behavior to every current model. The dated Model Spec informs evidence-weighted comparisons; it describes intended behavior.

Maintain and verify#

The canonical data lives in packages/writing-rules/src/catalogue.json and surface-patterns.json. Change the catalogue version when rules, examples, profiles or matching behavior change. Preserve stable IDs and revisit sources when provider guidance changes.

Tests cover catalogue integrity, references, keep cases, selection, prompt composition, distributed TypeScript declarations and exact lexical spans, including Unicode and truncation. These checks verify software behavior. They do not measure editorial benefit, detector accuracy or a provider's response quality. The existing four Studio local rules remain a separate implementation.