Files
archie/.github/skills/technical-prose-cleanup/SKILL.md
T
samandCopilot 64dfad6d53 feat(runs): add typed results and model aliases (#2043)
Also fix repository-free message.send validation (#2046) and add a single-binary development smoke path (#1977).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-18 23:47:35 +11:00

4.2 KiB

name, description
name description
technical-prose-cleanup Use when asked to clean up awkward or machine-generated technical writing in Archie's modules without changing behaviour. Reviews one module at a time.

Technical prose cleanup

Follow AGENTS.md. Improve wording without changing behaviour, contracts or technical meaning. Use Australian English.

Set the scope

  1. Check the working tree for existing changes. Inspect modules/ without editing and choose the smallest module with enough clear problems to justify a pass, unless the maintainer has specified one.
  2. Set the complete file scope before editing: exactly one module, at most 15 files. Do not expand into other modules or start another batch.
  3. Use subagents only when independent work warrants it. Assign at most three in parallel, each with a disjoint list of owned files, this writing standard and relevant examples. Instruct them to inspect the implementation, leave clear prose alone, report ambiguities and make no commits or pushes. The coordinator owns integration and validation. In a shared worktree, avoid broad staging, resets, checkouts and formatters that rewrite other work.

Edit in context

Check comments, errors, logs, test names, schema descriptions, CLI help, prompts, user-facing strings and module documentation. Look for unnatural word order, awkward possessives, unusual verbs, needless synonyms and wording that obscures the operation. Read the surrounding implementation and tests before rewriting. Do not mechanically replace words or edit text that already reads well.

Use conventional terms, even when they repeat. Keep established idioms such as “pin a dependency”, “drain a stream” and “acquire a lock”. Prefer precision over brevity when conditions, timing, ownership or guarantees matter.

Instead of Write
“PrepareRequest names the release to stage and who hears the outcome.” “PrepareRequest specifies the release to stage and notification recipients.”
“ReadOnly leaves the agent only the tools that change nothing.” “ReadOnly restricts the agent to read-only tools.”
“a release another key signed” “a release signed by a different key”
“it recalls earlier incidents and files what it found” “it retrieves previous incidents and stores new findings”

Comments explain why. Remove narration that adds nothing, but keep non-obvious constraints, invariants and decisions. Retain required Go documentation. Don't shorten a comment about replay into a generic retry description: say what is recorded and what is rebuilt or resolved at runtime. Likewise, distinguish a per-action reapproval limit from a run-wide limit, and escalation within one request from a new request.

Do not refactor or rename identifiers, configuration keys or API fields. Do not edit generated files by hand, add tooling or dependencies, or reformat unrelated code. Check consumers and tests before changing errors, logs or other output. Keep machine-readable values and exact text used as a contract. If a safe edit needs changes outside the scope or the meaning is unclear, leave the text alone and report why.

For prompts, preserve instructions, conditions, tool semantics and output requirements. Check what the agent actually sees. For example, judgement runs inside an action tool call; it is not a separate tool the agent calls directly. The investigation prompt says: “If a tool call returns a judgement decision, report the decision and any reasons it gives.” Keep matching fixtures in sync when editing prompt text.

Review and stop

Review the combined diff against both the implementation and the starting working tree. Verify the module and file limits, check that unrelated edits are intact, and confirm that no logic or contract changed. If implementation work already shares a file, keep it out of the prose diff; separate by hunk if asked to commit both.

Run the relevant checks on the final tree and follow AGENTS.md for the commit gate. Report failed or unavailable checks; do not fix unrelated failures in this batch. Summarise the module, file count, main edits, deliberately unchanged ambiguities and validation. Stop after this batch.