agentleFS
hamzzaqureshihamzzaqureshi/gravidex/.claude/skills/asd-ste100/SKILL.md

asd-ste100

Skill1 starsChanged 10 days agoMITView on GitHub

Use when English text must be parsed without ambiguity by AI agents or downstream systems (tool descriptions, error messages, inter-agent instructions, system prompts, schemas, ADRs) or when explaining technical concepts with minimum cognitive load. Enforces ASD-STE100 (Simplified Technical English, Issue 9) or Andrej Karpathy's 80% Pragmatic Mode: short sentences, active voice, approved vocabulary, max 3-word noun clusters, no progressive/passive forms, and 4 cognitive modalities (text, Mermaid diagrams, interactive HTML, video scripts).

34 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use handoff, tdd and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    handoff

    Compact the current conversation into a handoff document for another agent to pick up.

    Also in 5 projects that use this

  • GoogleSkill

    tdd

    Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

    Also in 3 projects that use this

  • GoogleSkill

    code-review

    Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 33 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When explaining complex systems or workflows, apply the 4 modalities to optimize parseability:

    line 106
  2. Distinctive:

    When an interaction involves 3 or more components, asynchronous handshakes, or branching logic, accompany the text with a standard Mermaid …

    line 112
  3. Distinctive:

    When asked to summarize a session, meeting, or architectural decision, output structured records adhering to this format:

    line 144
  4. Distinctive:

    Run the linter on any markdown file or via standard input:

    line 171
  5. Distinctive:

    Look up unapproved words and retrieve approved STE replacements:

    line 180

“Common” is measured: kept by at least 6 in 10 of the 33 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ASD-STE100: Simplified Technical English & Karpathy 80% Pragmatic Mode

ASD-STE100 is an international controlled-language specification maintained by the Aerospace and Defence Industries Association of Europe (ASD). It was created to stop maintenance personnel from misreading technical instructions, where ambiguous wording can lead to catastrophic hardware failure.

This capability applies the exact same discipline to autonomous AI agents, prompt engineering, tool contracts, and technical documentation. When language models parse instructions, tool schemas, or system prompts without a human to resolve ambiguity, unconstrained natural language produces hallucinations, invalid parameter choices, and flawed assumptions.

In addition to the aerospace standard (Issue 9, January 2025), this capability incorporates Andrej Karpathy's 80% Pragmatic Mode, which relaxes domain-specific vocabulary restrictions while preserving the cognitive parseability rules that maximize comprehension speed and accuracy.


1. When to Use This Capability

Activate this capability when:

  • An AI agent's instructions, tool descriptions, or error messages read as dense, passive, or ambiguous.
  • Writing inter-agent protocol messages, prompt templates, or function call parameters where misinterpretation causes failures.
  • Drafting architecture decision records (ADRs), runbooks, API documentation, or technical onboarding guides that require immediate cognitive clarity.
  • The user requests explanations in ASD-STE100, Simplified Technical English, "80% STE", or "Karpathy-style writing".
  • Summarizing complex sessions, decisions, or architectural reviews into structured records.
  • Linting or auditing existing documentation for passive voice, bloated sentences, unapproved synonyms, or semicolons.

2. Operational Modes: Strict 100% vs. Karpathy 80% Pragmatic

Rule DimensionStrict Mode (100% ASD-STE100)80% Pragmatic Mode (Karpathy) [Default]
Primary DomainSafety-critical systems, tool schemas, agent protocolsSoftware engineering, systems design, architecture docs
Sentence LengthProcedural: maximum 20 words.<br>Descriptive: maximum 25 words.Target 15 to 22 words. Hard ceiling: 25 words.
VoiceActive voice mandatory. Passive allowed only in descriptive text when the agent is unknown.Active voice prioritized; direct subject-verb-object structure.
Thought DensityExactly 1 instruction or thought per sentence.1 primary idea per sentence.
VocabularyRestricted to approved base words plus declared technical nouns and verbs.Plain controlled English; permits standard tech terminology (API, container, latency, cache).
Noun ClustersMaximum 3 consecutive nouns.Maximum 3 consecutive nouns. Break chains with prepositions.
PunctuationSemicolons forbidden (Rule 8.1). No contractions. No Latin abbreviations (e.g., i.e.).Semicolons forbidden. Contractions and standard abbreviations tolerated.
ParagraphsMaximum 6 sentences per paragraph. 1 topic per paragraph.Maximum 6 sentences per paragraph. Topic sentence first.
Modality SupportText tables and structured lists.4 Cognitive Modalities (Text, Mermaid, HTML, Video scripts).

For detailed breakdowns of the underlying rules, see:

  • writing-rules.md: Complete guide to the 53 writing rules of Issue 9 across 9 sections.
  • karpathy-framework.md: 80% Pragmatic Mode and the 4 Cognitive Modalities.
  • verb-forms.md: Verb forms matrix and prohibited tenses.
  • approved-words.md: Approved words, technical vocabulary, and prohibited buzzwords.

3. Anatomy of STE Sentences

Procedural Sentence

Procedural sentences give direct instructions to an operator or agent.

  • Rule: Maximum 20 words. Use the imperative verb form. Active voice.
  • Unapproved: "It is imperative that the operator ensures the hydraulic reservoir is replenished prior to commencing operation." (16 words, 4 unapproved forms)
  • Approved STE: "Make sure that the hydraulic reservoir is full before you start the operation." (13 words)
    • Make sure: Approved verb form (imperative command).
    • hydraulic reservoir: Approved technical name (2-word noun cluster).
    • is full: Descriptive state replacing unapproved "replenished".
    • before: Approved conjunction replacing "prior to".
    • you start: Direct active subject and verb.
    • the operation: Noun replacing unapproved verb "commencing".

