The four existing skills cover the product; nothing covered how work is reported. Two rules this project has paid for — check the artifact rather than the report, and do not state a claim more firmly than the evidence allows — lived only in the operator's head and in chat, where Claude Code never read them. - felhom-evidence five confidence tiers, artifact-over-report - felhom-diagnosis no hypothesis until a command has been seen red - felhom-plain-language ASD-STE100, two options, the re-pitch - felhom-handoff the note goes to a FILE, not the conversation - felhom-doc-authoring the pointer decides whether material is reached scripts/check_skills.py asserts what decides whether a skill is EVER reached: frontmatter parses, name == directory, description and body non-empty, under 150 lines, installed copy still samefile()s into the repo. install_skills.py globs and never reads the file, so a missing description installs perfectly and then silently never loads. It convicted on its first run: felhom-build-deploy is 179 lines. NOT trimmed here (pre-existing skills are out of scope, and trimming a deploy skill without exercising its commands is how a wrong command reaches a live host) — a named single-entry GRANDFATHERED exception, WARNed every run, R-394. A new skill over the limit is convicted. Red-proof run and seen failing: description removed from felhom-evidence -> exit 1, "frontmatter field 'description' is missing or empty". Restored, tree clean. skills/SOURCES.md records both MIT upstreams, that these are adaptations not copies, and the six pieces deliberately EXCLUDED with reasons. Register: R-392 (no architecture doc covers the two-AI workflow), R-393 (decision-log skill deferred, with the reason), R-394.
This commit is contained in:
@@ -0,0 +1,55 @@
|
||||
---
|
||||
name: felhom-plain-language
|
||||
description: How to write anything the Felhom operator reads. Triggers - writing the "For the operator" page of a task file; writing an operator-facing section of REPORT.md; writing customer-facing or operator-facing UI copy; and the phrases "wait, what", "re-pitch that", "I don't follow", "in plain language", "explain it simply". Contains the ASD-STE100 rules, the two-option decision format, and the re-pitch procedure.
|
||||
---
|
||||
|
||||
# Plain language
|
||||
|
||||
The operator reads this at the end of a long day. Write for that reader, not for the reader who has
|
||||
the whole system in their head.
|
||||
|
||||
## The rules
|
||||
|
||||
- **ASD-STE100 Simplified Technical English** — a controlled writing standard: a restricted set of
|
||||
approved plain words, active voice, one instruction or idea per sentence. Explain any term like
|
||||
that in the sentence that introduces it, as this line does.
|
||||
- **Short sentences. Short paragraphs. Small words.** If a big word is unavoidable, define it right
|
||||
after, in the same sentence.
|
||||
- **Open with what happened, what it means, and what the operator has to do.** That order. The
|
||||
detail comes after, or not at all.
|
||||
- **No file paths, no function names, no register numbers as the subject of a sentence.** No version
|
||||
numbers except ones the operator acts on. Those belong in the body of a report, not in a sentence
|
||||
that is trying to say what is going on.
|
||||
- **Describe the observable symptom, not the code defect.** *"Your Stop is silently undone on a
|
||||
reboot"* — not the name of the function that undoes it. The operator experiences the symptom; only
|
||||
the fixer needs the function.
|
||||
- **A decision gets at most two options.** Each one carries: what it costs, **what happens if the
|
||||
operator does nothing**, and which one you would pick and why. Never a bare question with no
|
||||
recommendation — a question with no recommendation moves the work back onto the tired person.
|
||||
- **A recommendation that is not followed gets one line saying why.** Silence reads as agreement,
|
||||
and the disagreement is then lost. This is standing rule 4 in
|
||||
`documentation/runbooks/workspace-CLAUDE.md`.
|
||||
- **Language:** customer-facing strings are Hungarian; operator and hub surfaces are English.
|
||||
Minimal emoji — and none at all in product UI, which **`felhom-ui-design`** enforces with a gate.
|
||||
|
||||
## What to cut
|
||||
|
||||
Empty openers (*"Great question"*, *"Let me explain"*), promotional adjectives, hedge stacks
|
||||
(*"it might possibly be somewhat"*), and any sentence that only announces the next sentence. If
|
||||
deleting a sentence loses no information, it was not a sentence.
|
||||
|
||||
## The re-pitch
|
||||
|
||||
When the operator fires one of the triggers — *"wait, what"*, *"re-pitch that"*, *"I don't
|
||||
follow"* — the last message did not land. That is the only fact you have.
|
||||
|
||||
Rewrite it from the top under these rules, **shorter**.
|
||||
|
||||
Do not defend the original. Do not add detail to clarify it — detail is usually what broke it. Do
|
||||
not ask which part was unclear; that spends the operator's attention to save your own effort. Write
|
||||
the whole thing again, smaller.
|
||||
|
||||
## What this skill is not
|
||||
|
||||
It is not a style guide for the product's visual surfaces. Palette, badges, status vocabulary and
|
||||
the Hungarian copy maps belong to **`felhom-ui-design`**.
|
||||
Reference in New Issue
Block a user