asd-ste100

Files (5)

• SKILL.md
• coverage.md · references/
• sentences.md · references/
• structure.md · references/
• words.md · references/

SKILL.md (first lines)

# ASD-STE100

Make an English spec, GitHub issue, or idea readable in one pass by a person or an agent.
When the user asks for this skill on a text in another language, apply the same checklist to that language and name the language in the Scope line.
Use the writing rules of Issue 9, adapted to software work.
The checklist guides writing and sets the acceptance criteria for a review.

## Terms

- **Target text**: the English spec, GitHub issue, or idea that you write or review
- **Item**: one checklist entry with a fixed `STE_NN` identifier
- **Issue 9**: the January 2025 edition of ASD-STE100 Simplified Technical English
- **Project glossary**: the project's names and their plain meanings. See [words](references/words.md)
- **Step**: one marked unit in an ordered set of instructions. See [structure](references/structure.md)
- **Instruction**: a sentence that directs the reader to act. See [structure](references/structure.md)
- **Descriptive text**: text that explains a fact or behavior. See [sentences](references/sentences.md)
- **Note**: extra information that the reader can skip. See [structure](references/structure.md)
- **Risk note**: a labeled message that states a safe action or condition and the harm if the reader ignores the precaution. See [structure](references/structure.md)
- **Noun group**: words that together name one thing. See [words](references/words.md)

## Keep the meaning

In every branch, each rewrite and each proposed fix changes wording only.
Keep every fact, number, actor, condition, scope limit, and open question.
Keep the strength of each "must", "should", "may", and "not".
If no source establishes an actor, a condition, or the meaning of a term, state an open question.

## Pick the branch

Choose the branch that matches the request:

- Write or rewrite: follow **Write**
- Review: follow **Review**
- Fix named items, such as `fix STE_06`: apply those items to the specified lines. Then check the changed lines against every applicable item, and report through Review step 3

## Write

1. Collect the project glossary from the repository, request, and user.
   Done when each thing named in the target text has one name.
2. Sort the content into descriptive text, instructions, notes, and risk notes.
   Done when each block belongs to one of these four types.
3. Draft or rewrite the target text against the checklist.
   Done when the draft preserves the source meaning and covers every applicable item.
4. Run the Review branch on the draft.
   Fix each finding and repeat the review.
   Done when a pass finds nothing new and each kept finding has a reason stated in the reply.
5. Reply with the target text, followed by `STE: Pass: <IDs>`.
   Include each kept finding and its reason.
   End with the fixed scope line shown in Review.
   Done when the reply contains the text, the result, any kept findings, and the fixed scope line.

## Review

1. Mark descriptive text, instructions, notes, and risk notes in the target text.
   Use the applicability table below. Done when each block has a type.
2. Check each applicable item, starting with STE_01, STE_07, STE_15, STE_02, STE_06, and STE_12.
   If an item's condition is unclear for a sentence, read that item's reference entry.
   Done when each item has findings, passes, or does not apply.
3. Report findings by item, with a count for each item.
   A finding that fits two items goes under the more specific one.
   Give each finding's location and its proposed fix or open question.
   For kept STE_11 overruns, give a count and a shared reason instead of individual locations and fixes.
   Then give a `Pass:` line for checked items without findings, including items marked `n/a`.
   End with the fixed scope line shown below.
   Done when every checked item has a result and the report states its scope.

Example report for descriptive text:

```text
STE_06 One referent per pronoun: 1
- issue.md:12 "It retries failed jobs." Open question: does the scheduler or the worker retry failed jobs?
Pass: STE_01–STE_05, STE_07–STE_13, STE_14–STE_17 (n/a)
Scope: Selected Issue 9 writing rules, adapted to software. Dictionary not checked.
```

## Applicability

Use each item for the text types in this table:

| Items | Text types |
|---|---|
| STE_01–STE_13 | All text |
| STE_14–STE_15 | Instructions |
| STE_16 | Notes |
| STE_17 | An instruction that can cause harm |

In the Pass line, mark an item that does not apply as `n/a`.

## Checklist

### Words

