admin
c30430c530
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.
3.2 KiB
3.2 KiB
name, description
| name | description |
|---|---|
| felhom-plain-language | 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-designenforces 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.