From 9c6a45713d058285874bcb2e728ca424bd03fe8d Mon Sep 17 00:00:00 2001 From: Colton Padden Date: Tue, 4 Aug 2026 18:05:13 -0400 Subject: [PATCH] chore: add technical docs guidance to human-writing Signed-off-by: Colton Padden --- .agents/skills/human-writing/SKILL.md | 16 ++++++++++++++++ .agents/skills/human-writing/eval.md | 8 ++++++++ 2 files changed, 24 insertions(+) diff --git a/.agents/skills/human-writing/SKILL.md b/.agents/skills/human-writing/SKILL.md index 466bd0289..d5b37cc94 100644 --- a/.agents/skills/human-writing/SKILL.md +++ b/.agents/skills/human-writing/SKILL.md @@ -23,6 +23,22 @@ Use when the user asks to audit, scan, flag, or judge whether a draft reads like Use when the user asks for new prose. Follow the supplied brief, audience, format, tone, and writing samples. Do not manufacture personal opinions, feelings, stories, humor, or first-person experience merely to make the prose sound human. +### Technical documentation + +Apply these rules when writing, editing, or reviewing eve's documentation: + +- Identify the audience, goal, and content type before writing. Keep each page focused on one job and read nearby docs for established terminology and structure. +- Verify behavior against the code or an authoritative source. Never invent examples, measurements, implementation details, or citations to make prose more specific. +- Use a neutral, instructional voice. Address the reader as `you`, use imperative verbs for steps, and do not add personal reactions, humor, tangents, or first-person experience. +- Prefer active voice, present tense, concrete verbs, and consistent terms. Do not describe a reader's task as `easy`, `simple`, or `quick`. +- Open with a short summary of what the page helps the reader do. Use sentence case and descriptive headings, focused paragraphs, and lists when they improve scanning. +- Define unfamiliar terms and spell out acronyms on first use. Use inline code for paths and identifiers, and reserve bold for user interface elements or critical facts. +- Prefer TypeScript examples unless the subject is language-agnostic. Add a language tag, explain each example, and keep it minimal, runnable, and consistent with the current API. +- Use descriptive link text and placeholders such as `your_access_token_here`. Avoid bare URLs, `here`, ``, and unexplained values. +- For review-only requests, group concise findings by file and include a clickable `file:line` location. If a file passes, report `✓ pass`. + +Follow repository conventions when they conflict with these rules. + ## Protect the writer - Preserve the meaning, facts, nuance, uncertainty, and intent. diff --git a/.agents/skills/human-writing/eval.md b/.agents/skills/human-writing/eval.md index 9b451ceca..81e4c2a21 100644 --- a/.agents/skills/human-writing/eval.md +++ b/.agents/skills/human-writing/eval.md @@ -26,6 +26,14 @@ Run this checklist internally after editing, detecting, or drafting. Treat every 4. Are robotic rhythm, fake-profound endings, redundant conclusions, decorative formatting, and punctuation crutches corrected where appropriate? 5. Were intentional constructions and required house-style choices preserved? +## Technical documentation + +1. Does the page have a clear audience and goal, use established terminology, and stay focused on one job? +2. Are technical claims and code examples accurate, current, and supported by the code or an authoritative source? +3. Does the page use a neutral instructional voice, descriptive sentence-case headings, and formatting that supports scanning? +4. Are code examples minimal, explained, language-tagged, and consistent with repository conventions? +5. For a review, does each finding include a concise, clickable `file:line` location? + ## Response contract 1. For an edit, is the full edited draft present, followed by a short **What changed** section unless the user requested clean copy only?