RFC 0027: Simplified Technical English for OpenClaw documentation

[jjjhenriksen]

What Problem This Solves

OpenClaw technical documentation spans many repositories and document types.
Different terms and sentence structures make technical meaning, search, and
translation less reliable. Contributors also lack one shared process for
reviewing new prose and for recording when a code change needs documentation.

Why This Change Was Made

RFC 0027 defines ASD-STE100 Issue 9 as the English technical-writing standard,
adds an OpenClaw term base, and proposes small repository-owned migration sets.
It also defines source and generated-document boundaries, an author-aid
checker, dual human review, phased rollout, and migration evidence.

The rollout is intentionally slow. It gives contributors and AI-assisted
contributors a short guide and examples first. It then proposes staged
ClawSweeper reporting, followed by a required check for PRs that change
documentation or change behavior that needs a documentation decision.

User Impact

This proposal aims to make OpenClaw documentation clearer, more consistent,
and easier to translate. It does not change code, runtime behavior, CLI help,
UI text, commands, API values, or generated translation output. The current
PR is an RFC-only draft; implementation and any ClawSweeper gate require later
maintainer review.

Evidence

• git diff --check
• RFC structure checked against rfcs/0000-template.md and README.md
• Structural STE check: zero descriptive sentences over 25 words and zero paragraphs over six sentences
• Current main review and comparison with merged RFC PRs, including the repository PR template alignment in chore: align pull request template #36
• Existing openclaw/openclaw to openclaw/docs publication and translation boundary preserved
• Manual review requested before implementation work begins

AI-assisted draft; wording and rollout boundaries reviewed manually.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 22, 2026, 9:04 AM ET / 13:04 UTC.

ClawSweeper review

What this changes

This PR adds a 381-line RFC proposing Simplified Technical English, a shared term base, and phased documentation-review checks across OpenClaw repositories.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep this draft open: current main already assigns RFC 0027 to a different accepted proposal, so this branch needs an unused identifier; the organization-wide documentation policy also requires explicit maintainer direction.

Priority: P2
Reviewed head: 68e7376162d1a0590e2bbb7b0e177eddff79d769
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The proposal is structured and docs-only, but it has a blocking identifier collision and awaits product sponsorship.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes only an RFC document, so runtime behavior proof is not applicable.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This PR changes only an RFC document, so runtime behavior proof is not applicable.
Evidence reviewed	4 items	RFC identifier already assigned on current main: Current main contains an accepted, unrelated RFC at the same numeric identifier, rfcs/0027-openclaw-enterprise.md; adding this document as another 0027 would make RFC references ambiguous. Current identifier provenance: The existing RFC 0027 was merged to main by commit af708f0ddb6f42cc4f4bc5499889cdc6889aef58 on 2026-08-01 and explicitly records its accepted status and implementation issue. Prior blocker remains unchanged: The added RFC retains the conflicting 0027 filename and its current head has no file changes since the previous review SHA, so the prior identifier finding remains applicable.
Findings	1 actionable finding	[P1] Assign an unused RFC identifier
Security	None	None.

How this fits together

The RFC repository records cross-project design and process decisions before implementation. This proposal would feed future repository documentation guidance, CI checks, and contributor review practices.

flowchart LR
A[Documentation authors] --> B[Controlled-English guidance]
B --> C[Repository declarations]
C --> D[Author-aid checker]
D --> E[Human review]
E --> F[Published documentation]

Loading

Decision needed

Question	Recommendation
Should OpenClaw sponsor a bounded pilot for an organization-wide Simplified Technical English policy, including its owner and future ClawSweeper gate, before accepting this RFC?	Sponsor a bounded pilot: Rename the RFC to an unused identifier and define a named owner, pilot repositories, and exit criteria before accepting the direction.

Why: The proposal intentionally creates cross-repository policy, configuration, and future required-check surface; source review cannot determine whether that direction is wanted or who should own it.

Before merge

• Add real behavior proof - Not applicable: This PR changes only an RFC document, so runtime behavior proof is not applicable.
• Assign an unused RFC identifier (P1) - This remains unresolved from the prior review: current main already contains accepted rfcs/0027-openclaw-enterprise.md. Rename this added file and its RFC references to an unused identifier; otherwise the repository will contain two different RFC 0027 documents and links or discussion will be ambiguous.
• Resolve merge risk (P1) - Merging this RFC as written would establish broad future documentation and review requirements for existing repositories without a maintainer-selected policy owner, checker, or pilot acceptance decision.
• Complete next step (P2) - A mechanical identifier repair is clear, but acceptance of the cross-repository policy and its ownership requires maintainer product direction.

