From fbd37b790ca8fbb686617da406dea148c6e06402 Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Sun, 27 Sep 2026 18:00:03 +0300 Subject: [PATCH 1/4] drop STE-based strict artifact writing mode The Strict output style carried a second writing layer for durable artifacts, derived from ASD-STE100 Simplified Technical English. Remove that layer and its cross-reference so the style governs conversational voice only. Artifact voice is handled elsewhere, not inside a swappable style. --- dot_claude/output-styles/private_strict.md | 53 +--------------------- 1 file changed, 2 insertions(+), 51 deletions(-) diff --git a/dot_claude/output-styles/private_strict.md b/dot_claude/output-styles/private_strict.md index bf98f3c..dd7d961 100644 --- a/dot_claude/output-styles/private_strict.md +++ b/dot_claude/output-styles/private_strict.md @@ -8,9 +8,8 @@ keep-coding-instructions: true This shape governs conversational replies to the user, and nothing else. Do not use it inside a file or an artifact. A document, README, runbook, commit message, -release note, or pull request description follows the strict artifact mode at the -end of this file, not this template. Never put the 🔍/⚠️/✅/➡️ sections or emojis -inside a file you write. +release note, or pull request description does not follow this template. Never put +the 🔍/⚠️/✅/➡️ sections or emojis inside a file you write. Do not tell a story. Do not reason in prose about where a hedge or a limit fits best in a sentence — wasteful, and hard to read. Put the answer in static lists, @@ -145,51 +144,3 @@ checking, not a full analysis. Do not write out provisional conclusions or long reasoning that your own findings might overturn a moment later. Hold the substance until the evidence is in, so the reader's attention is spent only on conclusions that hold. - -## Writing artifacts: strict mode - -The rules above govern conversation, and that is the default. Writing a durable -technical artifact is different. For documentation, READMEs, runbooks, -procedures, error messages, release notes, reports, commit messages, and pull -request descriptions, switch on this stricter layer on top of the plain-language -rules above. It comes from ASD-STE100 Simplified Technical English. Do not carry -it into conversational replies — the no-contraction rule, the banned modals, the -hard word caps, and the no-"-ing" rule make the voice stiff and clipped, which -fights the plain, scannable style the rest of this file asks for. - -Where dedicated instructions already define a format — commit messages and pull -request descriptions often have their own rules set elsewhere — follow those -first. Apply this strict mode only where they are silent, and never let it -override a format rule they state. - -CLASSIFY FIRST. Procedural text tells the reader what to do: imperative mood, at -most 20 words per sentence, one instruction per sentence. Descriptive text -explains: simple tenses, at most 25 words per sentence, one topic per paragraph, -at most six sentences per paragraph. Do not mix the two in one passage. - -VERBS. Use only the infinitive, imperative, simple present, simple past, simple -future, and past participle as an adjective. No present perfect ("has completed" -→ "completed"). No "-ing" verb forms ("making it easy" → start a new sentence). -Active voice; use passive only in descriptions when the actor is unknown. -Approved modals: can, will, must. Banned: should, would, may, might, could. For -"should", write "must" if it is required, or delete it if it is optional. - -SENTENCES. Keep full grammar: no contractions, keep articles, keep "that" ("make -sure that the file exists"). Put conditions before commands, with a comma: "If -the test fails, read the log." No semicolons — write two sentences. Use a -vertical list for more than two items or steps. - -WORDS. Apply the plain-language word discipline above. Additionally, hold one -word to one meaning across the whole document — pick one of check/verify/confirm -and keep it. Noun chains of at most three words; break longer ones with -prepositions ("the timeout value for the connection pool"). - -NEVER TOUCH. Code blocks, identifiers, CLI commands, file paths, quoted error -messages, product names. Each counts as one word toward the sentence limits. - -SELF-CHECK before returning prose: scan for contractions, "has been", "should", -", making", and semicolons. Count the words in your three longest sentences and -split any over the limit. Collapse synonym rotation. - -Do not apply these rules to code, to code comments that quote code, or to -marketing copy the user asks for. From 7228316b1fa635e34961d13c42bf6287cf4f6e3a Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Sun, 27 Sep 2026 18:00:08 +0300 Subject: [PATCH 2/4] route artifact writing to dedicated writer subagents Add an Artifact Authoring rule to the shared workflow guidelines so all runtimes (Claude, Codex, OpenCode) route durable artifact writing to a writer subagent matched to the artifact type, rather than writing the artifact in the coordinating agent. This replaces the removed STE-based artifact voice with a dispatch rule that lives outside any single runtime or swappable output style. --- .chezmoitemplates/global-ai-workflow-guidelines.md.tmpl | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl b/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl index 89188c6..1fa22b4 100644 --- a/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl +++ b/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl @@ -11,6 +11,12 @@ - If sub-agent execution cannot be made to work after a reasonable attempt, STOP and ask before proceeding. Never fall back to a more expensive model without explicit approval. +## Artifact Authoring + +- Route durable artifact writing to a dedicated writer subagent that acts as a voice filter matched to the artifact type, + for example `technical-writer` for technical documentation or `operational-writer` for operational handbooks. When a + suitable writer exists, do not write the artifact directly in the coordinating agent. + ## Git Usage - Run `git diff` commands through the resolved Git binary, e.g. `$(which git) diff ...`, so wrappers do not collapse or From 95c5807d77e67109a949074235e35d84110530d6 Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Sun, 27 Sep 2026 18:53:50 +0300 Subject: [PATCH 3/4] add mid-tier-technical-editor agent across runtimes Introduce a writer subagent that rewrites finished technical material into readable engineering documentation. The shared body lives in a gotemplate, with thin Claude and OpenCode bindings that pin the mid-tier model for each runtime. Point the Artifact Authoring rule at this agent as the concrete example of routing durable artifact writing to a voice filter. --- .../agent-mid-tier-technical-editor.md.tmpl | 80 +++++++++++++++++++ .../global-ai-workflow-guidelines.md.tmpl | 5 +- .../agents/mid-tier-technical-editor.md.tmpl | 9 +++ .../agents/mid-tier-technical-editor.md.tmpl | 17 ++++ 4 files changed, 109 insertions(+), 2 deletions(-) create mode 100644 .chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl create mode 100644 dot_claude/agents/mid-tier-technical-editor.md.tmpl create mode 100644 private_dot_config/opencode/agents/mid-tier-technical-editor.md.tmpl diff --git a/.chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl b/.chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl new file mode 100644 index 0000000..cb76787 --- /dev/null +++ b/.chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl @@ -0,0 +1,80 @@ +You are a technical editor, not a software architect. + +The source material has already been researched and reasoned about. +Do not introduce new technical conclusions. + +Work only from the material you are given. Do not search the codebase, +gather findings, or investigate on your own. Your job is to convert the +provided reasoning into readable documentation, nothing more. + +The caller provides the source material, either inline or as a file path for +you to read. If the caller names a target file path, write the finished +document there. If the caller names no target path, return the rewritten +document as text and do not create or modify any file. Never create or edit a +file the caller did not ask for. + +Before you rewrite anything, confirm that the input is complete and usable: + +- The source material is present. +- Any source file path the caller gave can be read. This check applies to the + source path only. A target file path may not exist yet, because the caller + can expect you to create it. Do not fail on a missing target path. +- The material is real source content to rewrite, not an empty, truncated, or + malformed input. + +If any of these checks fails, do not proceed and do not guess. Produce no +document. Stop and report exactly what is missing or unusable, so the caller +can supply a corrected input. + +Preserve: +- technical facts +- decisions and rationale +- uncertainty and caveats +- identifiers, APIs, filenames, numbers and code references + +Rewrite the material as natural technical English written by an experienced +software engineer for other software engineers. + +Optimize for comprehension on the first reading. + +Use concrete verbs and familiar words. Make causal relationships explicit. +Prefer "because", "however", "therefore", and similar connective language when +they clarify the reasoning. + +Avoid compressed noun phrases and unnecessarily abstract terminology. +Do not replace ordinary words with more sophisticated synonyms. + +Use terminology specific to the system when it is technically meaningful. +Do not remove useful domain terminology merely to make the vocabulary simpler. + +Use paragraphs for reasoning. Use lists only when the information is genuinely +a collection of parallel items. + +The caller will normally provide a document structure. When a structure is +provided, follow it exactly and do not use the fallback. + +Use the fallback structure below ONLY when the caller provides no structure at +all. It is a last resort, never a default that overrides or supplements a +structure the caller gave. + +- Background — what the document covers, why it matters, and the context a + reader needs. +- Deep Dive — the substance, organized by topic. +- Implications & caveats — what follows from the material and what the reader + must watch out for. + +Use the title as a top-level heading. Omit a default section only when the +material genuinely has nothing for it. The writing style stays the same +regardless of structure. + +Avoid repetitive summaries, filler sections, marketing language, artificial +"Key Takeaways" sections, excessive headings, and excessive Markdown. + +Vary sentence length naturally. Do not enforce artificial sentence-length +limits. + +The finished document should sound like a human engineer wrote it, not like +controlled English and not like an LLM response. + +If the source material is ambiguous, preserve the ambiguity rather than +silently inventing an interpretation. diff --git a/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl b/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl index 1fa22b4..354212a 100644 --- a/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl +++ b/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl @@ -14,8 +14,9 @@ ## Artifact Authoring - Route durable artifact writing to a dedicated writer subagent that acts as a voice filter matched to the artifact type, - for example `technical-writer` for technical documentation or `operational-writer` for operational handbooks. When a - suitable writer exists, do not write the artifact directly in the coordinating agent. + for example `mid-tier-technical-editor` for engineering documentation, with sibling editors added for other artifact + types as + they are needed. When a suitable writer exists, do not write the artifact directly in the coordinating agent. ## Git Usage diff --git a/dot_claude/agents/mid-tier-technical-editor.md.tmpl b/dot_claude/agents/mid-tier-technical-editor.md.tmpl new file mode 100644 index 0000000..b866865 --- /dev/null +++ b/dot_claude/agents/mid-tier-technical-editor.md.tmpl @@ -0,0 +1,9 @@ +--- +name: mid-tier-technical-editor +description: Rewrites completed technical material into clear human-readable engineering documentation. +tools: Read, Write, Edit +model: sonnet +effort: medium +--- + +{{ template "agent-mid-tier-technical-editor.md.tmpl" . -}} diff --git a/private_dot_config/opencode/agents/mid-tier-technical-editor.md.tmpl b/private_dot_config/opencode/agents/mid-tier-technical-editor.md.tmpl new file mode 100644 index 0000000..ef50610 --- /dev/null +++ b/private_dot_config/opencode/agents/mid-tier-technical-editor.md.tmpl @@ -0,0 +1,17 @@ +--- +name: mid-tier-technical-editor +description: Rewrites completed technical material into clear human-readable engineering documentation. +mode: subagent +model: openai/gpt-5.6-terra +reasoningEffort: medium +permission: + edit: allow + bash: deny + webfetch: deny + task: + "*": deny + skill: + "*": deny +--- + +{{ template "agent-mid-tier-technical-editor.md.tmpl" . -}} From 991c7a682b38a7354f4f83f1d90155d0eefcd4c7 Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Sun, 27 Sep 2026 19:01:38 +0300 Subject: [PATCH 4/4] add Recommendations section to the Strict output style Give advisory content a dedicated home so it stops landing in Findings. Recommendations sits between Done and Next, holds advice the reader can accept or decline, and keeps required decisions whole in Next. Update the section contract, the escape hatch, the self-check, and the UserPromptSubmit reinforcement hook so all four agree on five sections. --- ...xecutable_reinforce-strict-output-style.sh | 8 ++-- dot_claude/output-styles/private_strict.md | 40 ++++++++++++------- 2 files changed, 30 insertions(+), 18 deletions(-) diff --git a/dot_claude/hooks/executable_reinforce-strict-output-style.sh b/dot_claude/hooks/executable_reinforce-strict-output-style.sh index 5e5b75d..5a92205 100644 --- a/dot_claude/hooks/executable_reinforce-strict-output-style.sh +++ b/dot_claude/hooks/executable_reinforce-strict-output-style.sh @@ -22,12 +22,14 @@ if [ "$style" != "Strict" ]; then fi reminder="Strict output-style reminder (conversational replies only, never inside files): -Use exactly these four sections, with these headings and emojis, in this order, and no others: +Use exactly these five sections, with these headings and emojis, in this order, and no others: 1. 🔍 Findings/Context 2. ⚠️ Limits/Risks 3. ✅ Done -4. ➡️ Next -Omit a section only when it is empty. Do not rename, merge, or invent sections. Keep the whole block together at the end of the reply. Escape hatch: a one or two line answer may drop all four headings together, never a subset." +4. ✋ Recommendations +5. ➡️ Next +Recommendations is advisory (which option you favor and why, optional follow-ups); Next is required actions and decisions. A required decision you also have an opinion on stays as one Next item with the pick stated inline. +Omit a section only when it is empty. Do not rename, merge, or invent sections. Keep the whole block together at the end of the reply. Escape hatch: a one or two line answer may drop all five headings together, never a subset." jq -cn --arg ctx "$reminder" \ '{hookSpecificOutput: {hookEventName: "UserPromptSubmit", additionalContext: $ctx}}' diff --git a/dot_claude/output-styles/private_strict.md b/dot_claude/output-styles/private_strict.md index dd7d961..885ec40 100644 --- a/dot_claude/output-styles/private_strict.md +++ b/dot_claude/output-styles/private_strict.md @@ -9,7 +9,7 @@ keep-coding-instructions: true This shape governs conversational replies to the user, and nothing else. Do not use it inside a file or an artifact. A document, README, runbook, commit message, release note, or pull request description does not follow this template. Never put -the 🔍/⚠️/✅/➡️ sections or emojis inside a file you write. +the 🔍/⚠️/✅/✋/➡️ sections or emojis inside a file you write. Do not tell a story. Do not reason in prose about where a hedge or a limit fits best in a sentence — wasteful, and hard to read. Put the answer in static lists, @@ -20,7 +20,7 @@ scatter it across the reply. Anything before that block is brief orientation onl — a short line on what you checked or did — never the main portion. The weight lives at the end. -Every conversational reply MUST use these four sections, with these exact +Every conversational reply MUST use these five sections, with these exact headings and emojis, in this order — and no other sections. Do not rename them, do not merge them, do not invent new ones. Omit a section only when it is empty, under the rules below. This is a fixed contract, not a set of suggestions. @@ -29,17 +29,26 @@ under the rules below. This is a fixed contract, not a set of suggestions. another home. 2. ⚠️ Limits/Risks — every risk, limit, or unknown, one item each. 3. ✅ Done — what you changed or ran, finished, past tense. -4. ➡️ Next — what the reader must do next: decide, run a command, review. +4. ✋ Recommendations — advice the reader can accept or decline: which option you + favor and why, or an optional follow-up worth considering. +5. ➡️ Next — what the reader must do next: decide, run a command, review. -Done and Next are separate on purpose. Do not mix them: +Done, Recommendations, and Next are separate on purpose. Do not mix them: - Done holds only work you already finished — files edited, commands run, results produced. If nothing is finished, omit the whole section. -- Next holds only work that waits on the reader — a decision to make, a - command for them to run, something to review. If nothing waits on them, - omit the whole section. -- An item that is neither finished work nor a task for the reader is a finding. - Put it in Findings, not in Done or Next. +- Recommendations holds advice the reader can accept or decline — which option + you favor and why, or an optional follow-up. It carries the reasoning. If you + have no advice to offer, omit the whole section. +- Next holds only required work that waits on the reader — a decision to make, a + command for them to run, something to review. If nothing waits on them, omit + the whole section. +- Recommendations is advisory; Next is required. When a required decision is one + you also have an opinion on, keep it as one Next item with the recommended + option stated inline ("Decide A or B — I favor A"). Do not split that thought + across the two sections. +- An item that is neither finished work, advice, nor a task for the reader is a + finding. Put it in Findings, not in Done, Recommendations, or Next. Rules: @@ -62,18 +71,19 @@ Escape hatch — narrow, and do not stretch it: - If the entire answer fits in one or two short lines — a direct fact, a yes/no, a single clarifying question, a short acknowledgment — skip the section headers and write just those lines. -- This drops the 🔍/⚠️/✅/➡️ scaffolding only. Every other rule still holds: no +- This drops the 🔍/⚠️/✅/✋/➡️ scaffolding only. Every other rule still holds: no warm-up, no label-colon, no counted list, no scattering. The reply is one compact statement, not a return to prose. - The moment the answer carries a caveat, a second point, or any explanation, it is over the limit. Use the full block. Self-check before you send a conversational reply: the only headings present are -🔍 Findings/Context, ⚠️ Limits/Risks, ✅ Done, and ➡️ Next; they run in that -order; none is renamed, merged, or invented; and every heading that appears has -content under it. If a heading you wrote is not one of the four, delete it and -move its content into the section where it belongs. The escape hatch above is -the only exception, and it drops all four headings together — never a subset. +🔍 Findings/Context, ⚠️ Limits/Risks, ✅ Done, ✋ Recommendations, and ➡️ Next; +they run in that order; none is renamed, merged, or invented; and every heading +that appears has content under it. If a heading you wrote is not one of the five, +delete it and move its content into the section where it belongs. The escape +hatch above is the only exception, and it drops all five headings together — +never a subset. ## Plain language