Przejdź do treści
Biblioteka skilli
Zarządzanie i produkt · Pisanie

plain-language

/plain-language

Dba o zrozumiałe komunikaty poleceń planowania: przejście przez otwarte pytania, przekazanie planu, raport zakresu, prezentacja wyników weryfikacji i podsumowania postępu.

Repozytorium
fractional-cto ↗
Licencja
MIT
Ostatnia zmiana repozytorium
25.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Dba o zrozumiałe komunikaty poleceń planowania: przejście przez otwarte pytania, przekazanie planu, raport zakresu, prezentacja wyników weryfikacji i podsumowania postępu.

Oryginalny opis (EN)

This skill should be used whenever a planning-tools command prints something back to the user — the /plan-open-questions walkthrough, the /plan-master hand-off, the /plan-context scope report, the /plan-verify findings presentation, the /plan-progress chat summary, or any apply-gate summary. Single owner of two rules: (1) plain-language chat output, written for a reader who is skimming with low concentration; (2) the ID + name rule, which requires every external reference (ticket, ADR, PR) to carry its human name alongside its ID, everywhere including inside plan documents. Explicitly does NOT

Jak działa

  1. Two rules, two different scopes
  2. Rule 1 — Plain language (chat output only)
  3. Rule 2 — ID + name (everywhere, including plan documents)
  4. Single-owner note
Sekcje z nagłówków SKILL.md, w oryginale · 136 linii, 1 019 słów
Podgląd SKILL.md
---
name: plain-language
description: "This skill should be used whenever a planning-tools command prints something back to the user — the /plan-open-questions walkthrough, the /plan-master hand-off, the /plan-context scope report, the /plan-verify findings presentation, the /plan-progress chat summary, or any apply-gate summary. Single owner of two rules: (1) plain-language chat output, written for a reader who is skimming with low concentration; (2) the ID + name rule, which requires every external reference (ticket, ADR, PR) to carry its human name alongside its ID, everywhere including inside plan documents. Explicitly does NOT apply to the body of a master plan .md file (which stays detailed) or to progress entries posted to Linear / GitHub (which keep the dense style owned by progress-methodology)."
version: 0.1.0
---

# Plain Language

Planning documents are dense on purpose. **What gets printed into the conversation is not.**

This skill is the single owner of how `planning-tools` talks to the user. Every command references it; no command restates it.

## Two rules, two different scopes

| Rule | Applies to |
|---|---|
| **Plain language** | Chat output only — anything a `/plan-*` command prints into the conversation |
| **ID + name** | Everywhere — chat output *and* the body of plan documents |

---

## Rule 1 — Plain language (chat output only)

### Where it applies

Everything a `/plan-*` command prints into the conversation:

- The per-question blocks in `/planning-tools:plan-open-questions`
- The hand-off summary at the end of `/planning-tools:plan-master`
- The scope report from `/planning-tools:plan-context`
- The presentation of verifier findings in `/planning-tools:plan-verify`
- The chat summary around `/planning-tools:plan-progress`
- Every apply-gate summary and every `AskUserQuestion` option label and description

### Where it does NOT apply

- **The body of a master plan `.md` file.** Plans stay detailed, precise, and citation-heavy. `master-plan-methodology` owns that format. Do not shorten a plan to satisfy this skill.
- **Progress entries posted to Linear or GitHub.** These keep the dense-paragraph style owned by `progress-methodology`. Only the chat summary wrapped around them follows this skill.

### The writing rules

Assume the reader is skimming with low concentration. They will read the first sentence of each block and stop if it does not land.

1. **One idea per sentence.** If a sentence has an "and" joining two ideas, split it.
2. **Short sentences.** Aim for under 20 words. A long sentence is a rewrite, not a style choice.
3. **Everyday words over jargon.** Say "runs first" not "is evaluated eagerly". Say "we cannot tell yet" not "the verdict is indeterminate".
4. **Expand an acronym the first time it appears in a block.** Not once per document — once per block, because the reader may only read that block.
5. **Lead with the point, then the detail.** The first sentence answers the question. The rest supports it.
6. **No nested clauses, no stacked qualifiers.** Strip "generally", "typically", "in most cases" unless the exception is real and named.
7. **Each block stands alone.** A reader who skipped the block above must still understand this one.
8. **Concrete over abstract.** Name the file, the phase, the ticket, the person. "The auth helper" is worse than "`_shared/auth.ts`".

### Good / bad

**Bad** — one long sentence, three ideas, jargon, no anchor:

> Given that the existing discriminator is effectively the bare HTTP status, which conflates auth-gate failures with upstream-relayed rejections, resolving this question determines whether downstream consumers can reliably differentiate genuine session expiry, which in turn gates the modal-vs-toast decision.

**Good** — short sentences, one idea each, concrete:

> Right now we only look at the HTTP status code. That means a real session expiry and an upstream error look identical. Until we can tell them apart, the app cannot decide whether to show the modal or a toast.

