Rewrite extensions/grillme/DESIGN.md in STE style and document the style rules #297

New issue

Closed

opened 2026-10-09 21:20:29 +00:00 by david · 1 comment

david commented

2026-10-09 21:20:29 +00:00

Owner

Summary

Rewrite extensions/grillme/DESIGN.md best-effort to the STE rule categories, and add a "Response style" subsection that documents the rule categories, the best-effort status, the exemptions, and a link to the ADR.

Background

Depends on: #291, #294, #295

#291 ships ste-style.ts; #294 and #295 rewrite the authored strings. Write against the shipped behaviour.

DESIGN.md is the extension's design document. It currently covers Purpose, Core Principles, User Experience (Starting, Interaction, Commands for v1, Checkpoint), Output Model, Approval Before Mutations, Technical Design (Extension State, Prompt Injection, Tools, Read-only Enforcement), MVP Scope, and Known Limitations / Future Work. It contains fenced code blocks for the checkpoint Markdown template and the tool schemas.

The rule categories are defined in extensions/grillme/ste-style.ts as STE_RULE_CATEGORIES:

Keep sentences short. Aim for about 20 words or fewer when you give an instruction. Aim for about 25 words or fewer when you describe something.
Put one idea in each sentence.
Use the active voice.
Use simple tenses: past, present, future, and the imperative.
Do not use an -ing verb form when a simple tense works.
Use one word for one meaning. Do not trade between synonyms.
Do not use a phrasal verb when one verb does the work.
Keep a group of nouns to three words or fewer.
Use short, common words.
Keep the articles (a, an, the).

The licensing decision is recorded in docs/adr/0001-grill-me-ste-response-style.md. Do not paste the standard's rule text into the design doc; the design doc states our paraphrase and links the ADR.

Implementation Details

Keep every existing heading and the section order. Add a ### Response style subsection under ### Prompt Injection (or another position that reads best); do not drop or rename an existing section.
Rewrite the prose to the rule categories: split long sentences, prefer the active voice and simple tenses, remove -ing forms where a simple tense works, and keep the articles.
Leave byte-identical, as the code/identifier exemption: all fenced code blocks, the checkpoint Markdown template, tool names, parameter names, command forms, and the output-destination values.
### Response style must state:
- the ten rule categories (our paraphrase — the same list as above);
- the three exemptions: probing questions and their alternatives; code, file paths, identifiers, tool names, and commands; text quoted from the user;
- that the style is always on and best-effort, and is described as "STE style", never "STE compliant";
- that the approved-word dictionary is not included;
- the credit line and the link: Response style follows ASD-STE100 Simplified Technical English (Issue 9, January 2025), a copyright and trademark of ASD, Brussels. Rules paraphrased. See https://www.asd-ste100.org.
- a link to the ADR. From extensions/grillme/DESIGN.md, the relative path is ../../docs/adr/0001-grill-me-ste-response-style.md.
Cross-reference docs/GRILL_ME_STE_STYLE_PLAN.md only if a link is useful; do not restate the whole plan.

Acceptance Criteria

extensions/grillme/DESIGN.md prose follows the rule categories, and no section was dropped or renamed.
A ### Response style subsection lists the ten rule categories and the three exemptions.
It states the always-on rule and the best-effort status, and says "STE style", never "STE compliant".
It states that the approved-word dictionary is not included.
The credit line, the https://www.asd-ste100.org link, and a resolvable link to the ADR all appear.
Every fenced code block and every identifier is byte-identical to the previous file, and all fences are balanced.

Test Plan

Documentation review — no code to run.

grep -n "STE compliant" extensions/grillme/DESIGN.md

Expected: no output.

grep -n "asd-ste100.org\|0001-grill-me-ste-response-style" extensions/grillme/DESIGN.md

Expected: the standard link and the ADR path.

# the ADR link must resolve from the extension directory
ls extensions/grillme/../../docs/adr/0001-grill-me-ste-response-style.md

Expected: the file path prints.

# fences must stay balanced (even count of lines starting with ```)
grep -c '^```' extensions/grillme/DESIGN.md

Expected: an even number.

cd extensions/grillme && npm test

Expected: unaffected and green.

Manual read-through: confirm each claim in Response style matches ste-style.ts, and that no rewritten sentence exceeds 20 words as an instruction or 25 as a description.

