From 635debc07e262d31126ae57f5799167f21108ae0 Mon Sep 17 00:00:00 2001 From: Hampton Lintorn-Catlin Date: Wed, 19 Aug 2026 12:27:26 -0500 Subject: [PATCH 1/2] Add writing-style ground rules to agent instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two rule sets observed missing from live agent output: agents write document metadata into plan bodies (date lines, invented status fields, author lines — all things the platform records), and they pad working documents with promotional prose. New "Writing Style" section bans body metadata (with a facts-anchor exception), sets Simplified- Technical-English-style plain-language rules with named banned words, and lets a plan type's description or template override the defaults so persuasive types (e.g. a pitch) stay possible. Co-Authored-By: Claude Fable 5 --- .../coplan/agent_instructions/show.text.erb | 22 +++++++++++++++++++ spec/requests/agent_instructions_spec.rb | 12 ++++++++++ 2 files changed, 34 insertions(+) diff --git a/engine/app/views/coplan/agent_instructions/show.text.erb b/engine/app/views/coplan/agent_instructions/show.text.erb index b7fa8ce..eb2ba89 100644 --- a/engine/app/views/coplan/agent_instructions/show.text.erb +++ b/engine/app/views/coplan/agent_instructions/show.text.erb @@ -37,6 +37,28 @@ The server diffs your content against the current revision, records granular ope See [Editing Plans](#editing-plans-recommended-full-content-replacement) for the full request/response reference, and the lease + operations path only when you need a surgical single-operation edit. +## Writing Style + +These rules apply to every plan you write or edit. One exception mechanism: **a plan type's description or template may override any of them — the type wins.** (A persuasive pitch type can welcome persuasive language; these defaults assume a working document.) + +**The platform already records it.** Never write document metadata into the body: + +- No date or "last updated" lines — every version is timestamped in the plan history. +- No author, attribution, or "prepared by" lines — every version and comment is attributed, including your agent name. +- No status lines, status fields, or status tables — visibility, archival, and tags carry state (see [Visibility & Archiving](#visibility--archiving)). There is no document status; do not invent one. +- No version numbers or changelogs — the plan history is the changelog. + +The exception is dates that anchor **facts**, which belong in content: "confirmed against production 2026-08-19", "verified at commit abc123". + +**Write plainly.** Follow Simplified-Technical-English-style rules: + +- Short sentences. One idea per sentence. Active voice, present tense. +- Plain verbs: "use", not "leverage"; "check", not "perform validation of". +- No metaphors, no marketing adjectives, no drama. Words that signal padding — "robust", "seamless", "comprehensive", "cutting-edge", "elegant", "crucially", "delve" — are banned unless you are quoting someone. +- State facts without selling them. The reader is a colleague deciding what to do, not an audience to impress. Write like a runbook, not a keynote. +- Prefer a table or list over a paragraph when the content is enumerable. +- Length is a cost. Write the shortest document that serves its reader, then stop. + ## API Reference ### List Plans diff --git a/spec/requests/agent_instructions_spec.rb b/spec/requests/agent_instructions_spec.rb index 87cc6fe..8998bf5 100644 --- a/spec/requests/agent_instructions_spec.rb +++ b/spec/requests/agent_instructions_spec.rb @@ -42,6 +42,18 @@ expect(response.body).to include('"plan_type"') end + it "sets writing-style ground rules with a type-level override" do + get agent_instructions_path + + expect(response.body).to include("## Writing Style") + # Anti-metadata rules: the platform records dates/authors/status/versions. + expect(response.body).to include("The platform already records it.") + expect(response.body).to include("do not invent one") + # Plain-language rules with the override escape hatch. + expect(response.body).to include("the type wins") + expect(response.body).to include("Write like a runbook, not a keynote.") + end + it "walks agents through folder, type, and template before creating" do get agent_instructions_path From b0547c2546c029c0f233968c92748ec3ac684f4c Mon Sep 17 00:00:00 2001 From: Hampton Lintorn-Catlin Date: Wed, 19 Aug 2026 16:33:39 -0500 Subject: [PATCH 2/2] Ban "honest" and "actually" too Review feedback from Hampton on the padding-words list. Co-Authored-By: Claude Fable 5 --- engine/app/views/coplan/agent_instructions/show.text.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engine/app/views/coplan/agent_instructions/show.text.erb b/engine/app/views/coplan/agent_instructions/show.text.erb index eb2ba89..9ffb9e6 100644 --- a/engine/app/views/coplan/agent_instructions/show.text.erb +++ b/engine/app/views/coplan/agent_instructions/show.text.erb @@ -54,7 +54,7 @@ The exception is dates that anchor **facts**, which belong in content: "confirme - Short sentences. One idea per sentence. Active voice, present tense. - Plain verbs: "use", not "leverage"; "check", not "perform validation of". -- No metaphors, no marketing adjectives, no drama. Words that signal padding — "robust", "seamless", "comprehensive", "cutting-edge", "elegant", "crucially", "delve" — are banned unless you are quoting someone. +- No metaphors, no marketing adjectives, no drama. Words that signal padding — "robust", "seamless", "comprehensive", "cutting-edge", "elegant", "crucially", "delve", "honest", "actually" — are banned unless you are quoting someone. - State facts without selling them. The reader is a colleague deciding what to do, not an audience to impress. Write like a runbook, not a keynote. - Prefer a table or list over a paragraph when the content is enumerable. - Length is a cost. Write the shortest document that serves its reader, then stop.