brmdias/best-practice

Skill zur Dokumentation von Best Practices

Automatisiert den gesamten Workflow zur Dokumentation von Best Practices in der TAM-Wissensdatenbank und reduziert 2–4 Stunden manuelle Arbeit auf 10–15 Minuten.

Verwendung

/best-practice <Themenname>
/bp <Themenname>

Beispiele:

• /bp webhook-timeout-patterns
• /best-practice runner-disk-management
• /bp ansible-integration-patterns

Was dieser Skill tut

Führt den gesamten Workflow zur Dokumentation von Best Practices aus:

1. Validieren & auf Vorhandenes prüfen – Doppelte vermeiden, Aktualisierungen handhaben
2. Wissensdatenbank durchsuchen – Ähnliche Untersuchungen, Best Practices, Kundenbeispiele finden
3. Dokumentation durchsuchen – Offizielle Leitfäden und Versionsinformationen finden
4. Produktcode durchsuchen – Technische Details und Standardwerte überprüfen (wenn relevant)
5. GitHub durchsuchen – Community-Issues, Fehler und Funktionsanfragen finden
6. Jira durchsuchen – Interne Entwicklungstickets und Fix-Versionen lokalisieren
7. Community-Suche – Externe Quellen per WebFetch abrufen (optional)
8. Ergebnisse synthetisieren – Forschungszusammenfassung zur Benutzerbestätigung präsentieren
9. Dokument generieren – Best Practice gemäß TEMPLATE.md-Struktur erstellen
10. INDEX.md aktualisieren – Zu Kategorien, alphabetischer Tabelle und Kurzreferenz hinzufügen
11. Abschluss melden – Umfassende Zusammenfassung mit nächsten Schritten

Anweisungen

Wenn dieser Skill aufgerufen wird, folge diesen Schritten:

Schritt 1: Argumente parsen & validieren

Extrahiere den Themennamen aus den Argumenten:

• Erforderlich: Themenname (z. B. „webhook-timeout-patterns“)
• In Kebab-Case konvertieren, falls nicht bereits
• Wenn das Thema >80 Zeichen ist, warnen: „Thema scheint breit gefasst. Teilen erwägen?“

Wenn kein Thema angegeben:

• Fehler: „Verwendung: /best-practice “
• Beispiele zeigen

Schritt 2: Auf vorhandene Best Practice prüfen

Suche nach vorhandenen Best Practices mit ähnlichen Namen:

Glob pattern="*${Stichwörter}*" path="best-practices/"

Entscheidungslogik:

• Exakte Übereinstimmung: Benutzer fragen: „Best Practice existiert unter <file>. (1) Vorhandene aktualisieren, (2) Neue mit anderem Fokus erstellen, (3) Abbrechen?“
• Teilweise Übereinstimmungen: Auflisten, fragen: „Ähnliche gefunden: <files>. (1) Eine aktualisieren, (2) Neue erstellen, (3) Abbrechen?“
• Keine Übereinstimmungen: Mit Erstellung fortfahren

Wenn der Benutzer Aktualisierung wählt, Dateiname für spätere Bearbeitung statt Neuschreiben notieren.

Schritt 3: Wissensdatenbank durchsuchen

Suchschlüsselwörter aus Themennamen extrahieren (Bindestriche entfernen, in Begriffe aufteilen).

Best Practices durchsuchen:

Grep pattern="<Stichwörter>" path="best-practices/" output_mode="content" -C 3 head_limit=50

Untersuchungen durchsuchen:

Grep pattern="<Stichwörter>" path="investigations/" output_mode="content" -C 3 head_limit=50

Kundenprofile durchsuchen (wenn relevant):

Grep pattern="<Stichwörter>" path="customers/" output_mode="files_with_matches"

Wenn Kundenprofile gefunden werden, diese lesen, um Kontext zu sammeln.

Sammeln und notieren:

• Verwandte Best Practices (für den Abschnitt „Verwandte Best Practices“)
• Untersuchungsbeispiele (für den Abschnitt „Beispiele aus der Praxis“)
• Häufige Tags aus ähnlichen Dokumenten (für Metadaten)
• Kundenkontext, falls zutreffend

Schritt 4: Offizielle Dokumentation durchsuchen

Grep pattern="<Stichwörter>" path="repositories/docs/" output_mode="content" -C 2 head_limit=30

Sammeln und notieren:

• Offizielle Leitfäden und Empfehlungen
• Versionsspezifische Informationen
• Konfigurationsreferenzen und -optionen
• Bekannte Einschränkungen oder Vorbehalte

Schritt 5: Produktcode durchsuchen (bedingt)

Wann durchsuchen:

• Thema betrifft bestimmtes Feature-Verhalten
• Standardkonfigurationswerte werden benötigt
• Verständnis der Leistungsmerkmale
• Technische Einschränkungen überprüfen

Grep pattern="<Komponente|Klasse>" path="repositories/rundeckpro/" output_mode="content" head_limit=30

Sammeln und notieren:

• Standardkonfigurationswerte
• Implementierungsdetails und -verhalten
• Technische Einschränkungen oder Grenzwerte
• Versionsspezifische Logik

Schritt 6: GitHub Issues durchsuchen (über Runlayer-Connector)

GitHub über den Runlayer-Connector abfragen – die gh-CLI ist in dieser Umgebung nicht verfügbar. Rufe search_tools auf, um das GitHub-Issue-Suchwerkzeug zu finden, dann execute_tool, um rundeck/rundeck und rundeckpro/rundeckpro nach <Stichwörter> in offenen und geschlossenen Issues zu durchsuchen. Verwende nicht die Shell für gh.

Sammeln und notieren:

• Bekannte Probleme oder Fehler
• Funktionsanfragen und Community-Feedback
• Workarounds und Community-Lösungen
• Issue-Nummern für Zitate

Wenn der GitHub-Connector nicht verfügbar ist, notieren und fortfahren.

Schritt 7: Jira RUN-Projekt durchsuchen (über Runlayer-Connector)

Jira über den Runlayer-Connector abfragen. Rufe search_tools auf, um das Jira-Issue-Suchwerkzeug zu lokalisieren, dann execute_tool mit dem genauen tool_name und den zurückgegebenen Argumenten. Rufe nicht direkt mcp__atlassian__*-Werkzeuge auf. Verwende Parameter entsprechend:

jql: "project=RUN AND (summary ~ "<Stichwörter>" OR description ~ "<Stichwörter>") ORDER BY updated DESC"
maxResults: 15

Sammeln und notieren:

• Interne Entwicklungstickets
• Fix-Versionen und Release-Informationen
• Entwicklungsstatus und Kontext
• Jira-Keys für Zitate (RUN-XXXX)

Fehlerbehandlung: Wenn der Jira-Connector nicht verfügbar ist, „Jira-Suche nicht verfügbar“ notieren und fortfahren.

Schritt 8: Community-Suche (optional/nach Bedarf)

Auslösen, wenn:

• Weniger als 3 relevante Quellen in Schritten 3-7 gefunden wurden
• Neuartiges oder aufkommendes Muster, das nicht gut dokumentiert ist
• Benutzer breitere Recherche wünscht

WebFetch mit Parametern:
  url: "https://groups.google.com/g/rundeck-discuss/search?q=<Stichwörter>"
  prompt: "Finde Diskussionen über <Thema>. Extrahiere: gemeldete Probleme, vorgeschlagene Lösungen, empfohlene Muster, häufige Probleme"

Sammeln und notieren:

• Community-Lösungen und -Muster
• Häufige Fallstricke und Probleme
• Implementierungsvarianten
• Wichtig: Unbestätigte Behauptungen kennzeichnen, gegen offizielle Dokumente verifizieren

Schritt 9: Ergebnisse synthetisieren & Benutzerbestätigung einholen