- [ ] **STE_01 One name per thing**: Each thing has one name, and each name means one thing. Use the project's real name or the user's term throughout the target text. _(Issue 9: 1.8, 1.11, 6.2, 9.4)_
- [ ] **STE_02 New terms explained at first use**: Each unfamiliar name, acronym, or project term has a plain explanation at first use. _(Issue 9: 2.2)_
- [ ] **STE_03 Plain words, one meaning each**: General prose uses everyday words in their usual senses. Specialized words name real software concepts. Replace team slang, Latin abbreviations, and words mistaken for similar words in another language. _(Issue 9: 1.1, 1.3, 1.5, 1.6, 1.10, 1.12, 9.2, GR-5, GR-6)_
- [ ] **STE_04 Each word keeps its role**: Nouns stay nouns and verbs stay verbs. Use ordinary word forms. _(Issue 9: 1.2, 1.4, 1.7, 1.13)_
- [ ] **STE_05 Short noun groups**: A noun group that the writer creates has at most three words. A longer official name appears in full with an explanation at first use. Later uses keep that exact name, or a short form defined at first use. _(Issue 9: 1.9, 2.1, 2.2, 8.2)_
- [ ] **STE_06 One referent per pronoun**: Each pronoun or shortened reference, such as "the skill", points to one thing. A noun follows "this". _(Issue 9: 4.5, GR-3, GR-4)_

### Sentences

- [ ] **STE_07 The actor is named**: A sentence about an action names the actor. Descriptive text permits passive voice when the actor is unknown or does not matter. _(Issue 9: 3.6)_
- [ ] **STE_08 Actions in simple verbs**: An action uses a verb in a simple tense. Replace a phrasal verb, or an action noun such as "perform validation", with one equally precise verb. Rewrite an ambiguous "-ing" form. _(Issue 9: 3.2, 3.3, 3.4, 3.5, 3.7, 9.3)_
- [ ] **STE_09 One idea per complete sentence**: Each sentence keeps one idea and its needed words, including articles and "that". Spell out contractions. Use complete prose instead of arrows, slashes, semicolons, or missing words. List items can be fragments that fit their introductory sentence. When "with" can mean two relationships, name the relationship. _(Issue 9: 4.1, 4.2, 4.5, 6.1, 8.1, 9.1, GR-1, GR-2)_
- [ ] **STE_10 Linked sentences**: A sentence that continues, explains, or contrasts the preceding sentence states that link with a connecting word or a repeated key term. _(Issue 9: 4.4, 6.2)_
- [ ] **STE_11 Sentence length limits**: Each instruction, and each sentence in a step or a risk note, has at most 20 words. Other sentences, including notes, have at most 25. Before you report a sentence over its limit, count its words by the conventions in [sentences](references/sentences.md). Split a longer sentence when it carries two ideas, and report the others as a count. _(Issue 9: 5.1, 6.3, 8.4, 8.5, 8.6, 8.7)_

### Structure

- [ ] **STE_12 Point first**: Each section and paragraph opens with its problem, answer, or decision. Each paragraph covers one topic. _(Issue 9: 6.4, 6.5)_
- [ ] **STE_13 Lists for complex text**: A long sentence that lists many items, or a series of dependent actions, becomes a vertical list after an introductory sentence. List items use parallel forms. A list keeps facts and instructions apart. _(Issue 9: 4.3)_
- [ ] **STE_14 One instruction per step**: Each step gives one action, in command form, after any leading condition. Sequential actions have separate steps. Simultaneous actions may share a step. _(Issue 9: 5.2, 5.3)_
- [ ] **STE_15 Condition before command**: A condition, prerequisite, or purpose precedes the command that it governs. _(Issue 9: 5.4)_
- [ ] **STE_16 Notes hold no instructions**: A note contains information only. Steps or risk notes hold actions, requirements, and risks. The steps work without the notes. _(Issue 9: 5.5)_
- [ ] **STE_17 Risk note before the risky instruction**: Before an instruction that can cause harm, a risk note gives a label, a safe action or condition, and the consequence. Risks include data loss, production failure, secret exposure, and irreversible changes. _(Issue 9: 7.1, 7.2, 7.3)_

IDs never change and are never reused. To change the meaning of a published item, move its line under `### Voided` with `void <date>, replaced by STE_NN`. Give the new item the next free ID.

## References

From pascalandy/skills, MIT.

More from pascalandy/skills