## Summary Rewrite `extensions/grillme/DESIGN.md` best-effort to the STE rule categories, and add a "Response style" subsection that documents the rule categories, the best-effort status, the exemptions, and a link to the ADR. ## Background **Depends on:** #291, #294, #295 `#291` ships `ste-style.ts`; `#294` and `#295` rewrite the authored strings. Write against the **shipped** behaviour. `DESIGN.md` is the extension's design document. It currently covers Purpose, Core Principles, User Experience (Starting, Interaction, Commands for v1, Checkpoint), Output Model, Approval Before Mutations, Technical Design (Extension State, Prompt Injection, Tools, Read-only Enforcement), MVP Scope, and Known Limitations / Future Work. It contains fenced code blocks for the checkpoint Markdown template and the tool schemas. The rule categories are defined in `extensions/grillme/ste-style.ts` as `STE_RULE_CATEGORIES`: 1. Keep sentences short. Aim for about 20 words or fewer when you give an instruction. Aim for about 25 words or fewer when you describe something. 2. Put one idea in each sentence. 3. Use the active voice. 4. Use simple tenses: past, present, future, and the imperative. 5. Do not use an `-ing` verb form when a simple tense works. 6. Use one word for one meaning. Do not trade between synonyms. 7. Do not use a phrasal verb when one verb does the work. 8. Keep a group of nouns to three words or fewer. 9. Use short, common words. 10. Keep the articles (`a`, `an`, `the`). The licensing decision is recorded in `docs/adr/0001-grill-me-ste-response-style.md`. Do not paste the standard's rule text into the design doc; the design doc states our paraphrase and links the ADR. ## Implementation Details - Keep every existing heading and the section order. Add a `### Response style` subsection under `### Prompt Injection` (or another position that reads best); do not drop or rename an existing section. - Rewrite the prose to the rule categories: split long sentences, prefer the active voice and simple tenses, remove `-ing` forms where a simple tense works, and keep the articles. - Leave byte-identical, as the code/identifier exemption: all fenced code blocks, the checkpoint Markdown template, tool names, parameter names, command forms, and the output-destination values. - `### Response style` must state: - the ten rule categories (our paraphrase — the same list as above); - the three exemptions: probing questions and their alternatives; code, file paths, identifiers, tool names, and commands; text quoted from the user; - that the style is always on and best-effort, and is described as "STE style", never "STE compliant"; - that the approved-word dictionary is not included; - the credit line and the link: `Response style follows ASD-STE100 Simplified Technical English (Issue 9, January 2025), a copyright and trademark of ASD, Brussels. Rules paraphrased. See https://www.asd-ste100.org.` - a link to the ADR. From `extensions/grillme/DESIGN.md`, the relative path is `../../docs/adr/0001-grill-me-ste-response-style.md`. - Cross-reference `docs/GRILL_ME_STE_STYLE_PLAN.md` only if a link is useful; do not restate the whole plan. ## Acceptance Criteria - [ ] `extensions/grillme/DESIGN.md` prose follows the rule categories, and no section was dropped or renamed. - [ ] A `### Response style` subsection lists the ten rule categories and the three exemptions. - [ ] It states the always-on rule and the best-effort status, and says "STE style", never "STE compliant". - [ ] It states that the approved-word dictionary is not included. - [ ] The credit line, the `https://www.asd-ste100.org` link, and a resolvable link to the ADR all appear. - [ ] Every fenced code block and every identifier is byte-identical to the previous file, and all fences are balanced. ## Test Plan Documentation review — no code to run. ```bash grep -n "STE compliant" extensions/grillme/DESIGN.md ``` Expected: no output. ```bash grep -n "asd-ste100.org\|0001-grill-me-ste-response-style" extensions/grillme/DESIGN.md ``` Expected: the standard link and the ADR path. ```bash # the ADR link must resolve from the extension directory ls extensions/grillme/../../docs/adr/0001-grill-me-ste-response-style.md ``` Expected: the file path prints. ```bash # fences must stay balanced (even count of lines starting with ```) grep -c '^```' extensions/grillme/DESIGN.md ``` Expected: an even number. ```bash cd extensions/grillme && npm test ``` Expected: unaffected and green. Manual read-through: confirm each claim in `Response style` matches `ste-style.ts`, and that no rewritten sentence exceeds 20 words as an instruction or 25 as a description.

david added this to the Grill Me STE: M3 - Docs milestone

2026-10-09 21:20:29 +00:00

david added the

enhancement

label

2026-10-09 21:20:29 +00:00

david self-assigned this

2026-10-09 21:20:30 +00:00

david referenced this issue

2026-10-09 21:20:46 +00:00

Bump the grillme extension to 0.4.0 and add the changelog entry #298

david referenced this issue