feat(skills): make every agent-written artifact read as plain technical English

[sourcehawk]

Description

Investigation summaries, wiki entries, issues, PR bodies, playbook prose, and the prompts themselves came out with 40-word sentences, should and passive voice, present perfect, contractions, and padding that reviewers had to read past. This PR copies the simple-english (ASD-STE100) skill into the repo as skills/writing-simply, loads it on every surface where a session or sub-agent writes a durable artifact, and rewrites the nine operator skills and the default profile prompts to the same rules. The rules add roughly 800 words to each investigation and editor system prompt. One behavior change outside prose: EnableAuto now prepares the operator's cwd before it publishes the started state, so a failed skill extraction no longer leaves the UI in active auto mode with no operator behind it.

Changes

• New skills/writing-simply (SKILL.md plus the plugin's full rule catalog, checklist, and use-cases under references/) and a skills package with WritingSimply() for prompt embedding (frontmatter and H1 stripped, headings nested under the caller's) and Extract() for CLI discovery.
• The investigation and both editor system prompts gain a ## Writing style section. The same body rides in every fresh sub-agent prompt that writes a durable artifact: dispatched proposal playbooks (BuildDispatchPrompt), draft_pr, propose_wiki_draft, the session post-mortem drafter, and the repo architecture summary generator. The operator agent gets it extracted next to its own skills. Transient sub-agents (Slack analysis, change analysis, codebase research) do not carry it.
• Issue and PR body shapes, wiki_schema, playbook_schema, the summarize input schema, and the capture, wiki, PR, bug-report, and playbook proposal playbooks point at the rules, with per-field voice (imperative operator takeaways, simple-past retrospectives, present tense for open state).
• Operator skills rewritten (6205 to about 4100 words): trigger-only descriptions, imperative procedures, no should, the bug capture route added (it was missing from every skill), walker vocabulary instead of "state machine", and the playbook-versus-codefix rule stated once. Review also removed two impossible "wait" actions and an auto-trigger check that looked for the signal-watch marker in the wrong place.
• Default profile prompts (system, architecture, strategies, editor, wiki_editor) and the prose prompts.Build / BuildEditor emit follow the same rules; Build shares writeLinkedReposSection with the editor instead of carrying its own copy.
• pr_proposal and bug_report_proposal map their issue material onto the create_github_issue body shape (Description / Acceptance Criteria / Evidence / Out of scope) instead of prescribing a conflicting section list.
• EnableAuto extracts operator and shared skills before it sets PhaseStarted and publishes the started envelope.

Related

• Merges main at fix(subagent): return only the final answer in sub-agent tool results #81 (research_codebase), folded into the rewritten repo and editor prompts.

Testing

make test-go and make lint pass; no frontend changes. Unit tests pin the writing-style section into Build, both BuildEditor paths, the dispatch, draft-PR, wiki, post-mortem, and architecture-summary prompts, both body shapes, and both schema READMEs; the skills package tests cover frontmatter stripping, heading nesting, and extraction. TestManager_EnableAuto_ExtractFailureDoesNotPublishStarted blocks the shared-skill slug and checks that no started state or envelope is published and the in-flight sentinel clears.

The skill was developed TDD-style with subagents: baseline wiki-entry and issue-body runs without the skill showed the failures above; the same runs with the skill came back clean, and two loopholes those runs exposed (one-sentence-paragraph fragmentation, self-check narration leaking into the deliverable) were closed. The operator rewrite was checked against the old skills on a capture scenario with three traps (a merged wiki shape, a playbook YAML edit labelled as codefix, an oversized change that belongs in bug) and on an approve-then-close turn. The PR then went through 18 rounds of balanced Copilot review until a round returned nothing; every thread has a reply and each round's suppressed findings have a disposition comment.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Several writing-rule references are incorrect, and a rewritten default prompt still violates the declared sentence limit.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Embeds shared plain-English guidance across investigation, editor, operator, wiki, issue, and PR-writing workflows.

Changes:

• Adds and embeds the writing-simply skill.
• Applies writing guidance to prompts, schemas, and playbooks.
• Rewrites operator skills and default profile prompts.

File summaries