Alle Forschungsergebnisse analysieren:

1. Muster identifizieren über Quellen hinweg
2. Empfehlung bestimmen: Primärer Ansatz mit Begründung
3. Alternativen identifizieren: Andere Ansätze und warum primär bevorzugt wird
4. Implementierung extrahieren: Schritt für Schritt mit Codebeispielen
5. Vorteile und Abwägungen dokumentieren
6. Metadaten auswählen:
   • Produktbereich: Aus diesen Kategorien bestimmen:
     • 🎯 Auftragsdesign & Orchestrierung
     • 🖥️ Knotenverwaltung & Zielauswahl
     • 🔐 Sicherheit & Zugriffskontrolle
     • 📊 Leistung & Skalierung
     • 🔗 Integrationen & Webhooks
     • 🏗️ Architektur & Bereitstellung
     • 📝 Dokumentation & Wartung
   • Gilt für Version: Aus Jira/Docs (spezifisch wie „Rundeck 5.6.0+" oder konservativ „Alle Versionen“)
   • Tags: Vorhandene Taxonomie aus ähnlichen BPs verwenden (Tags aus Schritt 3 scannen), maximal 3-8 Tags

Forschungszusammenfassung dem Benutzer präsentieren:

# Forschungszusammenfassung: <Themenname>

## Gefundene Quellen
- Wissensdatenbank: X Untersuchungen, Y Best Practices
- Dokumentation: N Seiten
- GitHub: P Issues
- Jira: Q Tickets
- Community: [wenn durchsucht]

## Empfohlener Ansatz
[1-2 Absätze Zusammenfassung der primären Empfehlung basierend auf der Recherche]

## Wichtigste identifizierte Muster
- [Muster 1 aus Recherche]
- [Muster 2 aus Recherche]
- [Muster 3 aus Recherche]

## Vorgeschlagene Metadaten
- **Produktbereich:** [bestimmte Kategorie]
- **Gilt für Version:** [Version aus Recherche]
- **Tags:** #tag1 #tag2 #tag3 [aus ähnlichen BPs]

## Qualitätsprüfung
- ✓ [X] Quellen gefunden (mindestens 4 empfohlen)
- ✓ [Y] Code-/Konfigurationsbeispiele verfügbar
- ✓ [Z] Beispiele aus der Praxis gefunden

Bereit zur Dokumentenerstellung?

Auf Benutzerbestätigung warten. Benutzer kann:

• Bestätigen und fortfahren
• Änderungen an Metadaten oder Ansatz anfordern
• Zusätzliche Recherche anfordern
• Den Workflow abbrechen

Ohne Benutzerbestätigung NICHT mit der Generierung fortfahren.

Schritt 10: Best-Practice-Dokument generieren

Sobald der Benutzer bestätigt, das Dokument generieren:

1. Vorlage als Referenz lesen:

Read file_path="best-practices/TEMPLATE.md"

2. Alle Abschnitte mit recherchierten Inhalten befüllen:

Kopfzeile (Zeilen 1-6):

# [Themenname in Titelform]

**Zuletzt aktualisiert:** 2026-04-20
**Produktbereich:** [aus Schritt 9]
**Gilt für Version:** [aus Schritt 9]
**Tags:** #tag1 #tag2 #tag3 [aus Schritt 9]

---

Anwendungsfall / Szenario:

• Beschreiben, wann jemand dies benötigt (aus Untersuchungen + Dokumentation)
• Welches Problem löst es?
• Für welche Szenarien ist dies relevant?

Empfehlung:

• Klare, umsetzbare Anleitung (das „Was tun“)
• Primärer Ansatz aus Synthese
• Kann eine Tabelle enthalten, wenn mehrere Optionen

Implementierung:

• Schritt-für-Schritt-Anleitung
• Mehrere Muster, falls zutreffend (Muster 1, Muster 2, usw.)
• Codebeispiele aus Dokumentation und Coderecherche

# Tatsächliche YAML-/Konfigurationsbeispiele einfügen
# In der Recherche gefundene Code-Snippets verwenden

Warum dies funktioniert:

• Technische Erklärung aus Code + Dokumentationsrecherche
• Zugrundeliegende Prinzipien oder Mechanismen
• Warum dieser Ansatz effektiv ist

Vorteile:

• Nummerierte Liste aus Forschungsergebnissen
• Konkrete Vorteile (Leistung, Sicherheit, Wartbarkeit, usw.)
• Wenn möglich quantifizieren

Abwägungen / Vorbehalte:

• In der Recherche identifizierte Einschränkungen
• Leistungsüberlegungen
• Situationen, in denen dies möglicherweise nicht zutrifft
• ⚠️ Widersprüchliche Informationen kennzeichnen, falls gefunden

Alternativen in Betracht gezogen:

• Andere in der Recherche gefundene Ansätze
• Warum der empfohlene Ansatz bevorzugt wird
• Wann Alternativen besser sein könnten

Beispiele aus der Praxis:

• Links zu Untersuchungen: [Kunde/Fall](../investigations/YYYY-MM-DD-beschreibung.md)
• Wenn keine: „Keine Untersuchungen dokumentiert. Diese Best Practice basiert auf [offiziellen Dokumenten/Codeanalyse/Community-Mustern].“

Verwandte Best Practices:

• Links zu verwandten Dokumenten aus KB-Suche
• Format: [Titel](./dateiname.md) - Kurzbeschreibung

Offizielle Dokumentation:

• Links zu Docs-Repo-Dateien
• GitHub Issues nach Nummer
• Jira-Tickets nach Key
• Offizielle Website-Links

3. Qualitätsprüfungen vor dem Schreiben:

• ✓ Alle 4 Metadatenfelder ausgefüllt
• ✓ 3-8 Tags aus vorhandener Taxonomie
• ✓ Alle Vorlagenabschnitte vorhanden
• ✓ Mindestens 1 Code-/Konfigurationsbeispiel
• ✓ Mindestens 2 Quellen zitiert
• ✓ Korrekte Markdown-Formatierung

4. Das Dokument schreiben:

Wenn neu erstellt:

Write file_path="best-practices/<Kebab-Themenname>.md" content="<generierter-Inhalt>"

Wenn vorhanden aktualisiert (aus Schritt 2):

Edit file_path="best-practices/<vorhandener-Dateiname>.md"

Relevante Abschnitte aktualisieren, dabei Struktur beibehalten.

Schritt 11: INDEX.md aktualisieren

1. Aktuellen INDEX lesen:

Read file_path="best-practices/INDEX.md"

2. Primäre Kategorie bestimmen aus diesen Optionen (Emoji genau wie gezeigt verwenden):

   • 🎯 Auftragsdesign & Orchestrierung
   • 🖥️ Knotenverwaltung & Zielauswahl
   • 🔐 Sicherheit & Zugriffskontrolle
   • 📊 Leistung & Skalierung
   • 🔗 Integrationen & Webhooks
   • 🏗️ Architektur & Bereitstellung
   • 📝 Dokumentation & Wartung

3. Drei Abschnitte mit dem Bearbeitungswerkzeug aktualisieren:

a) Kategorieabschnitt: Die entsprechende Kategorie finden (z. B. „### 🎯 Auftragsdesign & Orchestrierung") und Eintrag hinzufügen:

- [Titel](./dateiname.md) - Einzeilige Beschreibung #tag1 #tag2 #tag3

Alphabetisch innerhalb der Kategorie einfügen.

b) Tabelle „Alle Best Practices (alphabetisch): Richtige alphabetische Position finden und einfügen:

| [Titel](./dateiname.md) | Kategorie [& Sekundäre Kategorien, falls zutreffend] | 2026-04-20 | [Verwandte Fälle oder „N/A"] |

c) Abschnitt „Kurzreferenz nach Anwendungsfall:“ 2-4 Einträge „Ich muss...“ hinzufügen, die häufige Anwendungsfälle widerspiegeln:

- **...bestimmtes Problem/Aufgabe** → [Titel](./dateiname.md)

Alphabetisch sortiert halten.

4. Datum „Zuletzt aktualisiert“ aktualisieren: Das Datum oben ändern:

**Zuletzt aktualisiert:** 2026-04-20

5. Aktualisierungen mit dem Bearbeitungswerkzeug durchführen: Bearbeitung für jede Änderung verwenden (oder kombinieren, wenn sie nahe beieinander liegen):

Edit file_path="best-practices/INDEX.md" old_string="<vorhandener-Text>" new_string="<aktualisierter-Text>"

Schritt 12: Abschluss melden

Umfassende Abschlusszusammenfassung bereitstellen:

✅ Best Practice erfolgreich erstellt!

## Dokumentdetails
**Titel:** [Vollständiger Titel]
**Datei:** best-practices/<dateiname>.md
**Kategorie:** [Primäre Kategorie]
**Tags:** #tag1 #tag2 #tag3

