# Polish: patterns that make a draft sound generated

Read this when the draft is in Polish. It lists wording that machine-written and
machine-translated Polish overuses, with plainer alternatives, and the checks that
matter in Polish specifically. Facts, numbers, commands, and quotations follow the
same rules as in `SKILL.md`; nothing here permits changing them.

## Stock openers and fillers

Use these as context-dependent editing suggestions, not banned phrases. Keep wording
that carries emphasis, uncertainty, scope, or an intentional register. Replace a
phrase only when the replacement preserves the same claim.

| Overused | Usually better |
| --- | --- |
| Z ogromną / wielką przyjemnością informujemy, że… | Say what happened: „Dodaliśmy…”, „Od dziś…” |
| Mamy zaszczyt ogłosić… | same |
| Warto zauważyć, że… / Należy podkreślić, że… | Delete; state the point |
| W dzisiejszych czasach… / W dzisiejszym dynamicznym świecie… | Delete |
| Nie da się ukryć, że… / Nie ulega wątpliwości, że… | Remove only when it adds no meaningful certainty or emphasis |
| W kontekście… / W ramach… (when it adds nothing) | „w”, „przy”, „podczas” |
| kluczowy, innowacyjny, przełomowy, kompleksowy, zaawansowany | Name the concrete property, or delete |
| umożliwia / pozwala na (as a reflex) | Prefer „pozwala podejrzeć”; do not turn a capability into an action already performed |
| w celu + noun | „aby” + verb, or „żeby” |
| dokonać + noun (dokonać instalacji, dokonać zmiany) | The verb: „zainstalować”, „zmienić” |
| posiadać (for things) | „mieć” |
| szereg, wiele różnych, cały wachlarz | Keep the quantity; use a specific number only if supplied by the source |
| Podsumowując, … (at the end of a short text) | Delete |
| Mam nadzieję, że ten artykuł okazał się pomocny. | Delete |

## Calques from English

Machine translation leaves English structure in place. Typical signs:

- **Passive where Polish uses an impersonal or active form.** „Plik został
  zapisany przez program” → „Program zapisał plik” or „Plik zapisano”.
- **„jest w stanie”** for every *can* → „może”, when this preserves capability; do not turn ability into completion.
- **Overused „że”-clauses after reporting verbs.** „Testy pokazują, że wynik jest
  lepszy” is fine; repeated clauses may need restructuring for readability, but are not evidence of AI authorship.
- **Capitalized common nouns** copied from English titles or UI: „Ustawienia
  Użytkownika” → „ustawienia użytkownika” unless it is the exact label of a button.
- **Sentence-initial „Także,” or „Dodatkowo,”** as connectors → join the sentences or
  drop the connector.
- **„Wspierać” for *support* in the sense of *handle*** → „obsługiwać” („obsługuje
  Windows”), keep „wspierać” for backing a cause or a person.
- **„Aplikować”** for *apply* → „stosować”, „zastosować”; „aplikować” is for job
  applications.
- **„Adresować problem”** → „zająć się problemem”; use „rozwiązać” only if the source promises a solution.
- **„Domyślnie” placed like English *by default*** at sentence end → usually earlier:
  „Domyślnie tryb jest wyłączony”.
- **Decimal points and thousands separators.** Polish prose uses a decimal comma
  („2,5 MB”) but code, versions, and flags keep their exact form (`2.5`, `v1.2.0`).
  Do not convert numbers inside code spans or commands.

## Register and address

- Choose one form of address and keep it: „Ty” (lowercase in running text unless the
  project capitalizes it), „Państwo”, or impersonal („można”, „należy”). Mixing them
  in one paragraph reads as generated.
- Avoid inventing a gender for the author or reader. Impersonal forms („zrobiono”,
  „można zapisać”) can avoid guessing gender. Keep the source narrator and number: do not introduce
  „my” or a team by changing a singular statement to „sprawdziliśmy”.
  If the source already uses a gendered past tense, keep it.
- Diminutives („pliczek”, „opcyjka”) and forced jokes are not what makes a text
  human. Concrete verbs and normal sentence length do.
- Keep English technical terms the project already uses („commit”, „pull request”,
  „deploy”) and inflect them the way the project does. Do not translate a term the
  glossary keeps in English.

## Checks that are specific to Polish