File	Description
system/wiki_proposal.yaml	Adds wiki prose guidance.
system/wiki_backfill_ingestion.yaml	Adds backfill writing rules.
system/pr_proposal.yaml	Aligns issues with the standard body shape.
system/playbook_proposal.yaml	Defines playbook prose style.
system/capture_offer.yaml	Adds capture-proposal writing rules.
system/bug_report_proposal.yaml	Aligns bug reports with issue structure.
skills/writing-simply/SKILL.md	Adds the shared working rules.
skills/writing-simply/references/use-cases.md	Documents writing use cases.
skills/writing-simply/references/simple-english.md	Adds the complete rule catalog.
skills/writing-simply/references/checklist.md	Adds a verification checklist.
skills/embed.go	Embeds and extracts shared skills.
skills/embed_test.go	Tests embedding and extraction.
prompts/prompts.go	Injects writing rules into session prompts.
prompts/prompts_test.go	Tests prompt injection.
pkg/mcp/wiki/tools_schema.go	Documents wiki prose requirements.
pkg/mcp/wiki/tools_schema_test.go	Tests wiki schema guidance.
pkg/mcp/wiki/prompts.go	Adds rules to wiki sub-agent prompts.
pkg/mcp/wiki/prompts_test.go	Tests wiki prompt guidance.
pkg/mcp/strategies/tools_proposal.go	Documents playbook prose rules.
pkg/mcp/strategies/server.go	Tightens summary field guidance.
pkg/mcp/strategies/schema_prose_test.go	Tests playbook prose documentation.
pkg/mcp/git/draft_pr_prompt.go	Adds rules to PR-drafting prompts.
pkg/mcp/git/draft_pr_prompt_test.go	Tests PR prompt guidance.
pkg/mcp/git/body_shapes.go	Adds body-shape writing requirements.
pkg/mcp/git/body_shapes_test.go	Tests body-shape references.
operator-skills/steering-investigations/SKILL.md	Simplifies steering guidance.
operator-skills/resuming-after-takeover/SKILL.md	Simplifies takeover recovery.
operator-skills/operator-role/SKILL.md	Condenses core operator instructions.
operator-skills/knowing-when-to-yield/SKILL.md	Simplifies takeover criteria.
operator-skills/finishing-a-session/SKILL.md	Simplifies completion guidance.
operator-skills/evaluating-codefixes/SKILL.md	Adds bug routing and concise criteria.
operator-skills/capture-decisions/SKILL.md	Adds bug capture and revised routing.
operator-skills/approving-drafts/SKILL.md	Simplifies proposal approval guidance.
operator-skills/answering-the-agent/SKILL.md	Simplifies response classification.
internal/server/manager.go	Extracts shared operator skills.
internal/profile/profiles/default/prompts/wiki_editor.md	Rewrites wiki editor instructions.
internal/profile/profiles/default/prompts/system.md	Rewrites investigation instructions.
internal/profile/profiles/default/prompts/strategies.md	Rewrites walker guidance.
internal/profile/profiles/default/prompts/editor.md	Rewrites playbook editor instructions.
internal/profile/profiles/default/prompts/architecture.md	Rewrites architecture guidance.
AGENTS.md	Documents the shared skills directory.

Review details

• Files reviewed: 41/41 changed files
• Comments generated: 4
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Auto-trigger detection is broken, and several new examples and prompts contradict the writing constraints they introduce.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

operator-skills/capture-decisions/SKILL.md:75

• This condition never matches the operator briefing. autoBriefing always starts with “You are the operator agent…” and places the watch-generated marker inside its Notes: section (internal/server/handlers_auto.go:73,93-95). Auto-triggered noops can therefore take the normal no route instead of producing the wontfix wiki entry needed for signal dismissal. Detect the marker in the notes section rather than requiring it at the start.

If the briefing starts with "Auto-triggered by signal-watch ingestion", a noop or false-positive outcome must become a wiki entry, not `no`. Reply `wiki` and ask for `status: wontfix` plus enough symptom keywords (services, error strings, timing) for `wiki_correlate` to find it. That entry is what lets the ingestion agent dismiss the same signal next time.

• Files reviewed: 41/41 changed files
• Comments generated: 2
• Review effort level: Balanced

[sourcehawk]

Round 2 suppressed finding, operator-skills/capture-decisions/SKILL.md:75 (auto-trigger marker never at the start of the briefing): confirmed against autoBriefing in internal/server/handlers_auto.go, which puts the watch marker inside the Notes: line. Applied in 4d65076: the check now reads "If the Notes: line of your briefing contains ...".

[Copilot]

🟡 Changes recommended

Several prompt examples and shared rules contradict the new writing contract and existing walker or summary-field behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

operator-skills/capture-decisions/SKILL.md:16

• There is no substring matcher in the walker. The agent reads each branch condition and explicitly passes a goto; the walker does not evaluate the reply (pkg/mcp/strategies/playbook.go:193-195). This claim is especially misleading because the required category labels put several route keywords into every reply. Describe the semantic branch selection instead.

The matcher scans for the keyword as a substring. The keyword on its own line keeps the matcher reliable and the prose readable.

