- Home
- Skills
- Technical Documentation
- STE Precision — Technical Writing Clarity Auditor
Works with the AI Agents you already use
STE Precision — Technical Writing Clarity Auditor
Audits and rewrites technical documentation for ASD-STE100-informed clarity using a deterministic offline screener, without ever claiming false compliance certification.
$7.15
STE Precision — Technical Writing Clarity Auditor
Example session with this skill installed
Here's a snippet from our on-call runbook, can you tighten it up? "In the event that the primary database connection is lost, the on-call engineer, after first checking the status dashboard and confirming that the issue is not a known scheduled maintenance window, which can be verified via the maintenance calendar, should then proceed to restart the connection pooler service; note that this operation may cause a brief service interruption of up to 30 seconds, and it is important that the engineer does not restart the primary database itself as this could cause data loss."
- Read your context and instructions
- Compiled the ste precision
Document Type / Mode
Procedure (runbook step) —
STE-informed clarity mode. No compliance label attached; this is a clarity rewrite, not a certified standards audit.
Deterministic Script Output
$ python scripts/ste_audit.py runbook_excerpt.md --mode procedure --format json
PARTIAL_STRUCTURAL_REVIEW / UNVERIFIED_LEXICAL — 2 candidates
L1: sentence_length_candidate — "In the event that the primary database connection is lost, the on-call engineer..." (approx. 52 words; threshold 20)
L1: semicolon_candidate — "...restart the connection pooler service; note that this operation may cause..."
Protected Elements Frozen Before Editing
| Element | Value | Must not change |
|---|---|---|
| Modal (uncertainty) | "may cause" | Stays "may" — not "will" or "does" |
| Negation | "does not restart the primary database" | Stays negative — not rephrased positive |
| Numeric limit | "up to 30 seconds" | Exact value preserved |
| Precondition | "checking the status dashboard... confirming... not a scheduled maintenance window" | Order preserved — happens before the restart action |
| Prohibition rationale | "could cause data loss" | Preserved — this is the reason the prohibition exists |
Minimal Rewrite (One Instruction Per Sentence)
If the primary database connection is lost, do this:
- Check the status dashboard.
- Confirm the maintenance calendar does not show a scheduled maintenance window for this time.
- Restart the connection pooler service.
NOTE: This restart may cause a service interruption of up to 30 seconds.
WARNING: Do not restart the primary database. This can cause data loss.
Semantic-Change Ledger
| Proposition | Before | After | Status |
|---|---|---|---|
| Interruption possibility | "may cause... up to 30 seconds" | "may cause... up to 30 seconds" | PRESERVED — modal and numeric limit unchanged |
| Prohibition on primary DB restart | buried mid-sentence, after the main instruction | promoted to a standalone WARNING, placed last | PRESERVED (meaning), flag: placement changed — confirm a trailing WARNING is acceptable in your runbook format, or require it immediately after step 3 |
| Precondition order | checks before restart | checks before restart (steps 1–2 before step 3) | PRESERVED |
Verified vs. Unverified
Verified by script: sentence-length and semicolon flags on the original; protected-token diff confirms no numeric, modal, or negation drift in the rewrite.
Unverified (requires your/SME review): whether a trailing WARNING label meets your organization's runbook formatting standard — the skill does not certify runbook-formatting compliance, only flags the placement change for your decision.
Next Steps
- Confirm the WARNING placement (trailing vs. immediately after the triggering step) matches your runbook's house style.
- Run
python scripts/ste_audit.pyagainst the final version once placed in the actual runbook file to confirm no new length/semicolon candidates were introduced. - Have the on-call lead sign off on the semantic-change ledger before this replaces the live runbook entry.
Verification Commands
python scripts/ste_audit.py runbook_excerpt.md --mode procedure --format json
python -m unittest discover -s tests
Connects securely to your tools. The creator never sees your data.
About this skill
Technical documentation — READMEs, runbooks, API docs, safety procedures — needs unambiguous language, but most "make this clearer" AI rewrites quietly change meaning: turning "may return an error" into "returns an error," or softening a "do not disconnect" warning. This skill applies ASD-STE100 Issue 9 controlled-language principles to technical writing with a built-in semantic-safety net, plus a bundled deterministic Python script for repeatable offline screening — and it is explicit, at every step, about what it cannot certify.
What it solves
- Stops meaning-changing "simplification" of safety-critical language (negations, modals, obligations, numeric limits).
- Replaces subjective "sounds clearer to me" judgments with a repeatable, offline, stdlib-only structural screen.
- Prevents false compliance claims — the skill explicitly states it is not ASD/STEMG-affiliated or certified, and labels every finding with an honest status (
CLARITY_REVIEW_ONLY,PARTIAL_STRUCTURAL_REVIEW,UNVERIFIED_LEXICAL, orEXPERT_REVIEW_REQUIRED). - Keeps a frozen inventory of protected elements (commands, numbers, units, WARNINGS/CAUTIONS, negations, modal strength) so nothing safety-relevant changes without explicit escalation.
How the workflow operates
- Inventories the document type, audience, safety criticality, and applicable standard before touching anything.
- Freezes protected elements (code, API names, numbers, units, preconditions, safety labels) as invariants pending human approval.
- Generates minimal rewrite candidates — one ambiguity at a time — rather than a full rewrite.
- Runs the bundled
scripts/ste_audit.pyfor deterministic, offline sentence-length, passive-voice, semicolon, contraction, and note-command candidate detection, with an optional--comparemode that flags protected-token drift between two versions. - Runs a semantic-guard review comparing before/after text for changes to negation, modality, numbers, roles, or order — escalating anything risky to the user/SME instead of silently approving it.
- Reports findings with sentence-level evidence, explicit "verified vs. unverified" labeling, and never a fake accuracy percentage or compliance badge.
What's inside the package
SKILL.md— the accuracy contract, mode dispatch, full workflow, and output-format rules.references/evaluation.md— how to build a real evaluation dataset and what the deterministic script does and does not check.references/issue9-migration-notes.mdandreferences/issue9-rule-register.md— a 53-rule independently-paraphrased research register with verification dependencies.references/official-pdf-audit.md,references/source-ledger.md,references/rule-map.md,references/mode-policy.md,references/semantic-guard.md— source provenance, document-class rules, and the meaning-preservation review protocol.scripts/ste_audit.py— a zero-dependency Python 3 stdlib script for offline structural screening (sentence length, passive voice, semicolons, contractions, protected-token drift).tests/test_ste_audit.py— a 49-case unit test suite covering the screener's structural checks, meaning-risk comparisons, and CLI behavior.
Ideal use cases
- Auditing READMEs, runbooks, or API docs for ambiguity before publishing.
- Screening a documentation rewrite for accidental meaning changes before merging.
- Teams that want a repeatable, offline, no-network clarity check in CI without a compliance claim attached.
- Technical writers who want ASD-STE100-informed brevity without flattening necessary precision.
Not certified by ASD/STEMG. Cannot verify dictionary compliance without the official PDF. Safety-critical text requires human expert review. Heuristic checks are not exhaustive.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 24 days ago
Permissions
The bundled script only reads the file(s) you explicitly point it at and never writes or modifies them; terminal access is needed only to invoke the local Python screener, with no network calls anywhere in the package.