- **Negation words to keep:** nie, nigdy, bez, żaden/żadna/żadne, ani, nikt, nic.
  A dropped „nie” reverses the claim. Double negation („nie ma nic”) is correct
  Polish and must stay.
- **Hedges to keep:** może, mogą, prawdopodobnie, chyba, około, wstępnie, tylko,
  jeszcze, na razie, w tym teście. „Nie sprawdziliśmy jeszcze” and „nie sprawdziliśmy”
  are different claims.
- **Aspect carries meaning.** „Zapisywał” (was saving) and „zapisał” (saved) differ;
  do not switch aspect to make a sentence shorter.
- **Diacritics must survive** in prose (ż, ó, ł, ą, ę, ś, ć, ń, ź) and must not be
  added to identifiers, flags, or code.
- **Quotation marks:** Polish prose uses „…” ; keep the source's marks inside
  quotations and code exactly.
- `scripts/check_facts.py` counts a fixed subset of Polish negation and hedge words,
  including „nie” and „jeszcze”. Phrases such as „na razie” and „w tym teście”
  still need manual comparison. It does not check aspect, case, or diacritics.

## Worked examples

**Release note**

Source: „Z ogromną przyjemnością informujemy, że w ramach naszych ciągłych starań o
najwyższą jakość dokonaliśmy implementacji innowacyjnego mechanizmu, który umożliwia
użytkownikom podgląd zmian przed ich zapisaniem. Warto zauważyć, że funkcja ta jest
obecnie w fazie testów i może nie działać na systemie Windows.”

One suitable edit: „Można teraz podejrzeć zmiany przed ich zapisaniem. Funkcja jest w
fazie testów i może nie działać w Windows.”

Acceptance: the preview behavior, the testing status, and „może nie działać” survive.
No claim about quality, effort, or users is added. `check_facts.py` reports no
dropped negation or hedge.

**Maintainer reply**

Source: „Dziękujemy za zgłoszenie! Nie da się ukryć, że jest to bardzo istotny
problem. Aby móc dokonać jego analizy, uprzejmie prosimy o dostarczenie informacji
dotyczących wersji systemu operacyjnego oraz wersji Pythona, a także pełnego
polecenia, które zostało wykonane.”

One suitable edit: „Dzięki za zgłoszenie. To istotny problem. Żeby go sprawdzić,
potrzebujemy wersji systemu i Pythona oraz pełnego uruchomionego polecenia.”

Acceptance: all three requested items remain; the reply does not claim the bug was
reproduced. `check_facts.py` reports one dropped „nie”: it belonged to the filler „Nie
da się ukryć”. In this edit the assessment „istotny problem” remains, and removing
the rhetorical opener is an intentional reduction of emphasis. Explain that choice
rather than silently reverting or declaring that the phrase never carries meaning.
The reply does not guess the reporter's gender.

These are authored examples, not recorded client evaluations. A fluent reader should
review edits before they are published.