internal/profile/profiles/default/prompts/architecture.md:9

• The second rewritten sentence is well over the skill's 25-word descriptive limit, so this default profile still does not follow the writing rules that the PR says it adopts. Split the profile action from the list of platform-specific content.

**This is a generic starting point, not a substitute for site knowledge.** Operators who run this in a real environment fork the default profile and replace this file with their platform's specifics: top-level CRDs, namespace conventions, the dependency direction between components, version-pivot gotchas, and common failure modes worth pre-loading. The README explains how to do that with `base: default` in a sibling `profile.yaml`.

skills/writing-simply/SKILL.md:59

• The mandatory self-check does not search for several forms that the preceding rules ban, including 've, 'm, 'd, past perfect, and progressive passive. A draft containing “we've”, “I'm”, “had been”, or “was being” can therefore pass this check unchanged. Include these mechanical patterns so the self-check enforces the stated contraction and tense rules.

• Files reviewed: 41/41 changed files
• Comments generated: 3
• Review effort level: Balanced

[sourcehawk]

Round 3 suppressed findings, all applied in 7fe9a7e:

• operator-skills/capture-decisions/SKILL.md:16 (no substring matcher): confirmed against Branch in pkg/mcp/strategies/playbook.go. The skill now says the agent reads the reply and picks the route, and explains the trailing keyword as the one unambiguous signal among bullets that name several routes.
• internal/profile/profiles/default/prompts/architecture.md:9 (sentence over 25 words): split into three sentences, the longest 22 words.
• skills/writing-simply/SKILL.md:59 (self-check misses banned forms): the search list now includes 've, 'm, 'd, had been, is being, and was being.

[Copilot]

🟡 Changes recommended

Issue guidance conflicts with its body contract, and several rewritten prompts still violate the newly mandated writing rules.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 41/41 changed files
• Comments generated: 4
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

Embedded prompts contain dangling reference paths, and backfill guidance conflicts with the shared imperative style for operator lessons.

Review details

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

skills/writing-simply/SKILL.md:10

• WritingSimply() embeds this text into investigation and editor prompts whose working directory has no references/ tree (prompts/prompts.go:428-434). This unconditional relative path therefore points to a file the agent cannot read. Qualify it as available only when the skill is loaded from disk.

This issue also appears on line 69 of the same file.
system/wiki_backfill_ingestion.yaml:147

• This assigns simple past to all backfill prose, but the next paragraph requires operator-facing ## Lessons takeaways, which the shared skill classifies as procedural imperatives. The conflicting instructions can turn actionable lessons into historical statements. Limit simple past to descriptive prose and preserve imperative takeaways.

skills/writing-simply/SKILL.md:69

• These relative paths are also embedded into fresh sub-agent prompts without their reference files, so an agent that follows the audit pointer gets a failed read instead of the promised checklist. Mark the references as disk-only, as with the catalog pointer above.

• Files reviewed: 51/51 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[sourcehawk]

Round 12 suppressed findings (no posted comments), all applied in aa8d26d:

• skills/writing-simply/SKILL.md:10 and :69: both references/ pointers now say the files exist only when the skill is loaded from disk, and that the embedded body stands alone with the self-check as the complete audit.
• system/wiki_backfill_ingestion.yaml:147: the voice rule is per section: Summary, Root cause, and Fix in the simple past; operator takeaways in Lessons imperative; the agent retrospective in Lessons simple past.

[Copilot]

🔵 Needs a closer look

Several concrete prompt examples still violate the writing rules they instruct agents to follow.

Review details

Suppressed comments (4)

Previously missed (3) — in code that hasn't changed since the last review.

operator-skills/evaluating-codefixes/SKILL.md:44

• This recommended follow-up uses the banned modal would, directly contradicting the writing-simply instruction that operator messages must follow. Use the approved can form so the example reinforces the rule.

> Would the alert have fired early enough to shorten triage? If the OOM follows the scrape spike within 30 seconds, a 1-minute window does not help.

operator-skills/finishing-a-session/SKILL.md:28

• This finish example uses the banned modal could, so the operator is given a concrete output that violates the writing skill it must follow. State the observed reason directly instead.

> `finish("Closed without findings. The symptom resolved before we could capture it.")`

internal/profile/profiles/default/prompts/strategies.md:15

• This output guidance still violates the embedded rules in two places: TL;DRs contains the banned semicolon, and the concrete postscript uses the contraction you'd. Agents tend to copy examples, so make the surrounding contract compliant too.

