Rewrite extensions/grillme/README.md in STE style and add the Response style section #296

New issue

Closed

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

david commented

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

Owner

Summary

Rewrite extensions/grillme/README.md best-effort to the STE rule categories, and add a "Response style" section that states the always-on style, the three exemptions, and the credit and link.

Background

Depends on: #291, #294, #295

#291 ships ste-style.ts; #294 and #295 rewrite the authored strings in the extension. Write this README against the shipped behaviour, not the plan's intentions. If the implementation diverged anywhere (the block fence text, the exact exemptions, the credit wording), the README describes what the code does.

The README is the user-facing contract for the extension. Its current structure is:

# Pi Grill Me
## Install
## Commands
## Behavior
## Output selection options
## Permissions and mutating outputs
## Acknowledgements
## Testing
## License

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: the standard is free to download but not free to redistribute, so the rules are paraphrased, the standard is credited and linked, the approved-word dictionary is not included, and the extension never claims compliance. Do not paste the standard's rule text into the README.

Implementation Details

Keep the existing section order and heading levels. Add ## Response style after ## Behavior (or in the position that reads best); do not drop or rename an existing section.
Rewrite the prose in every section 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 these byte-identical, because they are the code/identifier exemption: all command forms and option names in ## Commands (/grill, /grill stop, /checkpoint, /grill status, /grill intent, /grill output, /grill research), the output-destination values in ## Output selection options, install commands, file paths, and every fenced code block's contents.
## Response style must state:
- the style is always on — no toggle, no setting;
- its scope: the extension's authored strings, and the assistant's replies and the checkpoint while a Grill Me session is active;
- 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 best-effort, and the file says "STE style", never "STE compliant";
- the credit line and the link, i.e. 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.
Keep the existing ## Acknowledgements entry and add the credit there too, or cross-reference the ## Response style section — the credit must appear in the README.

Acceptance Criteria

extensions/grillme/README.md prose follows the rule categories, and no section was dropped or renamed.
A ## Response style section exists and states the always-on rule, the scope, the three exemptions, and the best-effort status.
The README says "STE style" and never "STE compliant".
The credit line and the https://www.asd-ste100.org link both appear.
Every command form, output-destination value, install command, and code fence is byte-identical to the previous file.
No claim of certified compliance, and no text copied from the official standard.

Test Plan

Documentation review — no code to run.

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

Expected: no output.

grep -n "asd-ste100.org" extensions/grillme/README.md

Expected: the link, in the Response style section (and Acknowledgements if you repeated it).

grep -n "^## " extensions/grillme/README.md

Expected: the original sections plus Response style.

cd extensions/grillme && npm test

Expected: unaffected and green.

Manual read-through: confirm each claim in Response style can be traced to ste-style.ts or index.ts, and that no sentence in the rewritten prose exceeds 20 words as an instruction or 25 as a description.

## Summary Rewrite `extensions/grillme/README.md` best-effort to the STE rule categories, and add a "Response style" section that states the always-on style, the three exemptions, and the credit and link. ## Background **Depends on:** #291, #294, #295 `#291` ships `ste-style.ts`; `#294` and `#295` rewrite the authored strings in the extension. Write this README against the **shipped** behaviour, not the plan's intentions. If the implementation diverged anywhere (the block fence text, the exact exemptions, the credit wording), the README describes what the code does. The README is the user-facing contract for the extension. Its current structure is: 1. `# Pi Grill Me` 2. `## Install` 3. `## Commands` 4. `## Behavior` 5. `## Output selection options` 6. `## Permissions and mutating outputs` 7. `## Acknowledgements` 8. `## Testing` 9. `## License` 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`: the standard is free to download but not free to redistribute, so the rules are paraphrased, the standard is credited and linked, the approved-word dictionary is not included, and the extension never claims compliance. Do not paste the standard's rule text into the README. ## Implementation Details - Keep the existing section order and heading levels. Add `## Response style` after `## Behavior` (or in the position that reads best); do not drop or rename an existing section. - Rewrite the prose in every section 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 these byte-identical, because they are the code/identifier exemption: all command forms and option names in `## Commands` (`/grill`, `/grill stop`, `/checkpoint`, `/grill status`, `/grill intent`, `/grill output`, `/grill research`), the output-destination values in `## Output selection options`, install commands, file paths, and every fenced code block's contents. - `## Response style` must state: - the style is **always on** — no toggle, no setting; - its scope: the extension's authored strings, and the assistant's replies and the checkpoint while a Grill Me session is active; - 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 **best-effort**, and the file says "STE style", never "STE compliant"; - the credit line and the link, i.e. `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.` - Keep the existing `## Acknowledgements` entry and add the credit there too, or cross-reference the `## Response style` section — the credit must appear in the README. ## Acceptance Criteria - [ ] `extensions/grillme/README.md` prose follows the rule categories, and no section was dropped or renamed. - [ ] A `## Response style` section exists and states the always-on rule, the scope, the three exemptions, and the best-effort status. - [ ] The README says "STE style" and never "STE compliant". - [ ] The credit line and the `https://www.asd-ste100.org` link both appear. - [ ] Every command form, output-destination value, install command, and code fence is byte-identical to the previous file. - [ ] No claim of certified compliance, and no text copied from the official standard. ## Test Plan Documentation review — no code to run. ```bash grep -n "STE compliant" extensions/grillme/README.md ``` Expected: no output. ```bash grep -n "asd-ste100.org" extensions/grillme/README.md ``` Expected: the link, in the Response style section (and Acknowledgements if you repeated it). ```bash grep -n "^## " extensions/grillme/README.md ``` Expected: the original sections plus `Response style`. ```bash cd extensions/grillme && npm test ``` Expected: unaffected and green. Manual read-through: confirm each claim in `Response style` can be traced to `ste-style.ts` or `index.ts`, and that no sentence in the rewritten prose 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:19 +00:00

david added the

enhancement

label

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

david self-assigned this

2026-10-09 21:20:19 +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