#!/usr/bin/env python3
"""List evidence that changed between a draft and its same-language rewrite.

Compares code, URLs, long option names and attached non-numeric values, placeholders,
numbers (including attached units such as 6 MB or 15s) and quotations, and counts
negation and hedge words in English and Polish.
It cannot judge meaning: a clean result only says these tokens survived. Standard
library only; Python 3.9+.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from collections import Counter
from pathlib import Path

FENCED = re.compile(r"```.*?```|~~~.*?~~~", re.S)
INLINE = re.compile(r"`[^`\n]+`")
URL = re.compile(r"https?://[^\s<>()\[\]\"']+")
PLACEHOLDER = re.compile(
    r"\{\{[^{}\n]+\}\}|\{[\w.:-]+\}|%\(\w+\)[sdifr]|%[sdif]|\$\{\w+\}|\$[A-Z_][A-Z0-9_]*"
)
QUOTE = re.compile(r'"([^"\n]+)"|“([^”\n]+)”|„([^”“\n]+)[”“]|«([^»\n]+)»')
UNITS = (
    "characters character seconds second minutes minute hours hour weeks week "
    "days day bytes byte bajtów bajty bajt sekundy sekundę sekund minuty minut "
    "godziny godzin tygodnie tygodni tydzień znaków znaki znak dnia dzień dni "
    "KiB MiB GiB TiB PiB KB MB GB TB PB kB secs sec mins min hrs hr godz sek "
    "ms ns µs μs us s h"
)
NUMBER = re.compile(
    r"(?<![\w.])[-+]?(?:\d+(?:[.,]\d+)*|[.,]\d+)(?:[eE][-+]?\d+)?%?"
    r"(?:[\s-]*(?:" + "|".join(sorted(UNITS.split(), key=len, reverse=True)) + r")\b)?"
)
FLAG = re.compile(r"(?<![\w/-])--[A-Za-z][A-Za-z0-9_-]*(?![\w-])")
ASSIGNED = re.compile(r"(?<![\w/-])(--[A-Za-z][A-Za-z0-9_-]*)=([^\s<>()\[\]\"']+)")
WORDS = {
    "negation": (
        "not no never none nobody nothing neither nor without cannot can't don't doesn't "
        "didn't isn't aren't wasn't weren't won't hasn't haven't hadn't shouldn't wouldn't "
        "nie nigdy bez żaden żadna żadne żadnych ani nikt nic"
    ),
    "hedge": (
        "may might could likely unlikely possibly probably perhaps approximately roughly "
        "estimated preliminary only yet "
        "może mogą prawdopodobnie chyba około szacunkowo wstępnie tylko jeszcze"
    ),
}


def evidence(text: str) -> dict[str, Counter]:
    found = {}
    for kind, pattern in (("code", FENCED), ("code", INLINE), ("url", URL)):
        matches = pattern.findall(text)
        found.setdefault(kind, Counter()).update(m.rstrip(".,;:!?") for m in matches)
        text = pattern.sub(" ", text)
    found["placeholder"] = Counter(PLACEHOLDER.findall(text))
    text = PLACEHOLDER.sub(" ", text)
    found["quotation"] = Counter(next(part for part in m if part) for m in QUOTE.findall(text))
    flags: Counter[str] = Counter()

    def take_assigned(match: re.Match[str]) -> str:
        name, value = match.group(1), match.group(2).rstrip(".,;:!?")
        if not value:
            return match.group(0)
        if NUMBER.fullmatch(value):
            flags[name] += 1
            return f" {value} "
        flags[f"{name}={value}"] += 1
        return " "

    text = ASSIGNED.sub(take_assigned, text)
    flags.update(FLAG.findall(text))
    found["flag"] = flags
    text = FLAG.sub(" ", text)
    found["number"] = Counter(NUMBER.findall(text))
    lowered = text.lower().replace("’", "'")
    for kind, words in WORDS.items():
        counts = Counter()
        for word in words.split():
            hits = len(re.findall(rf"(?<![\w']){re.escape(word)}(?![\w'])", lowered))
            if hits:
                counts[word] = hits
        found[kind] = counts
    return found


def compare(source: str, rewrite: str) -> list[dict]:
    before, after = evidence(source), evidence(rewrite)
    differences = []
    for kind in ("code", "url", "placeholder", "quotation", "flag", "number", "negation", "hedge"):
        for value in sorted(set(before[kind]) | set(after[kind])):
            old, new = before[kind][value], after[kind][value]
            if old != new:
                change = "dropped" if new < old else "added"
                differences.append(
                    {"kind": kind, "value": value, "change": change, "source": old, "rewrite": new}
                )
    return differences


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("source", type=Path, help="original draft")
    parser.add_argument("rewrite", type=Path, help="edited version in the same language")
    parser.add_argument("--json", action="store_true", help="print a JSON report")
    args = parser.parse_args(argv)
    try:
        source = args.source.read_text(encoding="utf-8")
        rewrite = args.rewrite.read_text(encoding="utf-8")
    except (OSError, UnicodeError) as exc:
        print(f"check_facts: {exc}", file=sys.stderr)
        return 2
    differences = compare(source, rewrite)
    if args.json:
        status = "review" if differences else "preserved"
        print(json.dumps({"status": status, "differences": differences}, ensure_ascii=False))
    elif differences:
        print(f"Review {len(differences)} change(s); restore each one or explain why it is safe:")
        for item in differences:
            print(
                f"- {item['kind']} {item['change']}: {item['value']!r} "
                f"({item['source']} -> {item['rewrite']})"
            )
    else:
        print(
            "Tracked code, URLs, placeholders, quotations, flags, numbers, negations and hedges match."
        )
        print("This does not check meaning, emphasis or attribution.")
    return 1 if differences else 0


if __name__ == "__main__":
    raise SystemExit(main())