4. **Conclusion.** When you reach a `terminal_advice` node in the final domain playbook of the chain, call `summarize`. The frontend renders the verdict (symptom, root cause, next steps, confidence) and the evidence as two separate cards. `symptom` and `root_cause` are Slack-shareable TL;DRs: no bullets, no log citations. `symptom` is at most two sentences. `root_cause` is two or three. All bullets, log lines, timestamps, and citations belong in `evidence`. Do not restate every tool call. The activity panel is the audit trail. You can add a one-line postscript in chat ("Anything else you'd like me to dig into?") and stop.

prompts/prompts.go:418

• The final sentence combines two sequential tool calls, while the newly embedded rules require one instruction per procedural sentence. Split the calls so this generated editor prompt follows the contract it gives the agent.

• Files reviewed: 51/51 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[sourcehawk]

Round 13 suppressed findings (no posted comments), all applied in 30c0ef3:

• operator-skills/evaluating-codefixes/SKILL.md:44: "Does the alert fire early enough to shorten triage?"
• operator-skills/finishing-a-session/SKILL.md:28: finish("Closed without findings. The symptom resolved before capture.")
• internal/profile/profiles/default/prompts/strategies.md:15: "TL;DRs" is now "summaries"; the postscript example has no contraction.
• prompts/prompts.go:418: the two backfill tool calls are separate sentences.

[Copilot]

🟡 Changes recommended

Conflicting issue-shape rules and incomplete bug-route lifecycle guidance can produce incorrect agent behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

operator-skills/capture-decisions/SKILL.md:62

• This contradicts the required reply shape above, which mandates one bullet per category. An operator cannot both emit all four category bullets and use only “Agreed.” plus the keyword. Make the abbreviated case explicit without dropping the category review, or relax the earlier requirement.

This reply splits the wiki, replaces the playbook, adds a codefix the agent declined, gives one reason per move, and ends with the keyword. Match this shape when the investigation has that much texture. When the agent's proposals are already right, "Agreed." plus the keyword is enough.

operator-skills/finishing-a-session/SKILL.md:12

• The new issue-only bug route does not satisfy this completion checklist: bug_report_proposal files an issue directly and stages no draft, proposal, or PR. The operator can therefore treat a completed bug capture as unfinished instead of calling finish. Include filed issues among the completed artifacts.

1. The capture flow ran to completion. You routed the capture. The flows staged their drafts, proposals, or PRs. You approved what needed approval. The agent emitted a final `end` with no pending question.

• Files reviewed: 51/51 changed files
• Comments generated: 2
• Review effort level: Balanced

[sourcehawk]

Round 14 suppressed findings, both applied in 01deb5a:

• operator-skills/capture-decisions/SKILL.md:62: the short-reply case keeps one bullet per category ("Wiki: agreed.") instead of dropping the bullets.
• operator-skills/finishing-a-session/SKILL.md:12: filed issues (the bug route) count as completed capture artifacts.

[Copilot]

🔵 Needs a closer look

Operator guidance contains impossible wait actions and can misroute valid issue-only bugs to the wiki.

Review details

Suppressed comments (3)

Previously missed (3) — in code that hasn't changed since the last review.

operator-skills/steering-investigations/SKILL.md:17

• wait is not an available operator action. Every wake-up prompt requires exactly one of send_message, request_takeover, or finish (internal/auto/operator.go:148), and operator-role says a turn without one dead-ends the session. In this state the safe available action is a minimal acknowledgement, so do not offer an impossible zero-action branch.

If none apply, send a one-word acknowledgement or wait for the agent's next question. You do not have to contribute every turn.

operator-skills/evaluating-codefixes/SKILL.md:23

• This sends issue-worthy findings to the wiki whenever the investigation identifies a concrete problem but has not designed a named fix. That contradicts the bug route, whose warrant only requires a concrete, bounded, issue-shaped problem and explicitly lets the maintainer decide the fix (system/bug_report_proposal.yaml:34-49). Route such findings to bug; reserve wiki fallback for problems that are not concrete, do not close this incident class, or have no linked-repo owner.

If tests 1, 3, and 4 hold but test 2 fails, route `bug`: file the issue and let the maintainer decide on the fix. If test 1, test 3, or test 4 fails, it is wiki material. A change that no linked repo owns still helps the next operator as a note. If the change is playbook YAML, it is a `playbook` proposal. See `capture-decisions`.

operator-skills/resuming-after-takeover/SKILL.md:28

• The catch-up prompt ends with “Respond with exactly one action: send_message, request_takeover, or finish” (internal/auto/operator.go:154-158), so the operator cannot follow this Wait instruction. Sending a message during tool use is also not equivalent to waiting. Either defer the resume wake until the next end, or add a real terminal wait action and include it in the operator contract.

