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>
77 lines
4.2 KiB
Markdown
77 lines
4.2 KiB
Markdown
---
|
|
name: technical-prose-cleanup
|
|
description: 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.
|