Findings

• [P1] Assign an unused RFC identifier — rfcs/0027-simplified-technical-english.md:1

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC scope	1 file added, 381 lines	Although the diff is documentation-only, it proposes organization-wide configuration and future review-gate behavior.

Merge-risk options

Maintainer options:

1. Repair the identifier and sponsor a pilot (recommended)
   Use an unused RFC number and add an owner-backed pilot decision before merging policy that can later change repository documentation requirements.
2. Keep the RFC as a draft
   Pause acceptance until maintainers choose the policy owner, checker approach, and rollout authority.

Technical review

Best possible solution:

Assign an unused RFC number, then obtain a maintainer-sponsored decision on whether to run a bounded pilot with named ownership before adopting organization-wide review requirements.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a policy RFC rather than a runtime defect; the structural identifier conflict is directly verifiable from current main.

Is this the best way to solve the issue?

No: an unused identifier is necessary, and the remaining organization-wide policy direction should be narrowed or explicitly sponsored rather than accepted by default.

Full review comments:

• [P1] Assign an unused RFC identifier — rfcs/0027-simplified-technical-english.md:1
  This remains unresolved from the prior review: current main already contains accepted rfcs/0027-openclaw-enterprise.md. Rename this added file and its RFC references to an unused identifier; otherwise the repository will contain two different RFC 0027 documents and links or discussion will be ambiguous.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against af708f0ddb6f.

Labels

Label justifications:

• P2: This is a broad but non-urgent process proposal whose acceptance needs a normal maintainer decision.
• merge-risk: 🚨 compatibility: The RFC proposes future required documentation checks and repository declarations that could affect existing contributor workflows.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This PR changes only an RFC document, so runtime behavior proof is not applicable.

Evidence

What I checked:

• RFC identifier already assigned on current main: Current main contains an accepted, unrelated RFC at the same numeric identifier, rfcs/0027-openclaw-enterprise.md; adding this document as another 0027 would make RFC references ambiguous. (rfcs/0027-openclaw-enterprise.md:1, af708f0ddb6f)
• Current identifier provenance: The existing RFC 0027 was merged to main by commit af708f0ddb6f42cc4f4bc5499889cdc6889aef58 on 2026-08-01 and explicitly records its accepted status and implementation issue. (rfcs/0027-openclaw-enterprise.md:7, af708f0ddb6f)
• Prior blocker remains unchanged: The added RFC retains the conflicting 0027 filename and its current head has no file changes since the previous review SHA, so the prior identifier finding remains applicable. (rfcs/0027-simplified-technical-english.md:1, 68e7376162d1)
• RFC process contract: The repository README defines RFC filenames as <id>-<short-name>.md and requires draft RFCs to remain unmerged pending the RFC lifecycle and discussion process. (README.md:16, af708f0ddb6f)

Likely related people:

• kevinlin-openai: Authored the accepted current-main RFC that occupies identifier 0027 and updated the repository RFC process history. (role: introduced the current RFC 0027 and recent RFC contributor; confidence: high; commits: af708f0ddb6f, e366ea9825a4; files: rfcs/0027-openclaw-enterprise.md, README.md, rfcs/0000-template.md)
• Dallin Romney: Authored the RFC sidecar-layout clarification that informs the repository's document-organization conventions. (role: RFC layout contributor; confidence: medium; commits: 3aa7d727383f; files: README.md, rfcs/0000-template.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Rename the RFC to an unused identifier and update its metadata or references.
• Obtain maintainer direction on the pilot owner, scope, and adoption path.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (70 earlier review cycles; latest 8 shown)

• reviewed 2026-08-09T12:41:54.136Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Use an unused RFC identifier
• reviewed 2026-08-09T14:50:38.053Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Use an unused RFC identifier
• reviewed 2026-08-09T19:49:46.869Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-09T22:00:30.561Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-09T23:12:23.764Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-11T03:13:31.436Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-13T05:24:04.120Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-15T07:05:34.925Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier