/plain-language

Összefoglaló

Amelyik mondatot az érintett fél nem érti, abból nem tud dönteni. A /plain-language a technikai tartalmat következmény-elsőként írja újra — a pontos technikai részlet megmarad, zárójelbe kerül, ahol a helyén van. Semmi elhagyás, semmi leegyszerűsítés. Mindenki számára működik, aki dönteni kénytelen anélkül, hogy ismerné a kódot.

Mikor használd

Akkor használd a /plain-language-t, ha az olvasó termékfelelős, érintett vagy végfelhasználó, akinek döntenie kell, de nem ismeri a kódot vagy a technológiát. Két mód áll rendelkezésre:

• Magyarázó mód — van valami elmagyarázandó (egy hiba, egy fogalom, egy technikai döntés): add meg argumentumként, és azonnal újraírja.
• Konvenciós mód — nincs megadott téma: betölti az egyszerű-nyelv írási konvenciót a munkamenet hátralévő részére. Más skillek (pl. /options, /feature-refinement) automatikusan ebben a módban hívják meg.

Triggerkifejezések (a SKILL.md-ből):

• "explain this simply"
• "what does this error mean"
• "put this in plain language"
• "translate this for a stakeholder"
• "explain the tech so I can decide"

A konvenció: vezess a következménnyel, a mechanizmust tedd zárójelbe. A pontos technikai részletet soha nem hagyja el — csak áthelyezi oda, ahol a nem-szakértő olvasó kihagyhatja anélkül, hogy elveszítené a lényeget.

Meghívás

Add meg a magyarázandó tartalmat argumentumként, vagy tegyél fel kérdést:

/plain-language [technikai tartalom vagy témakör]

Argumentum nélkül a skill betölti az egyszerű-nyelv konvenciót a munkamenetre — az olyan skillek kimenete, mint az /options, automatikusan ezt a konvenciót fogja követni.

1. példa — Technikai mondat újraírása

/plain-language "Move dedup into the StabilityGate.advance() barrier so the manifest write stops racing the scan."

Szüntesse meg az alkalmi duplikált kimenetet, amely akkor jelenik meg,
ha egy fájlt gyorsan egymás után kétszer mentenek (mozgassa a deduplikálást
a StabilityGate.advance() barrier-be, hogy a manifest-írás ne versenyezzen
a vizsgálattal).

2. példa — Fogalom elmagyarázása nem-technikai olvasónak

/plain-language explain what a pre-commit hook does to our CTO

Egy szkript, amely automatikusan lefut minden egyes git-mentés előtt —
elkapja a bukó teszteket vagy a tiltott kódot, mielőtt a változás bekerülne
a közös repóba (a .git/hooks/pre-commit fájlban van definiálva, ezen a
projekten 2 másodpercen belül fut le).

Kapcsolódó eszközök

• /options — Belsőleg használja a /plain-language-t, amikor döntési lehetőségeket mutat be érintetteknek; hívd meg közvetlenül, ha strukturált döntést szeretnél egyszerű-nyelv keretezéssel.
• /feature-refinement — A /plain-language-t használja, hogy a brief olvasható maradjon nem-technikai termékfelelősök számára is.
• /documentation-standard — A dokumentum struktúráját kezeli; kombináld a /plain-language-vel és a /doc-voice-szal, hogy a hangnem és a struktúra egyszerre legyen rendben.