diff --git a/CHECKSUMS.txt b/CHECKSUMS.txt index b36e1c4..bfa1ed9 100644 --- a/CHECKSUMS.txt +++ b/CHECKSUMS.txt @@ -2,16 +2,16 @@ c58492dd01b64460c5c9de4d2eb07e53590a688a97edf6ff7161c48542e9f652 *audit-prompts/ b3377cca11bf9f30bae20021e099b6f903fa6a1d2db341394ba5341ee8cd430e *audit-prompts/ai-llm-audit-master-prompt.md e7231652a9b68dd7c2f2a300eeaa9967f049206eb99afb2d0203f90ae4f7dab0 *audit-prompts/api-audit-master-prompt.md 4e2315a6a0dcbc74b7eb115ee8234f2c1d52793f885347e5f6a24af99d51846f *audit-prompts/compliance-privacy-audit-master-prompt.md -cbb755bfbcbf6d10b19bf1e4d4e95aefbb6b7d417d0549f5ef241dd3623eb88c *audit-prompts/content-audit-master-prompt.md +ec8a4645bfca5686a0d4a024aef06f43b020bc2df5b41bbf0ef5bd57338e7540 *audit-prompts/content-audit-master-prompt.md 1d57a6b77e041844191e924d1c0c2e97db0437ce409fa3b1d5f661b9fe129d85 *audit-prompts/data-audit-master-prompt.md afaad3168640d047af7082f93721ff6169f8c67ee0937f2a7a785fad21a0a798 *audit-prompts/documentation-audit-master-prompt.md 1c163b9bb26d4a8d56a60d4a3155f8719e735557c0830735b15709683de18380 *audit-prompts/frontend-audit-master-prompt.md 022cb41b8056e7c80bd23b1156302f6e138ebf497b3e027efac1e15b08936b96 *audit-prompts/full-audit-master-prompt.md 26ae6a7f36ee3cd7e44539238ab833026a585b38884c3334ab785c19e35ce440 *audit-prompts/infrastructure-audit-master-prompt.md -9322253707945af22ebb32104bb4657dff584869a23798091985f0226e336e58 *audit-prompts/lean-audit-master-prompt.md +cbb443387e4ecfc2425925af8c67552721fdec23207c4d47483792b2117f6670 *audit-prompts/lean-audit-master-prompt.md eade468bffad5ee4143e0461502ccc8c607846fb4861c6b672b2a0af52031d4f *audit-prompts/performance-audit-master-prompt.md ddee61e41e75d4b6d4a23d114f58eb5d1be7e13f29bbcf6ad37184076b14f872 *audit-prompts/repo-audit-master-prompt.md 435e1661ad34a4398d41715763c243cd4c76d9efb4d01b933f05768dca4ccc73 *audit-prompts/security-audit-master-prompt.md -6bcc77a3a95524cb58a189042ee579cd1172cc44ccc4fd1b7961387bfd899626 *ISSUE-OUTPUT-STANDARD.md +25417e9a606aeff7698e460f52befde8bcd725dc4449ef95458959d61dbc66c7 *ISSUE-OUTPUT-STANDARD.md d5c630f94295b56fb451a53836c69f5815e5096f4a694347a40c1f09543afb78 *DOCUMENTATION-STANDARD.en.md -65463676dc3f20c23b4d1be66528f03753b50c632ef2e79a16bd9333f92d92f0 *DOCUMENTATION-STANDARD.md +73df04e730805068521bda76f3f8542cf6832cd60461f64033e000f40f07b472 *DOCUMENTATION-STANDARD.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1273376..5ca49f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,7 @@ Every Markdown file follows the [`DOCUMENTATION-STANDARD.md`](DOCUMENTATION-STAN - Second person, present tense, active voice; short sentences; parallel lists. - Notes as GitHub alerts (`> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`) instead of emoji. - No dead links; no doc–code drift. +- Use [`TERMINOLOGY.md`](TERMINOLOGY.md) as the German (de-CH)/English copy glossary — the content audit's `STYLE_REFERENCE` for binding and advisory term choices. ## Contributing a new audit template diff --git a/DOCUMENTATION-STANDARD.md b/DOCUMENTATION-STANDARD.md index 37a273a..602d7d5 100644 --- a/DOCUMENTATION-STANDARD.md +++ b/DOCUMENTATION-STANDARD.md @@ -1,7 +1,7 @@ # Dokumentations-Standard (Google-Grade) Ein normativer Standard für Repository-Dokumentation: messbar, profilabhängig und an den -aktuellen Google-Dokumentationsmustern ausgerichtet. Dieser Standard ist der Maßstab, gegen den +aktuellen Google-Dokumentationsmustern ausgerichtet. Dieser Standard ist der Massstab, gegen den das [`documentation-audit`](audit-prompts/documentation-audit-master-prompt.md) beliebige Repos prüft und konkrete Verbesserungs-Issues erzeugt. @@ -39,7 +39,7 @@ Dieser Standard übernimmt **Googles Schreib- und Barrierefreiheits-Disziplin** **Repo-Kopf**, den Googles eigene, minimalistische READMEs bewusst weglassen: Badges, ein Management-Summary und ein Architektur-Diagramm. Diese Mischung ist gewollt: -- **Von Google:** Stimme, zweite Person, Präsens, Aktiv, satzweise Großschreibung der +- **Von Google:** Stimme, zweite Person, Präsens, Aktiv, satzweise Grossschreibung der Überschriften, parallele Listen, Geltungsbereich + Zielgruppe zuerst nennen, strikte Barrierefreiheit. (Quelle: Google developer documentation style guide, tech-writing.) - **Von Best-in-Class-OSS:** Badge-Reihe (shields.io), Management-Summary/TL;DR, Mermaid- @@ -95,7 +95,7 @@ Der Kopf entscheidet, ob ein Leser bleibt. Reihenfolge (verbindlich): 5. **Inhaltsverzeichnis.** Ab ~100 Zeilen README. Beschreibende Linktexte, funktionierende Anker. > [!TIP] -> Das C4-Modell hilft beim Schichten von Architektur: **Context** (System + Außenwelt) → +> Das C4-Modell hilft beim Schichten von Architektur: **Context** (System + Aussenwelt) → > **Container** (Apps, DBs, APIs) → **Component** (Inneres eines Containers). Im Repo-Kopf gehört > in der Regel ein Context- oder schlankes Container-Diagramm. @@ -195,7 +195,7 @@ tech-writing-Kursen. Sie gelten für jede Markdown-Datei im Repo. - **Code-Blöcke.** Sprache am Fence angeben; Einrückung 2 Leerzeichen; Zeilen ~80 Zeichen; ausgelassenen Code per sprachspezifischem Kommentar markieren, nicht per „…". - **Caption-first bei Abbildungen.** Erst die Bildunterschrift/Aussage, dann das Bild; Callouts - statt langer Fließtext-Erklärungen. + statt langer Fliesstext-Erklärungen. --- @@ -204,7 +204,7 @@ tech-writing-Kursen. Sie gelten für jede Markdown-Datei im Repo. Barrierefreiheit ist nicht optional. Dokumentation muss mit Screenreader und Tastatur nutzbar sein. - **Alt-Text** für jedes informative Bild; leerer Alt-Text nur für rein dekorative Bilder. -- **Keine Information ausschließlich über Bilder** vermitteln. +- **Keine Information ausschliesslich über Bilder** vermitteln. - **Keine Richtungssprache.** „vorstehend/folgend/weiter oben im Text" statt „oben/unten/rechts" — Layout variiert je nach Gerät und Screenreader. - **Kontrast** mindestens 4.5:1 für Text. @@ -266,7 +266,7 @@ ausgewiesen. - **P1 — Hoch:** kein Management-Summary, kein Architektur-Diagramm wo Profil es verlangt, undokumentiertes Kern-Feature, fehlende Pflicht-Health-Datei. - **P2 — Mittel:** Drift, schwache Navigation, inkonsistente Terminologie, dünne Referenz. -- **P3 — Niedrig:** Stil, Tippfehler, Emoji-Politik-Verstöße ohne Informationsverlust. +- **P3 — Niedrig:** Stil, Tippfehler, Emoji-Politik-Verstösse ohne Informationsverlust. Die Befunde werden nach dem [`ISSUE-OUTPUT-STANDARD.md`](ISSUE-OUTPUT-STANDARD.md) ausgegeben: zuerst ein Tracking-Issue (priorisierter Index + Management-Summary + Roadmap), dann pro Befund diff --git a/ISSUE-OUTPUT-STANDARD.md b/ISSUE-OUTPUT-STANDARD.md index 8495d86..3922352 100644 --- a/ISSUE-OUTPUT-STANDARD.md +++ b/ISSUE-OUTPUT-STANDARD.md @@ -5,13 +5,14 @@ Dieser Standard ist **verbindlich** und wird von jeder Vorlage in `audit-prompts > [!NOTE] > **Management-Summary.** Nach der adversariellen Verifikation überführt jedes Audit seine -> bestätigten Befunde in GitHub-Issues — **standardmäßig auf Deutsch**. Zuerst entsteht **ein +> bestätigten Befunde in GitHub-Issues — **standardmässig auf Deutsch**. Zuerst entsteht **ein > Tracking-Issue** (der Index aller Sub-Aufgaben, nach Priorität sortiert, mit Management-Summary, > Scorecard und Roadmap), danach **pro Befund ein eigenes Issue**, jedes mit eigener > Management-Summary und konkreter Vorher/Nachher-Handlungsempfehlung. Das echte Anlegen erfolgt > **erst nach Vorschau und ausdrücklicher Freigabe**. -Version 1.0.0 · Sprache der Issues: standardmäßig Deutsch (`OUTPUT_LANG` überschreibbar) +Version 1.1.0 · Sprache der Issues: standardmässig Deutsch (`OUTPUT_LANG` überschreibbar) +Neu in 1.1.0: de-CH-Orthografie (durchgehend ss) und der `dimension:`/`effort:`-Label-Kanon sind verbindlich. --- @@ -20,6 +21,11 @@ Version 1.0.0 · Sprache der Issues: standardmäßig Deutsch (`OUTPUT_LANG` übe - **Auslöser:** läuft nach Phase 3 (Verifikation) und der Synthese. Nur **bestätigte** Befunde werden zu Issues; Hypothesen bleiben getrennt im Bericht. - **Sprache:** Deutsch als Standard. Pro Lauf via `OUTPUT_LANG` änderbar (z. B. für englische Repos). +- **Locale & de-CH.** Die deutsche Issue-Ausgabe nutzt Schweizer Orthografie (durchgehend ss, kein + Eszett — Ausnahme nur unveränderliche Eigennamen, Code, Rechtstitel, wörtliche Zitate), deutsche + Anführungszeichen „…" (nie ein gerades ASCII-Schlusszeichen) und einheitliche Terminologie gemäss + Projekt-Glossar ([`TERMINOLOGY.md`](TERMINOLOGY.md)). Das gilt für **alle** Audits und ist pro Lauf + via `OUTPUT_LANG`/Locale überschreibbar. - **Vorschau zuerst.** Immer ein Trockenlauf (vollständiger Issue-Text als Markdown im Bericht). Echtes Anlegen nur bei **ausdrücklicher Freigabe** und vorhandenem Repo-Zugriff (`gh issue create`). - **Idempotenz.** Vor dem Anlegen bestehende Audit-Issues per Label-Suche (`audit`, ``) @@ -35,7 +41,7 @@ Ein einzelnes „Epic"/Index-Issue, das alle Sub-Aufgaben bündelt. - **Titel:** `[AUDIT] — Befund-Tracker & Roadmap` - **Labels:** `audit`, `tracking`, `` (z. B. `security`, `performance`, `docs`) - **Body:** - 1. **Management-Summary** (3–5 Sätze): Gesamturteil, Score/Note, größtes Risiko, realistisches + 1. **Management-Summary** (3–5 Sätze): Gesamturteil, Score/Note, grösstes Risiko, realistisches Ziel nach Behebung. Für Leitung lesbar. 2. **Scorecard** (Tabelle): Dimensionen × Note/Score × Befundzahl je Schweregrad. 3. **Priorisierte Aufgabenliste** als Checkboxen, sortiert **P0 → P3**, innerhalb gleicher @@ -58,7 +64,9 @@ Jeder bestätigte Befund wird ein eigenständiges, erstklassig dokumentiertes Is - **Titel:** `[][] ` — z. B. `[P0][AuthZ] IDOR an GET /api/orders/{id}` -- **Labels:** `audit`, `sev:p0|p1|p2|p3`, `domäne:`, `aufwand:S|M|L` +- **Labels:** `audit`, `sev:p0|p1|p2|p3`, `dimension:`, `effort:S|M|L`, optional `locale:de-CH`. + Die Lokalisierungs-Dimension heisst `dimension:localisation`; `locale:de-CH` markiert Schweizer + Orthografie (optional). - **Body (feste Reihenfolge):** 1. **Management-Summary** (2–3 Sätze): was, Auswirkung, Empfehlung in einem Satz. 2. **Schweregrad & Score:** P-Stufe + auditspezifischer Score (CVSS / ICE / Rubrik-Punkte). @@ -96,7 +104,7 @@ Damit die Checklisten-Links im Tracker auflösen, in dieser Reihenfolge arbeiten ```markdown > [!NOTE] > **Management-Summary.** Das Security-Audit von `acme/shop` ergibt Note **Bronze (62/100)**. -> Größtes Risiko: ein nicht authentifizierter Endpunkt, der Kundendaten preisgibt (P0). +> Grösstes Risiko: ein nicht authentifizierter Endpunkt, der Kundendaten preisgibt (P0). > Nach Behebung der 2 P0- und 3 P1-Befunde ist Silver erreichbar. ## Scorecard diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md new file mode 100644 index 0000000..dd730b4 --- /dev/null +++ b/TERMINOLOGY.md @@ -0,0 +1,105 @@ +# Terminology + +This is the project glossary for German (de-CH) and English copy across the site +([`web/lib/i18n.ts`](web/lib/i18n.ts), [`web/lib/audit-details.ts`](web/lib/audit-details.ts), +[`web/lib/content.ts`](web/lib/content.ts)) and the German issue output of the 13 audit prompts in +[`audit-prompts/`](audit-prompts/). It is a reference doc, so the head-matter is English; the +canonical German forms live in the `de-CH` column. The content audit consumes this file as its +`STYLE_REFERENCE`. + +Two tiers govern every entry: + +- **BINDING** — a fixed decision. An audit may **not** override it. Use it verbatim (for + keep-as-code tokens) or in its single canonical form. +- **ADVISORY** — a preferred canonical form. An audit may **extend** the advisory tier with new + entries per run, but may never **demote** an advisory preference to a worse variant, and never + promote translationese over the listed form. + +German copy follows Swiss orthography (de-CH): always `ss`, never the Eszett, except immutable +proper names, code, legal titles, or verbatim quotes. German quotation marks are „…", never an +ASCII straight-quote closer. See [`ISSUE-OUTPUT-STANDARD.md`](ISSUE-OUTPUT-STANDARD.md) for the +governing locale rule that all audits inherit. + +The `keep-as-code?` column says whether the token stays a verbatim literal (`yes`) or is rendered +as prose in the target language (`no`). + +## Binding — keep as code (stay English) + +These tokens are acronyms, proper names, or literal identifiers. They are never translated, never +spelled out in running text, and keep their exact casing. + +| Concept | EN (canonical) | de-CH | keep-as-code? | Tier | Rationale | +|---|---|---|---|---|---| +| Continuous integration/delivery | CI/CD | CI/CD | yes | BINDING | Established pipeline acronym; recurs across the prompts. | +| Infrastructure as code | IaC | IaC | yes | BINDING | Standard acronym; do not spell out in German. | +| OWASP | OWASP | OWASP | yes | BINDING | Proper name of the standards body. | +| Common Weakness Enumeration | CWE | CWE | yes | BINDING | MITRE catalogue identifier (e.g. CWE-639). | +| CVSS | CVSS | CVSS | yes | BINDING | Scoring-system name; keep the score format too. | +| MITRE | MITRE | MITRE | yes | BINDING | Organisation / ATT&CK proper name. | +| CIS | CIS | CIS | yes | BINDING | Benchmark body name. | +| Software bill of materials | SBOM | SBOM | yes | BINDING | Supply-chain acronym; do not localise. | +| Retrieval-augmented generation | RAG | RAG | yes | BINDING | Established AI acronym. | +| SLSA | SLSA | SLSA | yes | BINDING | Supply-chain integrity framework name. | +| DORA | DORA | DORA | yes | BINDING | Delivery-metrics framework name. | +| WCAG | WCAG | WCAG | yes | BINDING | Accessibility standard; most-cited token in the corpus. | +| E-E-A-T | E-E-A-T | E-E-A-T | yes | BINDING | Google quality-rater acronym; keep the hyphenation. | +| Bottom line up front | BLUF | BLUF | yes | BINDING | Writing-discipline acronym. | +| Evidence citation | `file:line` | `file:line` | yes | BINDING | Fundort format; never translated or reformatted. | +| GitHub issue | GitHub-Issue | GitHub-Issue | yes | BINDING | Product name; German compound keeps „Issue". | +| Workflow trigger | `pull_request_target` | `pull_request_target` | yes | BINDING | Literal GitHub Actions identifier. | +| Insecure direct object reference | IDOR | IDOR | yes | BINDING | Vulnerability-class acronym. | +| Broken object-level authorization | BOLA | BOLA | yes | BINDING | OWASP API vulnerability-class acronym. | +| API | API | API | yes | BINDING | Universally known; never spelled out. | + +## Binding — terms of art (keep English; one canonical German-inflected form where used as a verb) + +These are established terms of art. The English noun is kept in German prose; where the corpus uses +the concept as a verb, exactly one German-inflected form is canonical. + +| Concept | EN (canonical) | de-CH | keep-as-code? | Tier | Rationale | +|---|---|---|---|---|---| +| Trust boundary | Trust Boundary | Trust Boundary | no | BINDING | Threat-modelling term of art; keep English noun. | +| Blast radius | Blast-Radius | Blast-Radius | no | BINDING | Established impact-scope term; keep the compound. | +| Prompt injection | Prompt-Injection | Prompt-Injection | no | BINDING | Security term of art; do not translate. | +| Supply chain | Supply Chain | Supply Chain | no | BINDING | Kept English in the prompts; not „Lieferkette". | +| Business logic | Business Logic | Business Logic | no | BINDING | Term of art; not „Geschäftslogik". | +| Human gate | Human-Gate | Human-Gate | no | BINDING | Agent-safety term; keep the English compound. | +| Output sink | Output-Sink | Output-Sink | no | BINDING | Dataflow term of art. | +| Cost cap | Cost-Cap | Cost-Cap | no | BINDING | Agent-budget term; keep English. | +| Untrusted input | untrusted Input | untrusted Input | no | BINDING | Kept as „untrusted Input" across the prompts. | +| Merge (git) | merge | mergen | no | BINDING | German verb „mergen" is the canonical inflected form; keep it. | +| Map (a system) | map | kartieren | no | BINDING | Canonical German verb is „kartieren", never „mappen". | + +## Advisory — translate (prefer the German) + +Where a clean German word exists, prefer it over an English loan. An audit may extend this list but +must not revert to the English form. + +| Concept | EN (canonical) | de-CH | keep-as-code? | Tier | Rationale | +|---|---|---|---|---|---| +| Finding | finding | Befund | no | ADVISORY | „Befund" is the established term in `i18n.ts` / `audit-details.ts`. | +| Output (result) | output | Ergebnis | no | ADVISORY | Prefer „Ergebnis" over „Output" in prose. | +| Run (a pass) | run | Durchlauf | no | ADVISORY | „Durchlauf" for one audit pass. | +| Lens | lens | Prüfbereich / Prüfdimension | no | ADVISORY | Translate; no English-loan need. | +| Sweep | sweep | Durchlauf | no | ADVISORY | Same German as „run". | +| Deduplicate | deduplicate | Doppelungen entfernen | no | ADVISORY | Avoid „deduplizieren"; use plain German. | +| Benchmark (verb) | benchmark | gegen Referenzen prüfen | no | ADVISORY | Avoid „benchmarken"; describe the action. | +| Remediation | remediation | Korrekturmassnahme | no | ADVISORY | de-CH spelling with ss, never the Eszett form. | +| Failure mode | failure mode | Fehlerbild | no | ADVISORY | Prefer „Fehlerbild". | +| Scope | scope | Umfang | no | ADVISORY | „Umfang" (already used in `i18n.ts`). | + +## Advisory — rephrase (anchorless translationese to avoid) + +These English phrasings produce calques in German. Rephrase to the listed German instead of +translating word for word. + +| Concept | EN (canonical) | de-CH | keep-as-code? | Tier | Rationale | +|---|---|---|---|---|---| +| Run/operate it | "laufen lassen" | einsetzen / ausführen | no | ADVISORY | „laufen lassen" is anchorless; use „einsetzen" or „ausführen". | +| Aim the agent | "Point your agent at" | „… nutzen" | no | ADVISORY | Rephrase to „… nutzen"; avoid the literal calque. | +| Self-test | "dogfooded" | „prüft sich selbst" | no | ADVISORY | Render the meaning: „prüft sich selbst". | +| Steelman | "steelmannen" | „den stärksten Gegenpunkt bilden" | no | ADVISORY | No German loan; describe the action. | + +> [!NOTE] +> This glossary is a seed. Audits extend the ADVISORY tier per run, but never demote a BINDING +> decision. diff --git a/audit-prompts/content-audit-master-prompt.md b/audit-prompts/content-audit-master-prompt.md index baa0223..6961926 100644 --- a/audit-prompts/content-audit-master-prompt.md +++ b/audit-prompts/content-audit-master-prompt.md @@ -34,6 +34,12 @@ VOICE: DATA_ACCESS: OUTPUT_LANG: +SOURCE_LANGUAGE: +LOCALISATION_MODE: +TERMINOLOGY_POLICY: ISSUE_TARGET: ``` @@ -41,6 +47,12 @@ If unknown, Phase 0 infers the content type, thesis, audience, awareness stage, piece itself and states its assumptions explicitly. The thesis and the goal are the yardsticks; every finding is judged against whether it helps the reader believe the thesis and take the action. +`OUTPUT_LANG` expresses the target **locale**, not merely the language: Deutsch defaults to Swiss +**de-CH** (always *ss*, never *ß*). `VOICE` may point at an approved native corpus or glossary (a +`STYLE_REFERENCE`) the rewrite must match. When `SOURCE_LANGUAGE` differs from the target locale the +localisation apparatus (operating principle 9, lens C15, the Native Reader skeptic) runs in full; +when they match it runs as a lighter native-quality check. + --- ## Operating principles (binding for every agent) @@ -66,6 +78,20 @@ every finding is judged against whether it helps the reader believe the thesis a 8. **Comparative lens — measure information gain.** Benchmark against the best existing content for this reader and goal. Commodity content that a reader could get from any of ten other sources is a finding even when every sentence is clean. +9. **Native-language & locale integrity.** For any output whose target locale differs from the + source language — and as a lighter native-quality check when source == target — judge the text as + **original copy in its target locale**, never as a translation. Native-first test: an experienced + native copywriter in the target locale could plausibly have written it without ever seeing a + source-language original. Preserve **meaning, not sentence structure**. Precision over purism: + keep English for code identifiers, standards, established technical terms, UI labels, and + commands, and wherever it is materially more precise (CI/CD, OWASP, CVSS, SBOM, RAG, `file:line`, + GitHub-Issue, trust boundary, prompt injection, …). Terminology is **intentional**: each recurrent + term is explicitly kept / translated / rephrased and then used in **one canonical form**. Locale + rules are hard requirements; for de-CH: always *ss*, never *ß* (except immutable proper names, + code, legal titles, or verbatim quotes — each retained *ß* tagged `quote` | `code` | `legal`); + German „…" quotation marks, never an ASCII straight-quote closer; match the corpus register (the + auditor corpus uses *du*); comma decimals; orthography and anglicism tolerance only — **no** Swiss + dialect lexis (no Grüezi / Velo / parkieren / Natel). ### Severity scale @@ -78,6 +104,11 @@ every finding is judged against whether it helps the reader believe the thesis a Each finding gets **effort (S/M/L/XL)** and **priority = impact × confidence ÷ effort**. +**Localisation severity (C15).** P1 — systemic source-language interference in the hero, primary +value proposition, primary CTA, or core navigation; a phrase that obscures the product's meaning; or +trust-eroding terminology inconsistency in prominent content. P2 — recurring unnatural wording across +a page or module. P3 — isolated awkwardness or a minor locale correction. + --- ## Phase 0 — Reconnaissance (run first, feeds every agent) @@ -98,6 +129,16 @@ Build the shared brief every specialist receives: rewrites stay on-brand. - **Comparison set:** 2–3 best-in-class pieces for this reader and goal to benchmark against in Phase 4 (named in `COMPARISON` or chosen here). +- **Language & localisation brief:** the target language and locale; the source language and its + likely interference; the intended register; the reader's technical fluency; protected English + terms; preferred German terms; suspected translation artefacts; and any explicitly protected + wording. +- **Terminology matrix:** before any rewrite, build a matrix — *term | keep / translate / rephrase | + chosen form | rationale | scope* — so every recurrent term resolves to one canonical form. +- **Localisation profile:** state it explicitly. Source == target ⇒ a native-quality check only; + source != target ⇒ the full apparatus (operating principle 9, lens C15, the Native Reader + skeptic). When the corpus shows parallel source + target strings (e.g. an English master with + localized siblings), the profile is source != target. Output: a structured brief (thesis, audience, awareness stage, goal, objections, voice, references) distributed to all Phase 1 agents. @@ -188,6 +229,49 @@ Misleading or unsubstantiated claims, manipulative dark-pattern copy, undisclose exclusionary, non-inclusive, or culturally blind language. Anything that exposes the author to a credibility, legal, or trust hit is escalated with its harm chain. +### C15 — Native-language & locale integrity +Runs on the Phase 0 **localisation profile**. Two profiles: source == target ⇒ a lighter +native-quality pass (orthography, terminology consistency, idiom); source != target ⇒ the full +apparatus below. For non-source locales, systematically inspect for: English sentence architecture +and literal translation; imported phrasal-verb logic; unnecessary Denglish verbs; false friends; +unnatural collocations; noun-heavy stacks; inconsistent technical terminology; English terms that are +neither protected nor more precise; translated idioms; register inconsistency across product copy / +control jargon / engineering notes; locale-orthography violations; and CTAs, headings, or microcopy +that are correct but not idiomatic. + +**Precision carve-outs (do not puristically replace):** GitHub, CI/CD, CVSS, OWASP, SBOM, RAG, code +identifiers, file paths, commands, and framework terms. **Terms-of-art verbs anchored to a tool** +(Git *mergen*; data *mappen* / *kartieren*) are kept and enforced in one canonical form; only +anchorless translationese verbs (*laufen lassen*, *steelmannen*) are flagged. + +**Native-rewrite safety:** meaning-reshaping native-rewrite applies only to marketing / UX copy. For +safety, legal, or factual content, restrict changes to orthography and terminology, and route any +P0/P1 wording change through the accuracy lens (C9) with an explicit claims-preserved assertion. + +Each confirmed C15 finding states: the exact text and its location; the language pattern detected; +why it sounds translated or non-native; a technically equivalent native rewrite (precision +preserved); the terminology decision (keep / translate / rephrase); and whether it is systemic or +isolated. Example: + +```json +{ + "id": "C15-004", + "title": "Hero subline reads as a literal translation of an English clause", + "severity": "P1", + "confidence": 0.9, + "effort": "S", + "location": "hero, line 2", + "quote": "Wir lassen deinen Code von einem Schwarm von Agenten laufen, um Risiken zu mappen.", + "language_pattern": "literal carry-over of English clause order + anchorless verb 'laufen lassen' (run)", + "evidence": "Blind back-translation snaps cleanly to 'We run your code through a swarm of agents to map risks' — same clause order, same verb choice; a native de-CH copywriter would not phrase 'lassen … laufen' here. 'mappen' is an anchored term-of-art and is kept.", + "fix": "Before: 'Wir lassen deinen Code von einem Schwarm von Agenten laufen, um Risiken zu mappen.' After: 'Ein Agenten-Schwarm prüft deinen Code und mappt die Risiken.'", + "terminology_decision": "keep 'mappen' (anchored, one canonical form); rephrase 'laufen lassen' → 'prüft'; keep 'Agent' / 'Schwarm'", + "native_rewrite": "Ein Agenten-Schwarm prüft deinen Code und mappt die Risiken.", + "locale": "de-CH", + "expected_impact": "Hero reads as original de-CH copy, not a translation; preserves the 'mappen' term-of-art while removing translationese that erodes trust in the primary value proposition." +} +``` + --- ## Phase 2 — Cross-pollination barrier @@ -209,6 +293,19 @@ hard gate: if the steelmanned counter-argument stands unanswered, that is record finding. Then a **completeness critic** asks: which passage wasn't quoted, which claim wasn't checked, which reader objection wasn't tested? +**The Native Reader (C15).** For C15-P1/P2 findings this skeptic **replaces** the standard +three-skeptic panel. It works **without the source text** and runs a **blind back-translation**: +translate the target text back into the source language; if it snaps to the source's sentence and +clause order, the text is translationese and criterion (a) is met. It also checks that the proposed +rewrite **preserves technical precision and voice** rather than over-correcting into artificial +purism. A language finding survives only on **≥ 2 of 3**: (a) the text is demonstrably translated or +non-native — the back-translation decides, not taste; (b) a more natural form exists **without losing +precision** — the skeptic must **produce** that native alternative as evidence; (c) the fix improves +flow, trust, or comprehension. Two cases deterministically **override** the "default to refuted" +rule: a de-CH orthography violation (*ß*) and an English-verb-stem + German-inflection hybrid. An +off-manifest technical-term swap additionally requires a **Context Defender** sign-off with a +one-line precision-equivalence statement. + ## Phase 4 — Benchmark Compare thesis sharpness, evidence, structure, and information gain against the named best-in-class @@ -227,20 +324,31 @@ In `OUTPUT_LANG`: sharper one-sentence thesis if the current one is weak. 3. **Content scorecard (0–100):** score each dimension (weights below), report the total and the **grade band** (Gold 90–100 / Silver 75–89 / Bronze 60–74 / Needs-work 40–59 / Inadequate <40), - mapping the C1–C14 findings onto the dimensions. + mapping the C1–C15 findings onto the dimensions. The weighting is **mode-dependent**. + + When **source != target** (a localised piece), score a dedicated native-fit axis: | Dimension | Pts | |---|---| - | Thesis & argument integrity | 20 | - | Audience fit & message clarity | 20 | - | Evidence, credibility & originality | 15 | - | Structure & narrative | 15 | - | Voice, concision & line craft | 15 | - | Persuasion & engagement | 10 | - | Differentiation vs best-in-class | 5 | - - Re-weight for the content type (e.g., a pitch leans on persuasion/CTA; an essay on thesis and - originality) and state the re-weighting. + | Thesis & argument integrity | 18 | + | Audience fit & clarity | 18 | + | Evidence, credibility & originality | 13 | + | Structure & narrative | 13 | + | Voice, concision & line craft | 13 | + | Persuasion & engagement | 9 | + | Differentiation vs best-in-class | 4 | + | Native-language quality & locale fit | 12 | + + When **source == target**, add **no** new axis: fold ~3 points of native quality into *Voice, + concision & line craft* and keep the original seven weights (20 / 20 / 15 / 15 / 15 / 10 / 5 = + 100). In **both** modes, **either** a locale-orthography error (*ß* in de-CH) **or** a precision + regression (trading a precise English term for a vaguer German one) caps the native-fit + contribution — the *Native-language quality & locale fit* axis in localised mode, or the points + folded into *Voice, concision & line craft* in same-language mode; the penalty is symmetric (an + orthography error and a precision regression weigh the same). + + Re-weight further for the content type (e.g., a pitch leans on persuasion/CTA; an essay on thesis + and originality) and state the re-weighting. 4. **Before/after rewrites:** the highest-leverage passages rewritten in place (headline, opening, value proposition, CTA), each with a one-line rationale. 5. **Verified findings register:** the shared schema, sorted by priority; skeptic note on P0/P1. @@ -251,7 +359,16 @@ In `OUTPUT_LANG`: thesis correctly after one read", "every superlative is backed by a cited specific"). 9. **Optional ready-to-publish rewrite:** for a low-scoring piece, attach a full rewritten draft that preserves voice and meaning. -10. **GitHub issues (mandatory)** per [`ISSUE-OUTPUT-STANDARD.md`](../ISSUE-OUTPUT-STANDARD.md) — +10. **Localisation verdict** (when localisation is in scope): native / mixed / translated-sounding; + the dominant interference patterns; whether they are systemic or isolated; and the single most + important language correction. +11. **Terminology decision log:** *term | keep / translate / rephrase | approved form | rationale | + affected locations* — one canonical form per recurrent term. +12. **Native-copy rewrite set:** the hero, primary value proposition, primary CTA, navigation + labels, highest-traffic headings, and the most repeated *ss/ß* and Denglish-verb offenders — + **not** a "jargon cluster", because here the jargon *is* the value proposition. Each native + rewrite binds to its content key / location, not free text; for German, default to de-CH. +13. **GitHub issues (mandatory)** per [`ISSUE-OUTPUT-STANDARD.md`](../ISSUE-OUTPUT-STANDARD.md) — see the dedicated section below. ### Appendices @@ -273,7 +390,11 @@ preview/dry-run first, created only on explicit authorization + repo access. Two **management summary** (2–3 sentences: what, impact on the reader/goal, one-line recommendation), then the full finding (severity, dimension, the **quoted passage** with location, evidence, a concrete **before → after** rewrite, effort, re-audit criterion). Labels: `audit`, `content`, - `sev:p0…p3`, `dimension:`, `effort:S|M|L`; back-link to the tracking issue. + `sev:p0…p3`, `dimension:`, `effort:S|M|L`; back-link to the tracking issue. For localisation + (C15) findings, add `dimension:localisation` (and optionally `locale:de-CH`), title the issue + `[P1][Lokalisierung] …` (the German word, not `[de-CH]`), and carry — in addition to the + standard fields — the **language pattern**, the **terminology decision**, the **before/after**, + and the **re-audit criterion**. For a low-scoring piece, optionally attach a **ready-to-publish rewritten draft** to the tracking issue or open it as a PR. Create child issues first, collect their numbers, then create/update the @@ -298,7 +419,13 @@ rather than duplicate. "evidence": "The first concrete, specific benefit ('cut onboarding from days to minutes') appears at line 4; the first three sentences are generic context the reader already accepts and could apply to any competitor.", "fix": "Before: 'In today's fast-moving landscape...'. After: 'Cut new-hire onboarding from three days to twenty minutes.' Lead with the specific outcome; delete the generic preamble.", "expected_impact": "Moves the single most decision-relevant claim above the fold; reduces 5-second bounce for problem-aware visitors.", - "anticipated_refutation": "'The preamble sets context' — a problem-aware reader already has the context; the preamble costs the only seconds you get and says nothing a competitor couldn't." + "anticipated_refutation": "'The preamble sets context' — a problem-aware reader already has the context; the preamble costs the only seconds you get and says nothing a competitor couldn't.", + + // C15-only — present only on native-language / localisation findings; otherwise omit these four: + "language_pattern": "literal translation of English clause order", + "terminology_decision": "keep 'mappen'; rephrase 'laufen lassen' → 'prüft'", + "locale": "de-CH", + "native_rewrite": "Ein Agenten-Schwarm prüft deinen Code und mappt die Risiken." } ``` @@ -325,4 +452,14 @@ rather than duplicate. second person, present/active. - [ ] Coverage and "claims checked vs unverifiable" appendices are complete and honest. - [ ] The source content was left unmodified; rewrites are proposals, not edits to the original. +- [ ] The target locale was identified and recorded; the localisation profile (source == / != target) + was stated. +- [ ] Every non-source rewrite passed the native-first (blind back-translation) test. +- [ ] No *ß* remains in de-CH output except immutable quotes / code / legal names, each tagged. +- [ ] Recurring terminology resolves to one approved form (terminology decision log attached). +- [ ] English was kept only where protected, a standard, or materially more precise. +- [ ] No rewrite traded technical precision for "more German"; each precision regression is logged + per swap. +- [ ] The hero, primary CTA, navigation, and high-traffic headings were checked separately for + native quality. ``` diff --git a/audit-prompts/lean-audit-master-prompt.md b/audit-prompts/lean-audit-master-prompt.md index a482d54..56c60a6 100644 --- a/audit-prompts/lean-audit-master-prompt.md +++ b/audit-prompts/lean-audit-master-prompt.md @@ -334,7 +334,7 @@ Two-part contract: finding: severity, dimension, removal **class**, evidence `file:line` + tool signal, the blind-spots-checked line, reachability/reversibility/blast-radius, impact, a concrete before/after fix **with a git-revert/reversibility note**, effort, and a re-audit criterion. Labels: `audit`, - `sev:p0…p3`, `domäne:`, `aufwand:S|M|L`; back-link to the tracker. + `sev:p0…p3`, `dimension:`, `effort:S|M|L`; back-link to the tracker. Create child issues first, collect their numbers, then create/update the tracking issue so its checklist links resolve. Detect existing audit issues by label and update rather than duplicate.