Report

Co skill dělá

Ze zdrojových dat udělá jeden samostatný HTML soubor, který jde vzít, poslat mailem nebo nahrát na web, a kdekoliv se otevře a funguje – bez serveru, bez internetu, bez závislostí.

Co skill nedělá

• Nepouští data ven neagregovaná. V reportu jsou jen souhrny, nikdy původní řádky.
• Nezakrývá nejistotu. Malá čísla, krátké období a chybějící segmenty se přiznávají, ne obcházejí formulací.
• Nepočítá od oka. Výpočet je vždycky skript, který zůstane v projektu, protože report se přegeneruje.
• Neinterpretuje za hranicí dat. Co z čísel neplyne, do komentáře nepatří.
• Nezkoumá svět venku. Konkurenci a tržní rizika sbírá /discovery; tady se počítá z vlastního měření, ne z cizích produktů.
• Nereviduje měření. Jestli se měří správně a co v datové vrstvě chybí, řeší revize měření podle ~/Context/Analytics/; tenhle skill bere data taková, jaká jsou, a jen přizná, kde jsou slabá.

Jak je to postavené uvnitř

Volbu typu grafu, palety, os a legend skill neřeší sám – vyvolává na ni skill dataviz (Fáze 0, bod 3). Nad velkými zdrojovými daty si navíc čtení nedělá sám, ale posílá na ně subagenta, aby mu obsah souboru nesnědl kontext (Fáze 0, bod 1) – s dataviz to nesouvisí. Obojí je implementační detail, ne rozhraní: kdyby dataviz zmizel nebo se změnil, nahradí ho vlastní pravidla a na tom, co /report vyrábí, se nezmění nic.

Závazné je proti tomu to, co stojí v Nepřekročitelných požadavcích na výstup níž – jeden samostatný HTML soubor bez závislostí, jen agregovaná data a přiznaná nejistota. To se nesmí změnit tiše ani výměnou nástroje.

Nepřekročitelné požadavky na výstup

Tohle není doporučení. Když některý bod nejde splnit, zastav se a řekni to, místo abys ho potichu obešel.

1. Jeden soubor. HTML, CSS i JavaScript uvnitř. Obrázky a fonty jako data: URI. Data zapečená v souboru jako JS proměnná, ne načítaná fetchem.
2. Funguje z file://. Uživatel si ho otevře dvojklikem z disku. Žádný fetch, žádné moduly přes type="module" se sítí, žádné CORS.
3. Žádné CDN. Ani jeden <script src="https://…">, ani jeden <link rel="stylesheet" href="https://…">. Report musí fungovat offline i za pět let, až ta knihovna zmizí. Grafy kresli inline SVG nebo do <canvas> vlastním kódem; potřebuješ-li knihovnu, vlož ji do souboru celou a řekni, o kolik tím soubor narostl.
4. <meta charset="utf-8"> jako první věc v <head>. Bez toho se diakritika rozsype – a rozsype se právě až u příjemce, ne u tebe.
5. Žádná surová data. V reportu jsou jen agregované hodnoty. Originální řádky, ID uživatelů, e-maily, IP adresy ani nic, z čeho jdou zpětně sestavit, do souboru nepatří – viz Co nesmí ven ze souboru níž.
6. Datum vygenerování je statické. Skutečný okamžik, kdy report vznikl, zapsaný natvrdo do HTML. Nikdy new Date() v JavaScriptu – ten by ukazoval, kdy si to příjemce otevřel, což je nesmysl a zastírá stáří dat.
7. Zdroj dat a období jsou v reportu vidět. Kdo se na to podívá za půl roku, musí poznat, odkud čísla jsou a k jakému datu platí.

Fáze 0 – Příprava

Společný začátek drží ~/.claude/skills/preflight.md – načti si ho a řiď se jím. Body 4 a 5 odpadají: report je samostatný výstup, nesahá na kód projektu ani na diff větve.

Navíc si zjisti tohle:

1. Zdrojová data. Kde jsou, v jakém formátu, jak velká, jaké mají sloupce. Přečti si vzorek, ne celý soubor – u velkých dat na to pošli subagenta typem reader (subagent_type) a na nejlevnějším modelu (Volba modelu a effortu podle ~/.claude/standards/delegation.md, Model a effort podle úkolu.), je to čtení a shrnutí struktury. Typ bez shellu proto, že agent má jen číst – a zdrojová data bývají cizí soubor, do kterého nemá co sáhnout.
2. Načti doménové znalosti, které se na výstup vztahují:
   • ~/Context/Text/text.md – stavba a stylistika komentářů. Vždy.
   • ~/Context/Text/typography.md – česká sazba čísel, procent, jednotek, dat a interpunkce. Vždy – report je plný čísel.
   • ~/Context/Web/web.md – část pro statickou stránku otevřenou z disku (velikost písma, kontrast, šířka řádku, responzivita, meta tagy). Části pro stránku na serveru a pro dynamickou aplikaci se sem nevztahují.
   • ~/Context/Analytics/analytics.md – jsou-li data z GA4, GTM nebo BigQuery. Ovlivňuje to interpretaci, ne vzhled.
   • ~/Context/Advertising/advertising.md – jsou-li data z reklamních systémů (Google Ads, Meta, Sklik, LinkedIn). Rozhoduje o tom, co v číslech vůbec hledat: pokles konverzí po změně konverzní akce znamená něco jiného než pokles z poklesu poptávky.
3. Vyvolej skill dataviz – dřív, než napíšeš první řádek kódu grafu. Řeší volbu typu grafu, palety, os a legend. Bez něj vzniknou grafy, které spolu nedrží.

Fáze 1 – Co se reportuje

Ptej se postupně, jednu otázku za druhou, přes AskUserQuestion (viz ~/.claude/standards/rules.md, Ptej se postupně, ne všechno najednou). Nemá-li otázka nabídnutelné varianty, ptej se normálně.

Co potřebuješ vědět, než začneš počítat:

1. Otázka, na kterou report odpovídá. Ne „report z dat“, ale „jak moc Wimbledon zvedl návštěvnost“. Bez ní vznikne přehlídka grafů, ze které si nikdo nic neodnese.
2. Kdo to bude číst. Management, klient, kolega z oboru, nebo jen uživatel sám. Určuje to hloubku i tonalitu.
3. Období a rozsah dat.
4. Jednotka analýzy a normalizace. Počítá se to na řádky, na uživatele, na návštěvy, na dny? Může jeden uživatel přispět víc záznamy? Tohle je nejčastější zdroj chybných čísel – zeptej se výslovně a odpověď zapiš do metodiky.
5. Co se má porovnávat. Mezitýdenní srovnání, vývoj v čase, segmenty, poměr k celku.

Než začneš stavět, vypiš osnovu – jaké sekce report bude mít a co v každé bude – a nech ji odsouhlasit. Přestavovat hotový report je dražší než přepsat osnovu.

Fáze 2 – Zpracování dat

1. Počítej skriptem, ne od oka. Napiš skript (Python), ulož ho do projektu a nech ho tam. Report se skoro vždycky přegenerovává – nová data, opravená metodika, další období. Jednorázový výpočet v hlavě se nedá zopakovat ani zkontrolovat.
2. Mezivýsledky ulož do projektu jako JSON nebo CSV. Když se pak mění jen vzhled, nemusí se počítat znovu.
3. Ověř si čísla. Sedí součty? Sedí poměry na 100 %? Odpovídá celkový počet zdroji? Nesedí-li něco, neopravuj to tichým zaokrouhlením – najdi příčinu.
4. Nedopočítávej, co nevíš. Chybí-li den v datech, buď to v grafu přizná (mezera), nebo se interpoluje – ale pak to musí být v reportu označené jako odhad.
5. Metodiku piš průběžně, ne až nakonec. Jak se normalizovalo, co se vyloučilo, jak se řešily chybějící hodnoty, jaké jsou limity dat.

Fáze 3 – Stavba reportu

Struktura

Záhlaví        název, období, zdroj dat, datum vygenerování (statické)
Shrnutí        3–5 vět, co z toho plyne. Čte se jako první a často jako jediné.
Sekce 1..N     každá: graf nebo tabulka + krátký komentář, co v tom vidím
Metodika       jak se počítalo, co se vyloučilo, jak se normalizovalo
Limity dat     čemu se nedá věřit a proč
Patička        Jan Tichý · jantichy@jantichy.cz · https://www.jantichy.cz

