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

writing-design-docs

/writing-design-docs

Pisze propozycję, RFC lub dokument projektowy, który uzasadnia zmianę, z ramą decyzji i listą kompletności.

Licencja
MIT
Ostatnia zmiana repozytorium
13.09.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 13.09.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

Pisze propozycję, RFC lub dokument projektowy, który uzasadnia zmianę, z ramą decyzji i listą kompletności.

Wyzwalacze z opisu

write up the approach
Oryginalny opis (EN)

Use when writing a proposal, RFC, design document, spec, or migration plan - anything that argues for a change, records a design, or asks readers for input on one. Encodes the proposal skeleton, the Why & What decision box, and the completeness checks. Use whenever a change needs arguing or scoping in writing, even if the user just says "write up the approach".

Jak działa

  1. Overview
  2. When to invoke, and not
  3. Skeleton
  4. Structure rules
  5. The Why & What box
  6. Tone
  7. Completeness check
Sekcje z nagłówków SKILL.md, w oryginale · 102 linii, 875 słów
Podgląd SKILL.md
---
name: writing-design-docs
description: Use when writing a proposal, RFC, design document, spec, or migration plan - anything that argues for a change, records a design, or asks readers for input on one. Encodes the proposal skeleton, the Why & What decision box, and the completeness checks. Use whenever a change needs arguing or scoping in writing, even if the user just says "write up the approach".
---

# Writing design docs

**REQUIRED BACKGROUND:** the `technical-writing` skill (read-first, hard rules, truth rules, style).

## Overview

A design document is a proposal made discussable: conclusion first, every non-trivial choice in a Why & What box, costs named next to benefits, and fact separated from proposal.

## When to invoke, and not

Invoke for anything that argues for a change or records a design: proposals, RFCs, design docs, specs, migration plans, "should we" documents. Do NOT invoke for recording an already-taken decision (`recording-decisions`), for procedures (`writing-runbooks`), or for status reports.

Under pressure: a proposal persuades with its numbers and its named costs, and the register rules hold whatever the deadline (the `technical-writing` rule; "punchy" is not an override). When supplied facts arrive without sources, mark them `**[source wanted: ...]**` and keep writing (see `references/truth.md` in the `technical-writing` skill); never invent a citation and never silently drop the fact.

## Skeleton

```markdown
# Title: what the document does

**Subtitle pinning the scope in one sentence**

|                |                                            |
| -------------- | ------------------------------------------ |
| **Status**     | Draft / Request for comments               |
| **Owner**      | [team or role]                             |
| **Scope**      | [explicit, including what falls outside]   |
| **Related**    | [links to sibling documents]               |
| **Audience**   | [who must read this]                       |

---

## 1. Summary
[The conclusion immediately. Not the occasion, not the method.]

## 2. [Context / what was analyzed]
## 3. [The analysis, split per question]
## n. Open questions
## n+1. Benefits and costs
[Both. Benefits alone reads as a sales pitch.]
## n+2. Residual risks and what not to do
[Only when the design hands work to other teams.]

---

*Closing line: which parts are fact and which are proposal, and where input is wanted.*
```

## Structure rules

- **Number chapters** and cite them as `ch. 7.1`.
- **Goals and non-goals both.** The non-goals (or "explicitly not changed") section states what stays unchanged.
- **Definitions before behavior** when a term is ambiguous: pin "responded", "eligible", "stale" before using them.
- **A grounding section** pins the facts the design rests on: a fact/source table, checked against a named commit. Separate verified facts from what will be built.
- **Appendices** take letters (Appendix A, B) and hold what would bury the main text: config examples, glossaries, inventories.
- **A fact lives in one place.** Link to it; never repeat it, not even across documents in the same repo.
- **Mark unfinished parts** with `**[DRAFT - input wanted]**` instead of omitting them.
- **Open questions get owners**: a name, a role, or an explicit "to be filled by".
- **Residual risks and what NOT to do** close the document when the design ships work to others.
- **No line budget**, but length from repetition or emphasis goes; past roughly 800 lines, split and let the main document link to the parts.

## The Why & What box

Every non-trivial choice gets one; readers react to the box, not to the conclusion.

```markdown
> **Why & What - [the choice in four words]**
>
> **What:** [the choice, one sentence, no justification]
>
> **Why:** [the reasoning. Also name what the choice does NOT solve.]
>
> **Alternatives considered:**
> - *[Alternative]:* [its strongest argument, and why it still lost]
>
> **Fallback:** [what survives if this does not work]
```

- An alternative dismissed without its strongest argument is a strawman. Name that argument.
- Admitting what the choice does not solve makes the document more credible.
- No box for choices nobody would contest; that is noise.
- An alternative that appears nowhere else in the document does not belong in the box: the reader would never consider it. One such rejection can be justified; several short ones in a row mean the box is padded.

## Tone

- The document stays a proposal: "we propose" and "whether that convinces is up to you", not "this becomes the way of working". It sets the direction and leaves the detailed choices open.
- Name what it costs. The benefits chapter ends with the price: what gets harder, what people must unlearn, which freedom disappears.
- No superlatives, no promise language. Concrete figures and verifiable statements.
- The expected outcome may be negative; say so up front: "the expected outcome is that the current queue beats the proposed rewrite; that is a useful result."

## Completeness check

Before handing a spec or plan to a reviewer or executor, check the five vagueness defects:

1. Unresolved placeholders: any literal TBD, TODO, "fill in later", or clearly incomplete sentence (a marked `**[DRAFT - input wanted]**` block is deliberate; an unmarked gap is a defect).
2. Missing acceptance criteria: a requirement with no concrete, independently testable success condition.
3. Undefined references: a type, endpoint, component, or table mentioned but defined nowhere.
4. No verifiable output: a task producing nothing a reviewer could inspect (no file path, no command, no observable behavior).
5. What without how: an outcome with no implementable direction ("handle errors appropriately" with no definition of appropriate).

For execution plans, add per task: goal, exact files, the change shown, tests with concrete scenarios, and the verify command. Explain any confusing leftover (an odd directory name, a legacy alias) rather than leaving it puzzling.

Wersje

W bazie nie ma innych skilli o nazwie writing-design-docs.

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

Pobrania w ostatnich 30 dniach: 2 · ranking

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

Podobne skille

  • 100rfc
    Pisze krótki RFC projektu: dopytuje o problem, cele, ograniczenia i opcje, czyta kod i zapisuje dokument Markdown w folderze RFC.
  • 90octocode-rfc-generator
    Pisze RFC, dokument projektowy lub plan migracji przed ważną zmianą, z porównaniem opcji i mierzalnym kontraktem wdrożenia.
  • 100writing-rfc
    Pisze RFC lub dokument projektowy z podsumowaniem na początku, celami, poza zakresem, alternatywami i otwartymi pytaniami.
  • 100mip
    Pisze lub poprawia propozycję usprawnienia (MIP), numerowany dokument projektowy dla zmiany funkcji, integracji lub architektury.
  • 100cowrite-doc
    Pisze dokument razem z użytkownikiem: najpierw kontekst, potem sekcje, na końcu test świeżego czytelnika, na przykład RFC lub dokument projektowy.
  • 100grilling-plans
    Testuje istniejący plan, RFC, projekt lub propozycję, przedstawiając w jednej partii pytania decyzyjne poparte dowodami i prowadząc rejestr decyzji.

Uwagi i zgłoszenia

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