generate-writing-style.ts
36 lines · scripts/resolvers/preamble/generate-writing-style.ts at 3f79d81
1import type { TemplateContext } from '../types';
3/**
4 * Writing Style preamble section.
5 *
6 * v1.45.0.0 changes (T3):
7 * - Jargon list is referenced by path, not inlined. The 80-term list was
8 * duplicated into every tier-2+ skill (~1.5-2 KB × 48 skills = ~80 KB
9 * across the corpus). The pointer asks the agent to Read the JSON on
10 * first jargon term encountered — one extra Read per session, but the
11 * per-corpus payload is ~30 bytes.
12 * - When `ctx.explainLevel === 'terse'`, the entire section is replaced
13 * with a one-line pointer. Saves ~1.5 KB per tier-2+ skill in the
14 * opt-in terse build.
15 */
16export function generateWritingStyle(ctx: TemplateContext): string {
17 if (ctx.explainLevel === 'terse') {
18 return `## Writing Style\n\nTerse mode (build-time): skip jargon glossing, outcome-framing layer, and decision-impact closers. Lead with the answer.\n`;
19 }
21 const jargonPath = `${ctx.paths.skillRoot}/scripts/jargon-list.json`;
23 return `## Writing Style (skip entirely if \`EXPLAIN_LEVEL: terse\` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
25Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format is structure; this is prose quality.
27- Gloss curated jargon on first use per skill invocation, even if the user pasted the term.
28- Frame questions in outcome terms: what pain is avoided, what capability unlocks, what user experience changes.
29- Use short sentences, concrete nouns, active voice.
30- Close decisions with user impact: what the user sees, waits for, loses, or gains.
31- User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section.
32- Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses.
34Curated jargon list lives at \`${jargonPath}\`. On the first jargon term you encounter this session, Read that file once; treat the \`terms\` array as the canonical list. The list is repo-owned and may grow between releases.
35`;
36}