Repository navigation
feat: broaden technical-writer agent and add design-doc authoring skill - #33
Merged
Merged
Conversation
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.
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.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📝 Summary
The
mid-tier-technical-editoragent only rewrote finished text, but its voiceand tone fit both writing new docs and editing existing ones. This broadens it
into a technical writer, applies voice feedback from its first live session, and
adds an opt-in skill that drives authoring a human-audience design doc section
by section.
Key Decisions
✍️ Broadened Agent Role
Renamed
mid-tier-technical-editortomid-tier-technical-writeracross theshared body template, the Claude and OpenCode wrappers, and the Artifact
Authoring guideline. The new description covers authoring and editing, states
the narrative-first voice, and routes away from planning RFCs, execution plans,
and reference docs.
🗣️ Voice Refinements
Applied session feedback to the agent body: sections open setup → point → why,
technical and math terms are glossed inline, house vocabulary is preferred over
coined terms, headings are title-cased, and meta-narration and label-then-colon
phrasing are banned. Reader altitude is softened — code-level detail stays out
of the prose unless precision needs it, and the caller can override per document.
📄 Design-Doc Authoring Skill
Added the global, manually-invoked
authoring-human-readable-design-docsskill.It orchestrates section-by-section authoring through the writer agent with user
review between chunks, and keeps the writer's voice rules in the agent rather
than duplicating them. Its one hard boundary stops the workflow when feedback
changes the design itself and sends that back to a separate design session, 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.
🔄 Before & After
mid-tier-technical-editormid-tier-technical-writer