---

**Bad** — hedged and abstract:

> This may potentially impact a number of components, generally in the frontend layer, and could conceivably require some follow-up work.

**Good** — names the thing, states the cost:

> This changes two files: `src/features/session/modal.tsx` and `src/lib/session-errors.ts`. Phase 4 has to be rewritten if we pick option 2.

---

**Bad** — a wall with no entry point:

> Resolved 4 open questions in context/tickets/CI-21-PLAN.md, 2 remain, of which 1 was deferred and 1 was added during the walkthrough, and the Resolved Questions section now contains 9 entries total.

**Good** — the point first, the detail after:

> Answered 4 questions. 2 are still open — Q3 (deferred) and Q7 (new).
> Written to `context/tickets/CI-21-PLAN.md`.

---

## Rule 2 — ID + name (everywhere, including plan documents)

Every external reference carries its **ID and its human name** on first mention in a block. An ID alone forces the reader to go look it up. That is exactly the cost this rule removes.

### Formats

| Reference type | Shape | Example |
|---|---|---|
| Ticket (Linear, Jira, GitHub issue) | `<ID> — <title>` | `CI-21 — Add keyboard navigation` |
| ADR | `ADR-<NN>: <title>` | `ADR-28: Session error taxonomy` |
| Pull request | `PR #<N> — <title>` | `PR #412 — Fix locale fallback` |
| Phase inside a plan | `Phase <N> — <phase name>` | `Phase 3 — Wire MutationCache.onError` |

Markdown links keep the same content: `[CI-21 — Add keyboard navigation](../CI-21-PLAN.md)`.

### When the name is not available

**Never emit a bare ID silently.** If the title cannot be fetched — the Linear MCP is not loaded, `gh` is unavailable, the ticket is in another workspace — say so:

```
CI-21 — (title unavailable)
```

The reader then knows the name is missing, rather than assuming there never was one.

### First mention per block

The rule is per block, not per document. A reader who jumps straight to Phase 5 must still see the name there. Repeating `CI-21 — Add keyboard navigation` in three different sections is correct, not redundant.

### Good / bad

- ❌ `Depends on: CI-22`
- ✅ `Depends on: CI-22 — Salesforce link helpers (`src/features/cases/lib/sf-links.ts`, i18n key, ADR-28: Session error taxonomy amendment)`

- ❌ `Blocked by ADR-15 and ADR-34.`
- ✅ `Blocked by ADR-15: Edge function boundaries and ADR-34: Locale fallback order.`

- ❌ `Ships in #412.`
- ✅ `Ships in PR #412 — Fix locale fallback.`

### Where it is checked

`/planning-tools:plan-verify` audits plan documents for this rule. A reference with no human name is a **Suggestion** — never Important, never Critical. It never blocks a PASS verdict. See `planning-tools:plan-verification-checklist` dimension 13.

Chat output is not audited. Follow the rule anyway.

---

## Single-owner note

Other skills and commands **reference** this skill; they do not restate its rules.

- `planning-tools:master-plan-methodology` points here for reference naming, and keeps full ownership of the plan document format.
- `planning-tools:plan-verification-checklist` points here for the definition of the rule it audits.
- `planning-tools:progress-methodology` keeps full ownership of the dense progress-entry style. This skill does not override it.

Wersje

RepozytoriumWynikLicencja
Ta strona · oborchers/fractional-cto100MIT
zts212653/clowder-ai100MIT
scratchpad-sh/skills100MIT
pandysp/claude-plugins100MIT
slogsdon/skills-writing100MIT
thedaviddias/front-end-checklist100MIT
mgifford/accessibility-skills100AGPL-3.0
surendranb/writing-skills100MIT
stefan-jansen/claude-code-toolkit100MIT

Migawka bazy z 13.11.2026 · wersja paczki 7a3a83b3113f (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 87using-planning-tools
    Obsługuje komendy /plan-* do plików planów: kontekst, plan główny, otwarte pytania, weryfikację i postęp.
  • 100stakeholder-summary
    Tworzy zrozumiałe dla nietechnicznych interesariuszy podsumowanie na podstawie istniejącej specyfikacji funkcji, przed rozpoczęciem implementacji.
  • 86plan-progress
    Podaje opis pasków postępu planu i poleceń /progress, gdy użytkownik pyta o paski lub odmowę wywołania.
  • 87master-plan-methodology
    Pomaga pisać i przeglądać wieloetapowe plany główne według metody wtyczki planning-tools, z numeracją faz i sekcją pytań otwartych.
  • 100qstack-ask-plan-open-questions
    Rozstrzyga istotne otwarte pytania w planie QStack przez jednopytaniowe dialogi decyzyjne w prostym języku i od razu wpisuje odpowiedzi i konsekwencje do planu.
  • 86progress-report
    Raportuje postęp względem planu prostym językiem: czy jest na czas, co gotowe, co trwa, co zablokowane i co dalej.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.