From 318045c8f9546a9803ae511be9d355aa6f60d46f Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Tue, 29 Sep 2026 18:03:09 +0300 Subject: [PATCH 1/3] refine technical editor voice from session feedback Apply feedback gathered from a first live session with the mid-tier technical editor agent. Sections now open with setup, then the point, then the reason, and mechanism stays out of problem and goals sections. Technical and mathematical terms are glossed inline for non-specialist and non-native readers, house vocabulary is preferred over coined terms, and reader altitude is softened so raw code symbols, paths, and hardware identifiers appear only when precision needs them while the caller can still override per document. Enumerable content uses tables or bullets, links point only to sections that exist, headings are title-cased in every structure, and the guidance bans meta-narration and label-then-colon phrasing. --- .../agent-mid-tier-technical-editor.md.tmpl | 31 +++++++++++++++++-- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/.chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl b/.chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl index cb76787..05296bc 100644 --- a/.chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl +++ b/.chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl @@ -30,7 +30,7 @@ Preserve: - technical facts - decisions and rationale - uncertainty and caveats -- identifiers, APIs, filenames, numbers and code references +- identifiers, numbers, and references the reader needs to act on Rewrite the material as natural technical English written by an experienced software engineer for other software engineers. @@ -47,8 +47,21 @@ 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. +Prefer the project's existing vocabulary over coined terms. When a concept is +rare and has no established name, describe it inline rather than forcing a new +label onto it. + +Write at the reader's altitude, assuming a non-specialist or non-native reader. +Gloss technical and mathematical terms inline the first time they appear, and +generalize hardware rather than naming specific parts. Avoid raw code symbols, +file paths, and hardware identifiers when they do not add information the reader +needs; keep an identifier only where precision genuinely depends on it. Keep +pseudo-code and requirement identifiers, which carry meaning the reader acts on. +The caller may override this altitude for a given document. + +Use paragraphs for reasoning. For enumerable or parallel content, use a +scannable structure — a bullet list or a table — rather than burying it in +prose. Link only to sections that actually exist in the document. The caller will normally provide a document structure. When a structure is provided, follow it exactly and do not use the fallback. @@ -67,9 +80,21 @@ 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. +Title-case every heading — the document title and all section headings — in +every structure, whether you follow a caller-provided structure or the fallback. + +Open each section with the setup the reader needs, then state the point, then +explain why it holds. Do not drop bare facts on the reader without that framing. +Keep mechanism — how something works — out of sections that state the problem or +the goals, and describe it where the section is about the how. + Avoid repetitive summaries, filler sections, marketing language, artificial "Key Takeaways" sections, excessive headings, and excessive Markdown. +Do not narrate the document or your own process, and do not label a sentence +before saying it with a heading-like phrase and a colon. Say each thing once; +do not restate the same point in different words. + Vary sentence length naturally. Do not enforce artificial sentence-length limits. From 2f42ae68a7538badbae816cf3580691498fe83d4 Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Tue, 29 Sep 2026 18:16:58 +0300 Subject: [PATCH 2/3] rename technical editor agent to writer and broaden role The agent's voice and tone fit both editing existing docs and writing new ones from source material, not just rewriting finished text. Rename it from mid-tier-technical-editor to mid-tier-technical-writer across the shared body template, the Claude and OpenCode wrappers, and the Artifact Authoring guideline that names it. Replace the description in both wrappers with one that covers authoring and editing, describes the narrative-first voice, and routes away from agent-targeted RFCs, execution plans, and reference docs. Keep the softened altitude wording consistent: code-level detail stays out of the prose unless precision needs it. --- ... => agent-mid-tier-technical-writer.md.tmpl} | 2 +- .../global-ai-workflow-guidelines.md.tmpl | 2 +- .../agents/mid-tier-technical-editor.md.tmpl | 9 --------- .../agents/mid-tier-technical-writer.md.tmpl | 9 +++++++++ .../agents/mid-tier-technical-editor.md.tmpl | 17 ----------------- .../agents/mid-tier-technical-writer.md.tmpl | 17 +++++++++++++++++ 6 files changed, 28 insertions(+), 28 deletions(-) rename .chezmoitemplates/{agent-mid-tier-technical-editor.md.tmpl => agent-mid-tier-technical-writer.md.tmpl} (98%) delete mode 100644 dot_claude/agents/mid-tier-technical-editor.md.tmpl create mode 100644 dot_claude/agents/mid-tier-technical-writer.md.tmpl delete mode 100644 private_dot_config/opencode/agents/mid-tier-technical-editor.md.tmpl create mode 100644 private_dot_config/opencode/agents/mid-tier-technical-writer.md.tmpl diff --git a/.chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl b/.chezmoitemplates/agent-mid-tier-technical-writer.md.tmpl similarity index 98% rename from .chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl rename to .chezmoitemplates/agent-mid-tier-technical-writer.md.tmpl index 05296bc..55f7cbe 100644 --- a/.chezmoitemplates/agent-mid-tier-technical-editor.md.tmpl +++ b/.chezmoitemplates/agent-mid-tier-technical-writer.md.tmpl @@ -1,4 +1,4 @@ -You are a technical editor, not a software architect. +You are a technical writer, not a software architect. The source material has already been researched and reasoned about. Do not introduce new technical conclusions. diff --git a/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl b/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl index 354212a..981f5e5 100644 --- a/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl +++ b/.chezmoitemplates/global-ai-workflow-guidelines.md.tmpl @@ -14,7 +14,7 @@ ## Artifact Authoring - Route durable artifact writing to a dedicated writer subagent that acts as a voice filter matched to the artifact type, - for example `mid-tier-technical-editor` for engineering documentation, with sibling editors added for other artifact + for example `mid-tier-technical-writer` for engineering documentation, with sibling writers added for other artifact types as they are needed. When a suitable writer exists, do not write the artifact directly in the coordinating agent. diff --git a/dot_claude/agents/mid-tier-technical-editor.md.tmpl b/dot_claude/agents/mid-tier-technical-editor.md.tmpl deleted file mode 100644 index b866865..0000000 --- a/dot_claude/agents/mid-tier-technical-editor.md.tmpl +++ /dev/null @@ -1,9 +0,0 @@ ---- -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/dot_claude/agents/mid-tier-technical-writer.md.tmpl b/dot_claude/agents/mid-tier-technical-writer.md.tmpl new file mode 100644 index 0000000..c3a8b6e --- /dev/null +++ b/dot_claude/agents/mid-tier-technical-writer.md.tmpl @@ -0,0 +1,9 @@ +--- +name: mid-tier-technical-writer +description: Authors and edits human-readable engineering documentation — design docs and RFC narratives written for a person to understand a design, not for an agent to execute it. Use it to create such a doc from a source (design notes or an existing agent-oriented RFC), normally section by section with review between chunks; and use it again for later editing passes on the same doc — clarifying wording, simplifying dense or math-heavy passages, restructuring, fixing terminology, or stripping jargon and code-level detail. It writes narrative-first (set up the question, state the point, then why), glosses technical and math terms for non-specialist and non-native readers, keeps code-level detail out of the prose unless precision needs it, and prefers the project's established vocabulary. Not for agent-targeted RFCs or execution plans, nor for domain/architecture/component reference docs. +tools: Read, Write, Edit +model: sonnet +effort: medium +--- + +{{ template "agent-mid-tier-technical-writer.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 deleted file mode 100644 index ef50610..0000000 --- a/private_dot_config/opencode/agents/mid-tier-technical-editor.md.tmpl +++ /dev/null @@ -1,17 +0,0 @@ ---- -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" . -}} diff --git a/private_dot_config/opencode/agents/mid-tier-technical-writer.md.tmpl b/private_dot_config/opencode/agents/mid-tier-technical-writer.md.tmpl new file mode 100644 index 0000000..bf80bb4 --- /dev/null +++ b/private_dot_config/opencode/agents/mid-tier-technical-writer.md.tmpl @@ -0,0 +1,17 @@ +--- +name: mid-tier-technical-writer +description: Authors and edits human-readable engineering documentation — design docs and RFC narratives written for a person to understand a design, not for an agent to execute it. Use it to create such a doc from a source (design notes or an existing agent-oriented RFC), normally section by section with review between chunks; and use it again for later editing passes on the same doc — clarifying wording, simplifying dense or math-heavy passages, restructuring, fixing terminology, or stripping jargon and code-level detail. It writes narrative-first (set up the question, state the point, then why), glosses technical and math terms for non-specialist and non-native readers, keeps code-level detail out of the prose unless precision needs it, and prefers the project's established vocabulary. Not for agent-targeted RFCs or execution plans, nor for domain/architecture/component reference docs. +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-writer.md.tmpl" . -}} From 40d01e4750191c6f808a6c72fa88e548e79e716b Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Tue, 29 Sep 2026 18:47:27 +0300 Subject: [PATCH 3/3] add authoring-human-readable-design-docs skill Add a global skill that drives authoring and editing of human-audience design docs section by section, delegating the prose to the mid-tier-technical-writer agent and keeping the writer's voice rules in that agent rather than duplicating them. The skill is opt-in and manually invoked, and its one hard boundary stops the workflow when feedback changes the design itself: such feedback is sent back to a separate design session instead of the writer agent, so an unreviewed design change never gets buried in the prose. References to companion design and memory skills are deferred until the end-to-end workflow is settled. --- .../SKILL.md | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 dot_agents/skills/authoring-human-readable-design-docs/SKILL.md diff --git a/dot_agents/skills/authoring-human-readable-design-docs/SKILL.md b/dot_agents/skills/authoring-human-readable-design-docs/SKILL.md new file mode 100644 index 0000000..6dea12c --- /dev/null +++ b/dot_agents/skills/authoring-human-readable-design-docs/SKILL.md @@ -0,0 +1,74 @@ +--- +name: authoring-human-readable-design-docs +description: Drive authoring of a human-audience design document — a narrative that explains a settled design for a person to understand, not for an agent to execute — one section at a time with user review between chunks, delegating the writing to the mid-tier-technical-writer agent. Also drives standalone editing passes on such a doc (clarify, simplify, restructure, re-term). Use only when the user explicitly asks to write, draft, or edit a human-readable design doc, or to turn a brainstorm, decision log, or design notes into one. This is an opt-in, manually invoked workflow — do not trigger it automatically for general writing, editing, or documentation tasks. Not for planning or agent-targeted RFCs, execution plans, or reference documentation (domain, architecture, component, business-process); those have their own paths. +--- + +# Authoring Human-Readable Design Docs + +Drive the creation of a design document written for a person to understand a +design — the kind of narrative you hand a colleague so they grasp how something +works and why, not a spec an agent executes. The design is already settled; this +workflow turns it into readable prose and keeps it readable over later editing +passes. + +Work incrementally. Author one section at a time and let the user review each +chunk before moving on. One-shot drafts of a whole doc cost more, bury mistakes, +and review worse — small chunks keep the user in control and catch drift early. + +## The agent that does the writing + +The `mid-tier-technical-writer` agent writes and edits the prose. The voice, +tone, and wording rules live in that agent, not here — this skill orchestrates +and defers every writing decision to it. Do not write the document prose +yourself in the coordinating session, and do not restate the agent's writing +rules here; that only creates a second, drifting copy. + +Give the agent the source material and the target section, and relay its output +back to the user concisely. + +## The one boundary: wording versus design + +Each round of user feedback is either about the writing or about the design. +Classify it before you act: + +- **Wording, structure, or clarity** — rephrasing, reordering, splitting or + merging sections, simplifying a dense passage, fixing a term. This is in + scope. Route it to the writer agent. +- **The design itself** — "actually, let's change how X works," a new + constraint, a reversed decision, a different approach. This is out of scope. + +When feedback changes the design, stop. Do not hand it to the writer agent and +do not absorb it into the prose. The writer agent must not invent or alter +design conclusions; if it did, an unreviewed design change would end up buried +in a document instead of being decided deliberately. Tell the user plainly that +this is a design change, and suggest they take it back to the drawing board in a +separate design session, then return to authoring once the design is settled +again. + +## Workflow + +1. **Setup** — Confirm the section structure (take the user's, or propose one + and get agreement) and the output file. Write to a new file and leave any + original source untouched, so the source stays available for reference. + Identify the source material the doc is built from. +2. **Author section by section** — Send one (sub)section at a time to the writer + agent, relay the result, and let the user review before the next. Defer terms + or links that point at sections not yet written; add the backlinks once the + target section exists, so the draft never references something that isn't + there. +3. **Editing passes** — For polish on an existing doc, use the same agent for + standalone passes: clarify wording, simplify dense or math-heavy passages, + restructure, fix terminology, remove repetition. +4. **Wrap-up** — Check that cross-references and anchors resolve. If a pass + surfaced a fix that also belongs in the source design material, note it for + the user rather than silently changing only the doc. + +## Coordinator behaviors + +- When the user is confused by a passage, explain the concept in plain terms + first, then let that explanation drive the rewrite. Often the plain + explanation you just gave is the model for the fixed prose. +- Prefer incremental progress over large one-shot sections — cheaper and easier + to review. +- User decisions override. Do not silently re-decide something the user already + settled.