ankitg12/agent-skills

Wann dieses Skill verwendet werden soll

Verwenden Sie Typst anstelle von Word/.docx für jede detaillierte technische Ausarbeitung – Untersuchungsberichte, Architekturzusammenfassungen, Root-Cause-Dokumente, Migrationserklärungen. Zielen Sie auf Dokumente, die:

• Wie ein echter technischer Bericht aussehen: Titelseite, Executive Summary, nummerierte Abschnitte
• Im Druck gut aussehen (LaTeX-ähnlicher Textsatz: #set page, #set heading(numbering: "1.1"), Blocksatz)
• Diagramme enthalten (Architektur-/Ablaufdiagramme, nicht nur Fließtext)
• Tabellen enthalten (Vergleichstabellen, Belegtabellen, Statustabellen)
• Klickbare Links zu Quellen enthalten (Chat-Threads, GitHub-PRs, Wiki-Seiten)
• Primärquellen mit direkten Zitaten zitieren (Nachrichten, PR-Bodies), namentlich/datiert

Auslösephrasen: "schreib das auf", "erstell ein Dokument", "typst es", "erstell einen Bericht zu diesem Thema" – besonders nach einer Multi-Quellen-Untersuchung (Chat-Suche, GitHub-PR-Review, Live-System-Evidenz), die in ein teilbares Artefakt synthetisiert werden muss.

Vor dem Kompilieren: Führen Sie eine persönliche Typst-Gotchas-Datei (z.B. ~/notes/typst.md) und konsultieren Sie diese für bekannte Syntaxfallen (Fußnotenplatzierung, #N-Kollisionen, Fletcher-Import, Tabellenspalten-Sizing, etc.) – und ergänzen Sie sie, wann immer eine neue Kompilierungsfehlerklasse entdeckt wird.

Kritische Syntaxregeln (Pre-Flight-Checkliste vor typst compile):

1. Fettschrift ist einfaches *wort*, niemals **wort**: Markdown-Doppelsterne erzeugen Dutzende Compiler-Warnungen (warning: no text within stars; using multiple consecutive stars has no additional effect).
2. Mathe-Modus-Zeichenfolgen benötigen Anführungszeichen: In $ ... $ schlagen mehrbuchstabige Bezeichner wie $Count=65$ oder $RTO$ fehl (unknown variable). Schreiben Sie $"Count"=65$ oder setzen Sie Code in Backticks (`Count=65`).
3. Keine LaTeX-Backslash-Operatoren in Mathe: Die Eingabe von $\approx$ schlägt fehl (unknown variable: pprox). Typst verwendet nackte Symbole: $approx$ ohne Backslash.

Tiefe Inhalte, ressourcenbewusste Präsentation

Zwei ständige Richtlinien, die jeden Bericht prägen:

1. Gehen Sie tief in die technischen Inhalte. Zielen Sie auf quälende technische Tiefe, nicht auf eine oberflächliche Zusammenfassung – mehr rohe Konsolenausgaben, mehr Architektur-/Zustandsmaschinendiagramme, Register-/Bitfeld- oder Digital-Schaltkreis-Details, wenn das Thema hardwarenah ist, CPU-Befehl-/Assembler-Details, wenn das Thema softwareausführungsnah ist. Wenn ein Entwurf bei 5-6 Seiten "fertig" wirkt, ist das ein Signal, eine Ebene tiefer zu graben (einen zusätzlichen redis-cli/systemctl/Register-Dump, ein zusätzliches Architekturdiagramm, eine zusätzliche Branchenvergleichsperspektive), nicht aufzuhören. Siehe "Tiefenerwartung" unten für die konkrete abschnittsweise Aufschlüsselung.
2. Aber seien Sie ressourcenbewusst bei der Präsentation, nicht beim Inhalt. Inhaltstiefe und Ressourcenbewusstsein bei der Gestaltung sind getrennte Achsen – gehen Sie tief in Fakten/Belege/Diagramme, aber halten Sie die visuelle Präsentation selbst tintensparsam: helle Hintergründe + farbige Ränder/Text statt Vollfarbflächen, und Farbe nur dort, wo sie Bedeutung trägt (siehe Farbschema unten). Tintensparsamkeit betrifft die Seitenkörper-Tinte, NICHT den Titelblock – der Titel IST umrahmt (siehe Farbschema Punkt 1). Mehr Seiten mit echter technischer Substanz ist das Ziel; mehr Vollfarbtinte pro Seite ist nicht.

Workflow

1. Sammeln Sie ALLE Beweise zuerst (Chat-Suchen, GitHub-PR-Lektüren, Live-Befehlsausgaben, Issue-Tracker/Chat-Vorab-Recherche), bevor Sie schreiben – beginnen Sie die .typ-Datei nicht mitten in der Recherche; synthetisieren Sie einmal.
2. Schreiben Sie die vollständige .typ-Quelle in einem oder zwei write/eval-Aufrufen, unter Verwendung der obigen Strukturvorlage (einfach umrahmter Titel mit Akzent, Akzent-Überschriften mit einer dünnen Linie, helle Tabellenkopfzeilen, semantische Hervorhebungen an 2-4 bedeutungsvollen Stellen, helle Konsolenblöcke, Fletcher-Diagramme umschlossen von #figure für Knotengraphen, standardmäßig kein Inhaltsverzeichnis). Wenn Sie Fletcher verwenden, beginnen Sie die Datei IMMER mit #import "@preview/fletcher:0.5.7": diagram, node, edge – das Weglassen dieses Imports ist der häufigste Fehler beim ersten Kompilieren.
3. Kompilieren: typst compile datei.typ (aus einem Arbeitsverzeichnis, in dem die Datei liegt – überprüfen Sie typst --version einmal pro Sitzung, um zu bestätigen, dass die Binärdatei verfügbar ist; wenn Sie Fletcher verwenden, bestätigt ein Wegwerf-/tmp-Testkompilieren die Netzwerk-/Paketauflösung, bevor Sie es in das echte Dokument einbinden). Stoßen Sie auf einen Kompilierungsfehler? Überprüfen Sie Ihre Gotchas-Notizen-Datei, bevor Sie von Grund auf debuggen.
4. Überprüfen Sie immer visuell, bevor Sie für erledigt erklären – rendern Sie jede Seite als PNG (typst compile --format png --ppi 100 datei.typ "seite-{p}.png" – setzen Sie das Ausgabemuster in Anführungszeichen) und read Sie jedes PNG, um Layout/Abstände/Rendering zu inspizieren, insbesondere jede Seite mit einem Diagramm, einer Tabelle oder einer Hervorhebung. Diagramme mit 3+ Kanten oder bidirektionalen Kantenpaaren erfordern besondere Prüfung auf Beschriftungskollisionen.
5. Dann machen Sie einen separaten INHALTS-Lese-Durchlauf – Layout-Überprüfung ist keine Inhaltsüberprüfung. Schritt 4 beweist, dass nichts falsch gerendert wird; es beweist NICHT, dass irgendetwas wahr ist. read jede gerenderte Seite erneut, diesmal lesen Sie den Text gegen das Quellmaterial und suchen Sie gezielt: (a) handgetippte Abschnittsverweise ("siehe §9.1.3"), die veraltet sind, weil ein Kapitel eingefügt wurde; (b) Tabellenzellen, deren Behauptung invertiert oder transponiert relativ zur Quelle ist; (c) Zahlen, die aus zweiter Hand statt aus dem Primärartefakt transkribiert wurden – markieren Sie diese mit [INFERENCE] oder überprüfen Sie sie. In der Praxis bestätigt notwendig: Ein Dokument, das den vollständigen Layout-Durchlauf bestanden hat, enthielt immer noch einen hängenden §-Verweis UND eine faktisch invertierte Tabellenzelle, die beide nur durch Lesen erwischt wurden. Ein 40 KB großes Dokument, das in einem Durchlauf geschrieben wurde, wurde NICHT nur deshalb Korrektur gelesen, weil es kompiliert wurde.
6. Verschieben Sie die endgültige .typ + .pdf in das docs-Verzeichnis des Projekts (z.B. docs/generated/) und committen Sie beide, löschen Sie dann alle zwischenzeitlichen PNG-Prüfdateien – bewahren Sie die Quelle zusammen mit der kompilierten Ausgabe auf, damit sie später wieder bearbeitet werden kann.

Semantische Auszeichnung verwenden

Gemäß Typsts eigener Barrierefreiheitsrichtlinie: Verwenden Sie immer das echte semantische Element (= Überschrift, #quote(...), #table(...)) anstatt einfachen Text/Prosa manuell zu gestalten, damit er aussieht wie dieses Element (z.B. #text(size: 16pt, weight: "bold")[Überschrift]). Erfinden Sie niemals eine parallele "sieht aus wie eine Überschrift"-Konvention; treiben Sie das Erscheinungsbild immer vom echten Markup-Element her.

Farbschema

• Körperschrift: New Computer Modern. Der Maßstab ist "wie LaTeX" – NCM ist der LaTeX-Look und wird mit Typst ausgeliefert, also wird es immer aufgelöst. Verwenden Sie NIE eine Schriftart, die nicht auf dem Rechner installiert ist (überprüfen Sie mit typst fonts): Typst warnt nur bei einer fehlenden Familie und fällt stillschweigend zurück, sodass das Dokument "sauber" kompiliert, während es falsch aussieht. Wenn eine unknown font family-Warnung erscheint, ist das ein zu behebender Fehler, keine zu tolerierende Warnung.
• Semantische Hervorhebungspalette. grün #1a7f37, gelb #9a6700, rot #cf222e, blau #0969da, lila #6639ba, orange #bc4c00; Konsolen-/Tabellentönungen #f2f6fb / #eaf1fb mit Rand #9fb8d6 / #c8d6e8. Inline- und Block-raw sollten eine monospace Schriftart verwenden, die auf dem Rechner vorhanden ist (z.B. Consolas, JetBrains Mono, Menlo).

Eine strukturelle Akzentfarbe, die nur für Chrome verwendet wird – plus semantische Hervorhebungsblöcke für Bedeutung. Dies ist das etablierte Muster; wenden Sie es standardmäßig an, ohne es von Grund auf neu abzuleiten:

1. Titelblock: einfacher zentrierter farbiger Text mit umrahmter Box. Verwenden Sie #box(fill: white, stroke: 1.5pt + accent, ...) um den Titel.
2. Tabellenköpfe: helle Tönungshintergrund + Akzent-farbiger Text, NIEMALS eine Vollfarbfüllung.
3. Semantische Hervorhebungsblöcke für bedeutungsvolle Ergebnisse – hier wird zusätzliche Farbe verdient, weil sie funktional und nicht dekorativ ist. Verwenden Sie diejenigen, die zum Inhalt passen; erzwingen Sie nicht alle in jedem Dokument – 2-4 Hervorhebungen insgesamt pro Bericht ist eine gute Dichte, nicht eine pro Absatz.
   • Bestätigt (grünes Häkchen) – bestätigter guter Befund, eine Zeile.
   • Anomalie (gelbes Ausrufezeichen) – unerwartet, aber noch nicht als Defekt bestätigt.
   • Bestätigter Defekt (rotes X) – bestätigter schlechter Befund, eine Zeile.
   • Hinweis (blaue Info) – eine nicht kritische Beobachtung, die hervorzuheben ist.
   • Tipp (lila Glühbirne) – ein hilfreicher Vorschlag oder eine bewährte Praxis.
   • Offene Frage (orangefarbenes Fragezeichen) – eine echte ungelöste Diskrepanz oder Anfrage.
4. Variieren Sie die Tönung nach Dokument/Abschnitt, wo sie die Drucklesbarkeit verbessert.
5. Diagramm-Box-Farben bleiben rollenbasiert/semantisch.
6. Keine großen, durchgehenden, dunklen Farbflächen irgendwo (z.B. ein volles dunkelblaues Banner mit weißem Text). Abschnittsüberschriften: farbiger Text + eine dünne farbige Linie darunter, keine gefüllte Farbband- oder Box.
7. Konsolen-/Code-Ausgabeblöcke: hell getönter Hintergrund, nicht grau. Ein flaches #f4f4f4-Grau wirkt langweilig/kopiererhaft. Verwenden Sie eine helle Tönung mit einem dezenten passenden Rand.
8. Verwenden Sie NIE #pagebreak() zwischen Kapiteln. Ein Umbruch vor jeder =-Überschrift hinterlässt eine halbe Seite Leerpapier pro Kapitel und verschwendet echte Blätter beim Drucken. Lassen Sie Abschnitte fließen; ein neues Kapitel, das mitten auf der Seite beginnt, ist RICHTIG. Der einzige akzeptable #pagebreak() ist der einzelne, der die Titelseite vom Körper trennt.

Zwei Standardabschnitte – fügen Sie sie unaufgefordert hinzu

• Wettbewerbsbezogener/Industriekontext. Wie lösen die Alternativen dieses Problem, und was kauft und kostet diese architektonische Position strukturell? Rahmen Sie jeden Vorteil als entsprechendes testbares Risiko ein. Kennzeichnen Sie den Abschnitt als allgemeines Branchenwissen mit [INFERENCE], es sei denn, er stammt aus einem echten Wettbewerbsdokument.
• Das Automatisierungs-/Test-Harness, konkret. Exakte Aufrufe, Runner-Host, venv und fixierte Abhängigkeiten, Marker-Auswahl und wie man gesammelte vs. deselektierte vs. ausgeführte Zählungen liest. "Es gibt eine Suite" ist keine Abdeckung.

Abbildungsplatzierung: Diagramme/Tabellen in #figure(...) einwickeln, lassen Sie Typst sie floaten

Gemäß Typsts eigener Layout-Anleitung: Abbildungen werden standardmäßig inline innerhalb des Inhaltsflusses platziert, aber das Einwickeln eines Diagramms oder einer Tabelle in #figure(..., caption: [...]) ermöglicht placement: top/placement: bottom, damit Typst es an den oberen/unteren Rand der Seite floaten kann, anstatt den Inhalt ungeschickt darum herum mitten im Absatz zu teilen. Geben Sie Diagrammen immer einen #figure(...)-Wrapper mit einer echten Bildunterschrift (niemals einen nackten #diagram(...)-Aufruf, der im Text schwimmt) – dies ermöglicht auch die Querverweisbarkeit des Diagramms über @sec-label und gibt Bildschirmlesern/Wiederverwendungswerkzeugen eine ordentliche semantische Figure+Bildunterschrift-Paarung, nicht nur ein unbeschriftetes Bild.

Fletcher für Knoten/Kantendiagramme

Arbeitsmuster, bestätigt kompilieren und korrekt rendern (eingewickelt in #figure gemäß der Platzierungsrichtlinie oben). Denken Sie an den Import (siehe Workflow-Schritt 2) – dieses Snippet setzt voraus, dass er bereits oben in der Datei ist:

#figure(
  diagram(
    node-stroke: 0.6pt,
    spacing: (3em, 2em),
    node((0,0), [Schritt 1], fill: rgb("#dbe9ff"), corner-radius: 4pt),
    node((0,1), [Schritt 2], fill: rgb("#dbe9ff"), corner-radius: 4pt),
    edge((0,0), (0,1), "-|>", bend: 10deg),
    edge((0,1), (0,0), "-|>", bend: 10deg),
  ),
  caption: [Einzeilige Bildunterschrift, die beide Richtungen/Kanten erklärt, da Inline-Beschriftungen hier weggelassen wurden.],
)

Koordinaten sind (Spalte, Zeile)-Tupel; node-stroke/fill/corner-radius gestalten einzelne Knoten; edge(von, nach, "-|>") zeichnet einen Pfeil (die Markierungszeichenfolge, kein Keyword-Argument, wählt die Pfeilspitze aus – "-|>" und "->" funktionieren beide; "..|>" für einen gepunkteten Pfeil). Mehrere unabhängige Ketten können einen diagram(...)-Aufruf teilen, indem sie unterschiedliche Spaltenindizes pro Kette plus einen Kopfzeilenknoten mit stroke: none pro Kette verwenden. Halten Sie Kantenbeschriftungen kurz (ein Wort/eine Phrase) und verschieben Sie die vollständige Erklärung in die caption der Abbildung – Inline-Kantenbeschriftungen, die länger als ein Wort sind, sind der klassische Beschriftungskollisionsfehler.

Tiefenerwartung: Standardmäßig lange Form, Nerdesk tief, keine Zusammenfassung

Sofern nicht explizit etwas Kurzes verlangt wird, zielen Sie auf 10-12 gerenderte Seiten für eine vollständige Untersuchungsdokumentation – ein kurzer, korrekter aber dünner Bericht ist ein Fehlermodus, kein effizientes Ergebnis. Konkret bedeutet "tief gehen", wo immer das Thema es zulässt:

• Volle rohe Konsolen-/Log-Ausgaben, nicht abgeschnittene Ausschnitte – tatsächlicher Befehl + tatsächliche Ausgabe, wortwörtlich, für jede Behauptung, die aus Live-System-Evidenz stammt.
• Mindestens ein Architektur- oder Zustandsmaschinendiagramm (über Fletcher, siehe oben), das zeigt, wie die Teile tatsächlich zusammenhängen, nicht nur Prosa, die es beschreibt.
• Register-/Bitfeld- oder Digital-Schaltkreis-Details, wenn das Thema hardwarenah ist (z.B. das Bit-Layout eines bestimmten Konfigurationsregisters, ein Signal-Timing-Diagramm, die Port-Mapping-Tabelle eines ASIC-Blocks, reale Struct-/Opcode-Definitionen aus dem tatsächlichen Treiberquelltext) – hören Sie nicht bei "die Hardware macht X" auf, zeigen Sie den tatsächlichen Mechanismus.
• CPU-Befehl/Assembler- oder Syscall-Details, wenn das Thema softwareausführungsnah ist (z.B. welchen Syscall ein Treiber tatsächlich ausführt, wie die Disassemblierung des Hot Paths aussieht) – hören Sie nicht bei "der Treiber macht X" auf, zeigen Sie den tatsächlichen Codepfad.
• Ein eigener Branchen-/Externer-Kontext-Abschnitt (siehe unten) – präsentieren Sie niemals einen internen Mechanismus isoliert.
• Echte Vorab-Recherche/Historie – überprüfen Sie den Issue-Tracker, Chat-Verlauf und Git-Verlauf, ob diese genaue Frage schon einmal gestellt wurde (auch Jahre zuvor); ein Bericht, der eine mehrjährige offene Frage schließt, ist ein stärkerer Beleg als einer, der einen Befund als brandneu behandelt.

Struktur: (1) Titel + Executive Summary, (2) Hintergrund, (3) Beweiszeitplan/Methodik – ein Unterabschnitt pro eindeutigem Befund mit eigenem Zitatblock, normalerweise der längste Abschnitt, (4) Disambiguierungsabschnitt, wenn der Name des Themas mit etwas anderem überlappt, (5) Vergleichstabellen, (6) Branchen/externer Kontext, (7) Architektur/Synthese als nummerierte Ende-zu-Ende-Liste gepaart mit Diagrammen, (8) Offene Fragen mit konkreten Folgemaßnahmen, (9) Verbindung zur ursprünglichen Untersuchung, (10) Anhang mit vollständigen rohen Beweisen, die aus dem Hauptteil entfernt wurden. Wenn ein Entwurf sich fertig anfühlt, aber kurz ist, machen Sie eine weitere echte Rechercherunde (eine weitere Live-Überprüfung, einen weiteren Register-Dump, eine weitere Websuche, ein weiteres Diagramm, eine weitere Historiensuche nach Vorarbeiten), anstatt vorhandene Prosa aufzublähen – Tiefe muss aus echtem Inhalt kommen, niemals aus Wiederholungen oder Ausführlichkeit.