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 September 10, 2026, 4:23 PM ET / 20:23 UTC (Revision 76).

ClawSweeper review

What this changes

Adds a draft RFC proposing Simplified Technical English, shared terminology, human review, and phased documentation checks across OpenClaw repositories.

Merge readiness

⛔ Blocked before merge - 5 items remain

The proposal remains distinct from current main and merits continued RFC discussion. The author acknowledges the unresolved identifier, evidence, and sponsorship requirements; no verified merged replacement implements this writing standard.

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

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The proposal is coherent and bounded to prose, but its identifier collision and uncaptured validation limit readiness independently of draft status.
Proof confidence	🦪 silver shellfish (2/6)	Needs stronger real behavior proof before merge: The changed artifact is an RFC under rfcs/, outside the docs/ exemption. The complete supplied body reports static checks and structural counts, but lacks a captured rendered result or validation transcript for this document; no future checker implementation or live application demonstration is required. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: The changed artifact is an RFC under rfcs/, outside the docs/ exemption. The complete supplied body reports static checks and structural counts, but lacks a captured rendered result or validation transcript for this document; no future checker implementation or live application demonstration is required. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	7 items	Verified scope and repository policy: The remote identifies openclaw/rfcs. Complete tracked-tree listings and filesystem inspection found no AGENTS.md or maintainer notes. The introduced delta contains one new 381-line RFC and no executable, workflow, dependency, or settings changes; the checkout remained clean. RFC acceptance contract: README.md and the RFC template were read fully. The lifecycle requires a maintainer discussion, acceptance, an implementation issue, and accepted frontmatter before merge; draft status is currently appropriate while discussion continues. Identifier already assigned: Current main contains the accepted enterprise proposal at rfcs/0027-openclaw-enterprise.md. GitHub confirms #35 merged as af708f0. It concerns enterprise architecture, not this writing standard.
Findings	1 actionable finding	[P2] Assign an unused RFC identifier
Security	None	None.

How this fits together

This repository records OpenClaw design proposals before implementation. The proposed documentation process would take English source prose through terminology checks and human review before publication and translation.

flowchart LR
 A[English source documents] --> B[Declared documentation scope]
 C[Writing rules and approved terms] --> D[Proposed prose checker]
 B --> D
 D --> E[Subject and language review]
 E --> F[Publication and translation]

Loading

Decision needed

Question	Recommendation
Should this proposal advance as a named, bounded STE pilot before committing all active repositories to the standard?	Sponsor a bounded pilot: Name the policy owner and pilot repositories, then use pilot results to decide whether broader adoption is warranted.

Why: The author requests sponsorship, and the proposed cross-repository review obligations require organizational ownership that code inspection cannot establish.

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The changed artifact is an RFC under rfcs/, outside the docs/ exemption. The complete supplied body reports static checks and structural counts, but lacks a captured rendered result or validation transcript for this document; no future checker implementation or live application demonstration is required. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Assign an unused RFC identifier (P2) - Current main already assigns 0027 to rfcs/0027-openclaw-enterprise.md, accepted through RFC 0027: OpenClaw as the Open Enterprise Agent Platform #35. Adding this file under the same identifier makes numbered references and future 0027/ sidecars ambiguous. Rename the proposal and update its title and identifier references. This previously reported concern remains unresolved; its impact is documentation identity rather than runtime compatibility.
• Resolve merge risk (P1) - Ownership of the shared policy, checker selection, and approval of repository completion remain unresolved, so the organization-wide commitment lacks an agreed delivery owner.
• Complete next step (P2) - Resolve the RFC identifier collision, supply captured document validation, and obtain the maintainer acceptance decision; before merge, complete the README lifecycle with discussion, accepted status, and an implementation issue.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

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

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Change scope	RFC prose +381; production code +0; tests +0	This branch records a policy proposal and does not activate its proposed enforcement.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Adopt a uniquely numbered, sponsor-owned pilot proposal with explicit success criteria and a separate decision before organization-wide enforcement.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Adopt a uniquely numbered, sponsor-owned pilot proposal with explicit success criteria and a separate decision before organization-wide enforcement.

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

Yes for the concrete review defect: the added filename uses identifier 0027, which current main already assigns to the accepted enterprise RFC. The writing-policy proposal itself does not report a runtime bug.

Is this the best way to solve the issue?