Descriptive Sentence

Descriptive sentences explain system states, operational conditions, or specifications.

  • Rule: Maximum 25 words. Maximum 6 sentences per paragraph.
  • Unapproved: "The electrical supply unit functions in order to continually furnish high voltage power to the primary propulsion system while the activation mechanism remains in the enabled position." (25 words, bloated nominalizations)
  • Approved STE: "The power unit supplies high-voltage power to the motor when the switch is on." (14 words)

Safety Instruction

Safety instructions protect human life, physical hardware, and production data.

  • WARNING: Indicates a risk of injury or death to personnel.
  • CAUTION: Indicates a risk of damage to equipment or data corruption.
  • Format: First a clear, simple command. Then state the specific risk.
  • Example:
    WARNING: Do not touch the brake unit until it is cool. Hot parts can cause injury.
    CAUTION: Do not delete the database partition. Data loss will occur.

4. The Verb Forms Matrix

ASD-STE100 Section 3 strictly defines allowed verb tenses to prevent temporal ambiguity:

FormExampleStatusRule Citation
Command (Imperative)Close the valve. / Flush the cache.ApprovedRule 3.1
Simple PresentThe valve closes. / The service starts.ApprovedRule 3.2
Simple PastThe valve closed. / The worker halted.ApprovedRule 3.3
Simple FutureThe valve will close. / The job will execute.ApprovedRule 3.4
InfinitiveTurn the knob to close it.ApprovedRule 3.5
Past Participle (as adjective)The closed valve prevents flow.ApprovedRule 3.6
Progressive (-ing)The valve is closing.NOT approvedRule 3.7
Perfect (Compound)The valve has closed.NOT approvedRule 3.8
Passive (in procedures)The valve must be closed by the user.NOT approvedRule 3.9

[!NOTE] The -ing form is permitted only as part of an established technical noun (for example: landing gear, operating system, clustering algorithm). It is never permitted as a active progressive verb form (is running, was validating).


5. Karpathy's 4 Cognitive Modalities

When explaining complex systems or workflows, apply the 4 modalities to optimize parseability:

Modality 1: Pure Controlled Text

Direct, short sentences conforming to 80% STE. Used for README files, ADRs, PR descriptions, and runbooks.

Modality 2: Mermaid Structural Diagrams

When an interaction involves 3 or more components, asynchronous handshakes, or branching logic, accompany the text with a standard Mermaid diagram:

flowchart TD
    A[Client Request] --> B[API Gateway]
    B --> C{Token Valid?}
    C -->|Yes| D[Worker Service]
    C -->|No| E[Return 401 Unauthorized]
    D --> F[Database Write]

Modality 3: Interactive HTML Explainer Widgets

For state machines, distributed algorithms, or mathematical transforms, generate single-file self-contained HTML components featuring reactive sliders, step-by-step playback, or interactive state inspections.

Modality 4: Video Storyboards & Animation Scripts

Produce scene-by-scene animation scripts (e.g., Manim / 3Blue1Brown style) with narration cues written in STE for clear pacing and algorithmic visualization.


6. Transformation Reference Table

Non-STE / Bloated ProseStrict 100% STE Rewrite80% Pragmatic Mode Rewrite
In order to utilize the database, it is necessary that authentication be performed prior to commencing queries.You must log in before you send queries to the database.Log in before you query the database. Authentication is required.
The worker pool should be terminated subsequent to the completion of all scheduled tasks.Stop the worker pool after all tasks finish.Stop the worker pool after all tasks finish.
Make sure the system is properly configured with an adequate number of replicas.Configure the system with at least 3 replicas.Configure the system with at least 3 replicas to prevent downtime.
The data was transmitted across the network by the client agent.The client agent sent the data across the network.The client agent sent the data across the network.
We have performed an investigation into the issue and verified that no data loss has occurred.We investigated the issue. We confirmed that no data was lost.We investigated the issue and found no data loss.

7. Session Records Format

When asked to summarize a session, meeting, or architectural decision, output structured records adhering to this format:

# Session Record: [Topic Name]

## Purpose
State the user requirement or system objective in 1 to 2 active sentences.

## Decisions
- State decision 1 and the exact technical reason.
- State decision 2 and the exact technical reason.

## Completed Work
1. Step one executed in chronological order.
2. Step two executed in chronological order.

## Open Items
- List remaining uncompleted tasks or unresolved blockers.

8. Offline Governance Tooling

This capability includes pure Python standard library tools located in scripts/:

Deterministic Linter (ste_lint.py)

Run the linter on any markdown file or via standard input:

python3 scripts/ste_lint.py path/to/document.md
python3 scripts/ste_lint.py --mode strict path/to/procedure.md
echo "It is recommended to utilize the cache." | python3 scripts/ste_lint.py
python3 scripts/ste_lint.py --selftest

Vocabulary Lookup Tool (ste_lookup.py)

Look up unapproved words and retrieve approved STE replacements:

python3 scripts/ste_lookup.py utilize
python3 scripts/ste_lookup.py "prior to"
python3 scripts/ste_lookup.py --all

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.