## Forschungszusammenfassung
- Wissensdatenbank: X Untersuchungen, Y Best Practices
- Dokumentation: N Seiten
- GitHub: P Issues
- Jira: Q Tickets
- Community: [wenn durchsucht]
- **Quellen insgesamt:** [Anzahl]

## Abgeschlossene Dokumentabschnitte
✓ Anwendungsfall / Szenario
✓ Empfehlung mit [Anzahl] Mustern
✓ Implementierung mit [Anzahl] Codebeispielen
✓ Warum dies funktioniert
✓ [Anzahl] Vorteile aufgelistet
✓ [Anzahl] Abwägungen dokumentiert
✓ [Anzahl] Alternativen in Betracht gezogen
✓ Beispiele aus der Praxis: [Links oder „Dokumentation ausstehend"]
✓ [Anzahl] verwandte Best Practices verlinkt
✓ [Anzahl] Referenzen zur offiziellen Dokumentation

## INDEX.md aktualisiert
✓ Zu [Kategorienname] hinzugefügt
✓ Zur alphabetischen Tabelle hinzugefügt (Zeile [N])
✓ [Anzahl] Kurzreferenzeinträge hinzugefügt
✓ Datum „Zuletzt aktualisiert" aktualisiert

## Nächste Schritte
1. Dokument überprüfen unter: best-practices/<dateiname>.md
2. Implementierung ggf. in der Sandbox testen
3. Mit Team teilen: `/share-kb "<titel>" best-practices/<dateiname>.md`
4. Ggf. von relevanten Kundenprofilen verlinken

Wenn dies eine Aktualisierung statt einer Neuerstellung war:

✅ Best Practice erfolgreich aktualisiert!

## Aktualisiertes Dokument
**Titel:** [Vollständiger Titel]
**Datei:** best-practices/<dateiname>.md
[restliche Zusammenfassung an Aktualisierungsszenario angepasst]

Qualitätsrichtlinien

Forschungsqualität

• Mindestens 4 Quellenkategorien durchsuchen (WB, Dokumentation, Code, externe Tracker)
• Konkrete Dateipfade für Code-/Dokumentationsreferenzen angeben
• Auf GitHub Issues nach Nummer verlinken (#1234)
• Auf Jira-Tickets nach Key verlinken (RUN-1234)
• Community-Behauptungen gegen offizielle Quellen verifizieren
• Unbestätigte oder widersprüchliche Informationen kennzeichnen

Dokumentqualität

• Klarheit: Jeder Abschnitt sofort umsetzbar oder informativ
• Vollständigkeit: Alle Vorlagenabschnitte ausgefüllt (keine TODOs)
• Evidenzbasiert: Alle Empfehlungen durch Quellen gestützt
• Praktisch: Echte Code-/Konfigurationsbeispiele enthalten, nicht nur Text
• Ehrlich: Abwägungen und Vorbehalte dokumentieren