| Agent mid-tool-use, no question | Wait. The next `end` wakes you |

• Files reviewed: 51/51 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[sourcehawk]

Round 15 suppressed findings, all applied in 4c193db:

• operator-skills/steering-investigations/SKILL.md:17 and resuming-after-takeover/SKILL.md:28: "wait" removed; both now say to send a one-word acknowledgement, since every wake-up ends with one terminal action.
• operator-skills/evaluating-codefixes/SKILL.md:23: a concrete, owned problem with no named fix (or a fix too large for one run) routes to bug; wiki is reserved for problems that do not close this incident class or that no linked repo owns. The gesture row in the table says why it stays wiki: no concrete problem to file.

[Copilot]

🔵 Needs a closer look

Several writing checks and issue-routing prompts contain contradictory guidance that can produce incorrect artifacts.

Review details

Suppressed comments (8)

Previously missed (6) — in code that hasn't changed since the last review.

skills/writing-simply/SKILL.md:64

• This “complete audit” misses the plural progressive forms are being and were being, so text such as “pods are being restarted” passes the prescribed search despite violating the rule above. Include both forms in the search list.

This issue also appears on line 65 of the same file.
skills/writing-simply/references/checklist.md:15

• The full audit also omits were being, so a common progressive passive is not caught even though this row claims to cover that violation. Add it alongside the other singular and plural forms.

This issue also appears on line 20 of the same file.
skills/writing-simply/references/simple-english.md:309

• The catalog defines Rule 5.4 only for required conditions before commands, but this self-check expands it to every occurrence of if and when. That incorrectly rejects indirect questions and complements such as “record when the alert fired”; restrict the check to conditional clauses.
  operator-skills/capture-decisions/SKILL.md:13
• The capture_offer message proposes only Wiki, Playbook, and Codefix categories; Bug appears only as a possible recommendation inside Codefix. Requiring a Bug: bullet for every reply therefore makes the operator invent an unproposed category, contradicts the no-padding rule, and even conflicts with the example below, which omits it. Require bullets only for proposed categories and add Bug conditionally.

2. One bullet per category (`Wiki:`, `Playbook:`, `Codefix:`, `Bug:`): accept, refine, or drop, with the reason, in one or two sentences.

system/pr_proposal.yaml:179

• This guidance is internally contradictory: “why split, not raise the threshold” is explicitly a design choice, while the BODY SHAPE forbids design (pkg/mcp/git/body_shapes.go:26,40) and these lines delegate design to the codefix sub-agent. Remove the design-rationale exception and keep only problem constraints that inform acceptance criteria.
  system/bug_report_proposal.yaml:161
• These instructions both invite a non-obvious design choice (“split, not raise”) and say that the maintainer decides the fix. They also conflict with the BODY SHAPE's explicit “No solution, no design” rule (pkg/mcp/git/body_shapes.go:26,40). Keep the Description focused on the problem and its constraints.

skills/writing-simply/SKILL.md:65

• This check treats every if and when as a condition, but Rule 5.4 only applies to a required condition before a command. Legitimate complements such as “Record when the pod restarted” cannot start the sentence, so this instruction forces incorrect rewrites. Limit the check to conditional clauses.
  skills/writing-simply/references/checklist.md:20
• This mechanical pattern marks valid indirect uses such as “record when the pod restarted” as violations. Rule 5.4 only moves required conditions before commands, so narrow the row to conditional clauses instead of every mid-sentence if or when.

• Files reviewed: 51/51 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[sourcehawk]

Round 16 suppressed findings, all applied in 183e61e:

• skills/writing-simply/SKILL.md:64 and references/checklist.md:15: the search lists include are being and were being.
• SKILL.md:65, references/checklist.md:20, references/simple-english.md:309: the condition-first check applies only to an if/when clause that states a condition for an instruction; a when that names a time is called out as not a condition.
• operator-skills/capture-decisions/SKILL.md:13: bullets are required only for the categories the agent proposed; a Bug: bullet is added when a change is routed to bug.
• system/pr_proposal.yaml:179 and bug_report_proposal.yaml:161: the Description guidance states a constraint as a fact about the problem ("raising the threshold hides the second cause") instead of inviting a design choice.

[Copilot]

🟡 Changes recommended

The shared untouchable-text rule can preserve credentials in durable artifacts, and post-mortem tense guidance misrepresents unresolved state.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 51/51 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

Broad behavioral prompt changes across many agent surfaces require final human validation.

Review details

• Files reviewed: 51/51 changed files
• Comments generated: 0 new
• Review effort level: Balanced