Má-li report víc tematických celků, udělej záložky. Nesmí to ale rozbít tisk do PDF – co je za neaktivní záložkou, se netiskne.

Tonalita

Tohle je místo, kde se reporty nejčastěji kazí. Platí ~/Context/Text/text.md, ~/Context/Text/typography.md a k tomu pravidla níž – a to pro každý psaný text v reportu, ne jen pro komentáře u grafů. Tedy i pro Shrnutí, Metodiku a Limity dat. U shrnutí to platí nejvíc, protože se podle Struktury výš čte jako první a často jako jediné.

• Věcně a krátce. Co se stalo, o kolik, oproti čemu.
• Žádné nadšení. Ne „skvělý nárůst!“, ne „úžasný výsledek“, ne vykřičníky. Konstatuj číslo a jeho význam.
• Žádná klišé a agenturní žargon. Píše se to pro člověka, který nemá čas a nemusí rozumět analytice.
• Interpretuj, nepopisuj. „Návštěvnost vzrostla 5ד je popisek grafu. „Nárůst je organický z Googlu, tedy zvýšené vyhledávání značky – ne odkazy z médií“ je komentář.
• Nejistotu přiznej. Malá čísla, krátké období, chybějící segment. Radši „na tohle jsou data příliš malá“ než opatrná formulace, která vypadá jako závěr.

Grafy

Kromě toho, co říká dataviz:

• Konzistentní barvy napříč celým reportem. Jedna veličina = jedna barva všude.
• Osa Y u procent od 0 do 100, pokud není výslovný důvod jinak.
• Nemíchej v jednom grafu absolutní čísla a procenta. Jsou to dva grafy pod sebou se sdílenou osou X.
• Legenda bez balastu – žádné hodnoty a roky v závorkách.
• Přímý tisk. Report se často tiskne do PDF. Ověř, že se grafy vejdou na šířku stránky a že se nerozpadnou.
• Tooltipy a interaktivita jsou bonus, ne nosič informace. Co je jen v tooltipu, v PDF neexistuje.

Dvě verze

U rozsáhlejších analýz udělej podrobnou i stručnou verzi. Stručná je zhruba pětina rozsahu, jen to podstatné, bez opakování – ne zkrácená kopie, ale samostatně napsaný text. Pojmenuj report.html (stručná, ta se používá častěji) a report-full.html.

Zeptej se, jestli je chce obě, ne že to uděláš automaticky.

Co nesmí ven ze souboru

Report je soubor, který se posílá dál – e-mailem, do Slacku, klientovi – a jednou venku už ho nevezmeš zpátky. Proto se kontroluje až hotový vygenerovaný soubor, ne zdroje. Únik vzniká přesně v tom kroku, kdy se do HTML něco zapeče.

Hledej dvě skupiny.

1. Osobní údaje. user_id, user_pseudo_id, client_id, e-maily, jména, telefony, adresy, IP adresy, ID objednávek a faktur, cokoliv, z čeho jde identifikovat konkrétního člověka. Pozor i na nepřímou identifikaci: segment o třech lidech je taky osobní údaj.

2. Přístupové a autentizační údaje. Tohle je zrádnější, protože to do reportu nikdo vědomě nedává – proteče to tam samo z výpočetního skriptu, konfigurace nebo odkazu:

• API klíče a tokeny (api_key, api_secret, access_token, refresh_token, bearer, client_secret, měřicí API secret GA4, tokeny MCP serverů)
• hesla, connection stringy k databázi, přihlašovací údaje v jakékoliv podobě
• privátní klíče a certifikáty (BEGIN … PRIVATE KEY, .pem, .p12)
• session cookies a hodnoty hlaviček Authorization
• autentizace v URL – podepsané odkazy (presigned S3 a GCS, token auth Bunny, sdílecí odkazy Google Drive) a query parametry typu ?token=, ?key=, ?sig=, ?signature=, ?auth=. Odkaz do zdroje dat vypadá nevinně, dokud si nevšimneš, že v sobě nese platný podpis.
• interní věci, které nikomu venku nic nedají a jen prozrazují prostředí: absolutní cesty /Users/honza/…, interní hostnames a IP, názvy projektů a datasetů, poznámky v komentářích

