mirror of
https://github.com/garrytan/gstack.git
synced 2026-06-29 21:15:37 +02:00
Garry Tan
da5f26872f
A.2 jargon dedup: generate-writing-style.ts replaces the inlined 80-term jargon list with a one-line pointer to scripts/jargon-list.json. The list was duplicated into every tier-2+ skill (48 of 51 skills); inlining cost was ~1.5 KB × 48 = ~70 KB across the corpus. Pointer cost is ~30 bytes per skill. Agents Read the JSON once per session on first jargon term encountered; thereafter the terms array is the canonical reference. A.3 terse build flag: --explain-level=terse compresses preamble prose at gen time. When the flag is set, writing-style collapses to a one-line terse directive and completeness-section + confusion-protocol + context-health are dropped entirely. The default build keeps the runtime-conditional behavior intact (sections still render; the model skips them when EXPLAIN_LEVEL: terse appears in the preamble echo). Terse build is opt-in for users who want shipped skills to match their runtime preference and avoid the per-session terse-mode dead prose. TemplateContext gains an optional `explainLevel: 'default' | 'terse'` field. Default builds set it to 'default'; --explain-level=terse sets 'terse'. Resolvers gate their output via `ctx?.explainLevel === 'terse'`. Measured impact (default build, post-T3): - Total corpus: 2,847 KB → 2,812 KB (saved 35 KB) - ship.md: 160 → 159 KB - plan-ceo-review.md: 128 → 127 KB - Top 10 heaviest: all slightly smaller from jargon pointer Larger compression lands in T4 (catalog trim) and T7 (atomic regen across the full Phase A pipeline). The terse build path further compresses to ~711K tokens vs default ~725K (saved ~14K tokens corpus-wide). Test plan: - bun test test/gen-skill-docs.test.ts: 389 pass (no regression) - bun test test/resolver-entry.test.ts: 6 pass - bun test test/helpers/capture-parity-baseline.test.ts: 4 pass - bun run gen:skill-docs --explain-level=terse: ship.md drops completeness + confusion-protocol + context-health sections; writing-style collapses to one-line terse directive 48 SKILL.md files updated (every tier-2+ skill picks up the jargon pointer). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
37 lines
2.0 KiB
TypeScript
37 lines
2.0 KiB
TypeScript
import type { TemplateContext } from '../types';
|
||
|
||
/**
|
||
* Writing Style preamble section.
|
||
*
|
||
* v1.45.0.0 changes (T3):
|
||
* - Jargon list is referenced by path, not inlined. The 80-term list was
|
||
* duplicated into every tier-2+ skill (~1.5-2 KB × 48 skills = ~80 KB
|
||
* across the corpus). The pointer asks the agent to Read the JSON on
|
||
* first jargon term encountered — one extra Read per session, but the
|
||
* per-corpus payload is ~30 bytes.
|
||
* - When `ctx.explainLevel === 'terse'`, the entire section is replaced
|
||
* with a one-line pointer. Saves ~1.5 KB per tier-2+ skill in the
|
||
* opt-in terse build.
|
||
*/
|
||
export function generateWritingStyle(ctx: TemplateContext): string {
|
||
if (ctx.explainLevel === 'terse') {
|
||
return `## Writing Style\n\nTerse mode (build-time): skip jargon glossing, outcome-framing layer, and decision-impact closers. Lead with the answer.\n`;
|
||
}
|
||
|
||
const jargonPath = `${ctx.paths.skillRoot}/scripts/jargon-list.json`;
|
||
|
||
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)
|
||
|
||
Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format is structure; this is prose quality.
|
||
|
||
- Gloss curated jargon on first use per skill invocation, even if the user pasted the term.
|
||
- Frame questions in outcome terms: what pain is avoided, what capability unlocks, what user experience changes.
|
||
- Use short sentences, concrete nouns, active voice.
|
||
- Close decisions with user impact: what the user sees, waits for, loses, or gains.
|
||
- User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section.
|
||
- Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses.
|
||
|
||
Curated jargon list lives at \`${jargonPath}\` (80+ terms). 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.
|
||
`;
|
||
}
|