skills: five process-domain skills + check_skills.py
gates / gates (push) Failing after 15s

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:
2026-08-25 09:36:20 +02:00
parent ebdc04601d
commit c30430c530
12 changed files with 826 additions and 243 deletions
+55
View File
@@ -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`**.