Kde hledat. Ne jen v textu, který je vidět:

• zapečená datová proměnná
• inlinovaný JavaScript a jeho komentáře
• HTML komentáře
• data: URI obrázků – screenshot z administrace může mít token přímo na obrazovce; když do reportu vkládáš obrázek, který jsi sám nevyrobil z dat, podívej se na něj
• atributy odkazů a <iframe src>

Jak. Nejdřív mechanicky – grep přes celý soubor na výš uvedené řetězce a na typické tvary (sk-, ghp_, AIza, eyJ na začátku JWT, -----BEGIN, dlouhé náhodné řetězce v query stringu). Pak si soubor přečti; grep nechytí to, co se jmenuje jinak.

Když něco najdeš, zastav se. Neodmazávej to potichu a nepokračuj – nález u druhé skupiny znamená dvě věci, ne jednu:

1. Ten údaj je i ve zdroji, ze kterého report vznikl – ve výpočetním skriptu, konfiguraci nebo mezidatech. A ty jsou nejspíš commitnuté v gitu, kde zůstanou i po smazání ze souboru.
2. Unikl-li ven i jen do rozpracované verze, kterou už někdo viděl, je potřeba ho rotovat. Řekni to výslovně; to není tvoje rozhodnutí, ale uživatel to musí vědět.

U osobních údajů, které jsou pro smysl reportu opravdu nutné, upozorni výslovně a nech si to potvrdit. Nikdy to nezamlčuj a nikdy si to neodsouhlas sám.

Fáze 4 – Ověření

Nespoléhej na to, že to vypadá dobře ve zdrojáku.

1. Otevři to v Chrome a projdi bod po bodu. Nalezené chyby oprav, znovu zkontroluj, a takhle dokola, dokud to nebude sedět. Sám cyklus ukonči nejpozději po pátém kole a řekni, co zbývá – nezacyklit se je taky součást práce.
2. Kontrolní seznam:
   • Diakritika je všude v pořádku (záhlaví, legendy, tooltipy, tisk).
   • Report funguje otevřený z file://, ne jen přes lokální server.
   • V konzoli nejsou chyby.
   • Žádný požadavek do sítě – ověř v záložce Network, že po načtení nejde ven nic.
   • Grafy se vykreslily a mají data. Prázdný nebo undefined graf je nejčastější tichá chyba.
   • Čísla ve všech psaných částech (shrnutí, komentáře, metodika, limity) sedí s čísly v grafech a tabulkách.
   • Stránka se nerozpadne na úzkém okně a v tisku do PDF.
3. Přepočítej namátkou dva tři údaje z reportu zpátky proti zdrojovým datům.
4. Projdi hotový soubor na úniky podle Co nesmí ven ze souboru výš. Tohle je poslední krok před předáním, protože až teď je soubor v podobě, ve které odejde – a všechny předchozí opravy do něj mohly něco vnést zpátky.

Fáze 5 – Uzavření

Zapiš do projektu:

• docs/decisions.md – metodická rozhodnutí a proč (jak se definoval uživatel, co se vyloučilo, proč zrovna tahle normalizace). U reportu je metodika to jediné, co se za půl roku nedá zrekonstruovat.
• docs/todo.md – co se nestihlo, co by šlo doplnit při příští aktualizaci.
• CLAUDE.md – jak se report přegeneruje, když přijdou nová data. Vždycky přijdou.

Commitni, má-li projekt zapnutý autocommit.

Závěr:

## Report hotový

**Soubory**
- <cesta> – <velikost>, <počet sekcí>
- <skript a mezidata>

**Data**
- Zdroj: <…> · Období: <…> · Vygenerováno: <datum>

**Ověřeno v prohlížeči**
- [seznam kontrol, které prošly]

**Na co upozorňuji**
- [limity dat, osobní údaje, nedopočítané věci – nebo „nic“]

Vypisuj to jako Markdown, ne jako blok kódu, a řádky nezalamuj natvrdo – ~/.claude/standards/rules.md, Styl odpovědí.

Zakonči jednou z těchto vět:

• Report je hotový a ověřený, můžeš ho poslat dál.
• Report hotový není – brání tomu: <konkrétní seznam>.