Unclear: phased conversion and human review are sensible safeguards, but a named pilot and measured reviewer/checker results are needed to justify organization-wide STE adoption.

Full review comments:

• [P2] Assign an unused RFC identifier — rfcs/0027-simplified-technical-english.md:1-2
  Current main already assigns 0027 to rfcs/0027-openclaw-enterprise.md, accepted through RFC 0027: OpenClaw as the Open Enterprise Agent Platform #35. Adding this file under the same identifier makes numbered references and future 0027/ sidecars ambiguous. Rename the proposal and update its title and identifier references. This previously reported concern remains unresolved; its impact is documentation identity rather than runtime compatibility.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.96

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 967d9aac7472.

Labels

Label changes:

• add P3: This is a documentation-policy proposal with no current runtime failure or urgent user-facing regression.
• remove merge-risk: 🚨 compatibility: Current PR review selected no merge-risk labels.
• remove P2: Current review triage priority is P3, so this older priority label is no longer current.

Label justifications:

• P3: This is a documentation-policy proposal with no current runtime failure or urgent user-facing regression.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The changed artifact is an RFC under rfcs/, outside the docs/ exemption. The complete supplied body reports static checks and structural counts, but lacks a captured rendered result or validation transcript for this document; no future checker implementation or live application demonstration is required. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Verified scope and repository policy: The remote identifies openclaw/rfcs. Complete tracked-tree listings and filesystem inspection found no AGENTS.md or maintainer notes. The introduced delta contains one new 381-line RFC and no executable, workflow, dependency, or settings changes; the checkout remained clean. (rfcs/0027-simplified-technical-english.md:1, 68e7376162d1)
• RFC acceptance contract: README.md and the RFC template were read fully. The lifecycle requires a maintainer discussion, acceptance, an implementation issue, and accepted frontmatter before merge; draft status is currently appropriate while discussion continues. (README.md:77, 967d9aac7472)
• Identifier already assigned: Current main contains the accepted enterprise proposal at rfcs/0027-openclaw-enterprise.md. GitHub confirms RFC 0027: OpenClaw as the Open Enterprise Agent Platform #35 merged as af708f0. It concerns enterprise architecture, not this writing standard. (rfcs/0027-openclaw-enterprise.md:2, af708f0ddb6f)
• Current-main and canonical comparison: Current-main searches for STE100, Simplified Technical English, controlled language, and style guide found no matching adoption. The complete returned PR listing identified no replacement proposal. The accepted localization RFC preserves translation ownership but does not adopt this English writing standard. The release endpoint returned no releases. (rfcs/0024-localization-runtime-and-coverage.md:16, 967d9aac7472)
• Prior review and contributor disposition: The previous completed review used the same pinned head and identified the numbering problem plus rendered/structural evidence and pilot sponsorship. The contributor explicitly acknowledges all three in RFC 0027: Simplified Technical English for OpenClaw documentation #53 (comment). The supplied complete body reports static checks and zero structural violations, but supplies no captured rendering or validation transcript. (rfcs/0027-simplified-technical-english.md:1, 68e7376162d1)
• RFC process history: README history identifies the process update at this commit. Local blame and older patch inspection could not complete because historical blobs were unavailable; GitHub REST inspection supplied the commit patch and author login kevinslin. Routing does not claim independently verified source-line introduction. (README.md:77, e366ea9825a4)

Likely related people:

• kevinslin: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• hannesrudolph: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

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

• Assign an unused RFC identifier and update identifier-based references.
• Attach rendered Markdown evidence or captured structural-validation output for this RFC, redacting private details; update the PR body to trigger re-review, or ask a maintainer for @clawsweeper re-review.
• Resolve the pilot sponsorship decision and complete the README acceptance lifecycle before merge.

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 (75 earlier review cycles; latest 8 shown)

• 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
• reviewed 2026-08-22T13:04:20.347Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-29T02:02:13.098Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-30T23:09:32.754Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-09-02T17:17:10.438Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-09-04T18:59:46.100Z sha 68e7376 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier

[jjjhenriksen]

Maintainer-readiness follow-up: three concrete gates remain before this can move. The proposal needs an unused RFC identifier (0027 already exists on main), captured rendered/structural validation evidence, and a named maintainer sponsor for a bounded pilot with clear ownership. I’m holding the next revision to those decisions rather than pretending the current draft is merge-ready; once the identifier and sponsor direction are settled, I’ll update the draft and request review.