hec-ovi/research-skill

Research

Persistenter, projektbezogener Speicher für tiefgehende Rechercheergebnisse. Du hast diese Skill aktiviert, weil der Benutzer eine substantielle Recherchefrage gestellt oder sie explizit mit /research <Thema> aufgerufen hat.

Wird die Skill mit einem Themenargument aufgerufen (z.B. /research tailwind-v5), verwende es als Ausgangspunkt für den Abruf – suche zunächst in INDEX.md nach diesem Thema. Recherchiere nicht blind; die Suche kann die Frage sofort beantworten.

Wann verwenden

• "Was ist das neueste npm-Paket, das X macht"
• "Vergleiche A vs B vs C für 2026"
• "Welche Engines / Frameworks / Bibliotheken können X schnell klonen"
• "Recherchiere, wie Y unter der Haube funktioniert"
• "Tiefer Einblick in Z"
• Benutzer fügt einen langen Markdown-Forschungsdump ein und bittet dich, ihn zu speichern

Wann NICHT verwenden

• Notizen in der Planungsphase
• Kleine Fakten oder einzeilige Präferenzen
• Code-Entscheidungen, die an eine einzelne Datei gebunden sind
• Einfache Nachfragen, die aus einer einzigen Quelle ohne Synthese beantwortet werden können
• Persönliche Ideen oder Gedanken festhalten
• Als Ersatz für eine einzelne WebSearch oder WebFetch

Wenn eine einzelne WebSearch + 1-2 Sätze die Frage beantworten, brauchst du diese Skill nicht.

Einrichtung (nur bei erster Nutzung)

Bei der ersten Aktivierung in einem Projekt führe dies einmal durch:

1. Projektstamm ermitteln: git rev-parse --show-toplevel 2>/dev/null || pwd

2. Erstelle <root>/.research/, falls nicht vorhanden

3. Erstelle <root>/.research/INDEX.md mit genau diesem Inhalt:

   # Forschungsindex
   
   | Thema | Pfad | Zuletzt überprüft | Kurzbeschreibung |
   |---|---|---|---|
   

4. Füge .research/ zu <root>/.gitignore hinzu. Falls .gitignore nicht existiert, erstelle es. Forschungsdaten können proprietäre Erkenntnisse enthalten, standardmäßig privat.

Die Daten befinden sich unter <root>/.research/ (neben .claude/, nicht darin verschachtelt). Es ist ein top-level Projektverzeichnis, das so gewählt wurde, dass Forschungsdaten zusammen mit dem Projekt abgelegt, standardmäßig von Git ignoriert und leicht auffindbar sind. Die Überprüfung bleibt intakt: Jeder Lese- und Schreibvorgang durchläuft das normale Berechtigungssystem des Hosts.

Arbeitsablauf

1. Abruf (die Leseseite – so spart die Skill deinen Kontext)

Der Sinn dieses Systems ist die progressive Offenlegung: Lade nicht, was du nicht brauchst. INDEX.md ist dein Verteiler – es erlaubt dir zu entscheiden, welche Einträge du laden möchtest, ohne dass du sie laden musst. Gehe die Hierarchie von der günstigsten zur teuersten Stufe durch; eskalieren nur, wenn die vorherige Stufe die Frage nicht beantwortet.

Ladehierarchie (günstigste → teuerste)

Stufe	Laden	Ungefähre Tokens	Wann
1	INDEX.md (immer)	~100-500	Bei jedem Abruf – deine Routingtabelle
2	Nur die ## Summary des Eintrags	~50-200	Wenn der Index ein passendes Thema anzeigt
3	Vollständiger FINDINGS.md-Text	~500-3000	Wenn die Zusammenfassung die Frage nicht abdeckt
4	Bestimmtes raw/<Datei>-Dokument	variiert (oft groß)	Wenn ein Ergebnis darauf verweist und du eine Behauptung überprüfen musst
5	Querverwiesener Eintrag (related:)	wiederholt Stufen 2-3	Wenn die Frage mehrere Einträge betrifft

Suchvorgang

1. Lies zuerst INDEX.md (Stufe 1). Scanne die Kurzbeschreibungsspalte anhand der Benutzerfrage. Dies ist der Verteiler – dieselbe Rolle wie RESOLVER.md in GBrain.

2. Entscheidung über Übereinstimmung:

   • Starke Übereinstimmung – die Kurzbeschreibung eines Eintrags deckt das Thema klar ab → gehe mit diesem Eintrag zu Schritt 3.
   • Mehrere plausible Übereinstimmungen – lade die ## Summary jedes Eintrags (immer noch günstig auf Stufe 2). Wähle diejenigen aus, die tatsächlich antworten.
   • Schwache / keine Übereinstimmung → falle durch zur Untersuchung. Ein neuer Eintrag wird hinzugefügt.

3. Lies nur die ## Summary des passenden Eintrags (Stufe 2):

   sed -n '/^## Summary/,/^## /p' <root>/.research/<slug>/FINDINGS.md
   

   Reicht normalerweise aus.

4. Eskaliere nur dann um eine Stufe, wenn nötig:

   • Frage benötigt Details auf Behauptungsebene über die Zusammenfassung hinaus → lade den vollständigen FINDINGS.md-Text (Stufe 3).
   • Frage ist "haben wir X schon einmal ausprobiert / was wurde verworfen?" → sed nur diesen Abschnitt: sed -n '/^## Discarded approaches/,/^## /p' <root>/.research/<slug>/FINDINGS.md. Lade nicht den Rest.
   • Frage bezieht sich auf eine zitierte Behauptung aus einem Dump → öffne die entsprechende Datei unter raw/ (Stufe 4).
   • Frage erstreckt sich über Themen, die in verschiedenen Einträgen behandelt werden → folge related:, wiederhole Stufen 2-3 für jeden.

5. Durchfall zur Untersuchung. Wähle den Modus:

   • Kein Eintrag vorhanden in INDEX.md → Untersuchung im Modus "Neuer Eintrag".
   • Vorhandener Eintrag beantwortet die Frage nicht tatsächlich (Problem ungelöst) → Untersuchung im Modus "Zusammenführung" (übergebe den vorhandenen Eintragsinhalt an den Subagenten).
   • Vorhandener Eintrag ist veraltet bei einem sich schnell ändernden Thema → Untersuchung im Modus "Zusammenführung" (aktualisieren, nicht zitieren).

Was NIEMALS zu tun ist

• Lade nicht alles. Das Schema existiert, damit du selektiv sein kannst.
• Lade nicht den vollständigen Text, wenn die Zusammenfassung ausreicht. Wenn 3 Zeilen die Frage beantworten, ziehe nicht 300.
• Lade keine Rohdokumente spekulativ. Sie sind groß; die meisten Fragen brauchen sie nicht.
• Lies keinen Eintrag erneut, den du bereits in dieser Sitzung geladen hast – es sei denn, er wurde seitdem aktualisiert.

INDEX.md als Verteiler

INDEX.md existiert nur, damit du entscheiden kannst, welche Einträge du laden möchtest, ohne sie laden zu müssen. Die Kurzbeschreibungsspalte ist das gesamte Signal, das du hast, bevor du für einen Eintragslauf bezahlst – schreibe sie beim Speichern spezifisch.

Halte INDEX.md knapp: unter ~100 Zeilen. Wenn es darüber hinauswächst, bereinige oder archiviere. Das gesamte Tokenspar-Design bricht zusammen, wenn INDEX.md selbst zur Blähungsquelle wird.

2. Untersuchung (wenn neue Recherche erforderlich ist)

Starte einen general-purpose Subagenten mit model: "opus" und run_in_background: true. Die Untersuchungsphase benötigt ein starkes Modell: Die konträre Prüfung und die Syntheseschritte hängen von der Argumentationstiefe ab, die kleinere Modelle nicht liefern werden. Der Hintergrundmodus hält die Konversation interaktiv: Der Benutzer kann während der Recherche weiterarbeiten. Die Speicherung erfolgt asynchron, wenn die Abschlussbenachrichtigung des Agenten eintrifft.

Der Subagent führt die Recherche durch und gibt seine Synthese als strukturierten Text zurück. Er schreibt KEINE Dateien. Du (Hauptagent) führst alle Dateischreibvorgänge in der Speicherung durch. Diese Trennung hält die Verantwortlichkeiten sauber: Der Subagent hat null Kontext und muss dein Schema oder INDEX.md-Layout nicht kennen.

Namenskonvention. Setze den description-Parameter des Agent-Tools auf Research investigation: <Thema> (3 bis 5 Wörter). Dies macht Forschungsskill-Aufrufe in der Benutzeroberfläche des Harnesses identifizierbar.

Bei Abschlussbenachrichtigung: Analysiere die Rückgabe des Agenten, wende sofort die Speicherung an, gib dem Benutzer eine kurze Meldung (z.B. "Recherche zu <Thema> unter <Pfad> gespeichert"). Gib die vollständigen Ergebnisse nicht in den Chat, es sei denn, du wirst darum gebeten.

Subagenten haben null vorherigen Kontext. Sie sehen diese Skill, CLAUDE.md oder unsere Konversation nicht. Weise sie vollständig ein. Es gibt keine Fortsetzung in diesem Harness – das SendMessage-Tool zur Wiederaufnahme eines Agenten ist nicht verfügbar. Nur ein einmaliger Aufruf. Wenn Lücken bleiben, starte erneut mit einer verfeinerten Aufgabenstellung.

Der Modus (neuer Eintrag vs. Zusammenführung) wurde in der Abrufphase 5 entschieden. Weise den Subagenten entsprechend ein:

• Modus "Neuer Eintrag" – Standardaufgabenstellung, kein bestehender Kontext einzuspeisen.
• Modus "Zusammenführung" – Füge die ## Summary und alle relevanten Abschnitte der ## Findings des bestehenden Eintrags in die Aufgabenstellung ein, gekennzeichnet als "aktueller Stand des Eintrags – überprüfen, aktualisieren oder ersetzen". Sage dem Subagenten, er solle Behauptungen markieren, die jetzt falsch sind.

Aufgabencheckliste

Jede Untersuchungsaufgabenstellung MUSS enthalten:

• Präambel "Du hast null vorherigen Kontext"
• Das tatsächliche heutige Datum (führe zuerst date +%Y-%m-%d aus; übergib den literal String)
• Jahres-Pinning-Regel für WebSearch-Abfragen (vertraue nicht dem Modellvorwissen des Subagenten, welches Jahr wir haben)
• Mindestens 2 unabhängige Quellen pro nicht-trivialer Behauptung. Quellen werden in einem einzelnen ## Sources-Block am Ende der Rückgabe gesammelt; zitiere NICHT inline.
• Die kognitiven Phasen unten als explizite nummerierte Schritte
• Das erforderliche Ausgabeformat des Subagenten (unten)
• Die strikte keine-[n]-/keine-Inline-URL-Regel für den Findings-Text (siehe Erforderliches Ausgabeformat)
• Nur Zusammenführungsmodus: den Inhalt des bestehenden Eintrags, den der Subagent überprüfen/ersetzen soll

Kognitive Phasen (wörtlich in die Subagentenaufgabenstellung einfügen)

Der Subagent durchläuft diese als diskrete Phasen. Phase 4 ist tragend:

1. Zerlegen – Liste der Teilbehauptungen, die die Frage beantworten würden; identifiziere, welche Beweise jede klären.
2. Sammeln – Finde für jede Teilbehauptung ≥2 unabhängige Quellen (jahresgepinnte WebSearch → WebFetch auf die Top-Ergebnisse). Zitiere wörtlich. Synthetisiere noch nicht.
3. Validieren – Leite Zahlen, Benchmarks, Versionsangaben neu ab. Markiere alles, was nicht stimmt.
4. Konträre Prüfung – Suche aktiv nach "warum ist das falsch / Betrug / kritisiert / veraltet / bekannt schlecht". Nenne den stärksten gefundenen Einwand. Dies zu überspringen ist der häufigste Fehlermodus des Subagenten. Weise explizit in der Aufgabenstellung darauf hin.
5. Synthetisieren – Urteil + Zitate + verbleibende Meinungsverschiedenheiten explizit aufgelistet. Keine stillen Entscheidungen.

Erforderliches Ausgabeformat des Subagenten

Die Aufgabenstellung MUSS explizite Zitierregeln enthalten. Subagenten, die auf akademischen Schreibstil trainiert sind, verwenden standardmäßig [1], [2]-Inline-Zitate; ohne explizite Anweisungen produzieren sie verrauschte Ausgaben. Gib die Regeln in einfacher Sprache an. Empfohlener wörtlicher Block zum Einfügen in die Aufgabenstellung:

Zitierregeln. Lies sorgfältig und befolge genau:

• Verwende KEINE [n] nummerierten Zitate. Keine [1], [2] oder andere eingeklammerte Zahlen im Findings-Text.
• Füge KEINE URLs in den Findings-Text ein.
• Füge KEINE Inline-Fußnotenmarkierungen, Anker oder andere Zitationstags pro Behauptung jeglicher Art hinzu.
• Schreibe Findings als einfache Prosatexte.
• Wenn die Interpretation einer Behauptung davon abhängt, welche Quelle sie gemacht hat, nenne die Quelle als Prosa, keine Klammern ("laut der README", "gemäß littlemight.com", "der HN-Simulator-Kommentator argumentiert..."). Keine URL, kein [n].
• Setze ALLE Quellen in einen einzelnen ## Sources-Block am ENDE der Rückgabe, ein Aufzählungspunkt pro Quelle: - url - abgerufen YYYY-MM-DD. Der Hauptagent hebt diesen Block in das Frontmatter von FINDINGS.md.
• Die Quellenanzahl-Disziplin bleibt erhalten: mindestens 2 unabhängige Quellen pro nicht-trivialer Behauptung. Die Disziplin lebt in der Quellenanzahl, nicht im Inline-Tagging.

Erforderliche Ausgabeform (was der Subagent zurückgibt):

## Summary
3 bis 6 Zeilen Zusammenfassung.

## Findings
Einfache Prosa. Keine `[n]`-Markierungen. Keine Inline-URLs. Inline-Quellen namentlich nur als Prosa, wenn für die Interpretation tragend.

## Stärkster Einwand (aus der konträren Prüfung)
1 bis 2 Sätze, oder "keiner gefunden".

## Sources
- url - abgerufen YYYY-MM-DD
- url - abgerufen YYYY-MM-DD

## (Nur Zusammenführungsmodus) Ersetzt
- Behauptung aus bestehendem Eintrag, die jetzt falsch ist + Grund

Der Subagent schreibt keine Dateien. Du analysierst diese Rückgabe und wendest die Speicherungsregeln an.

Lückenbehandlung

Wenn die Rückgabe des Subagenten Lücken aufweist:

• Kleine Lücke (eine fehlende Tatsache, ein bestimmter Aspekt) → fülle sie selbst mit einer gezielten WebSearch / WebFetch. Günstiger als ein Neustart.
• Große Lücke (ganze Abschnitte oberflächlich, konträre Prüfung offensichtlich übersprungen) → starte erneut mit einer verfeinerten Aufgabenstellung, die die spezifische Lücke benennt. Die vorherige Rückgabe wird verworfen (es wurde noch keine Datei geschrieben).

3. Speicherung (die Schreibseite – der Hauptagent besitzt ALLE Dateischreibvorgänge)

Überprüfung vor dem Speichern

Das strukturierte Format des Subagenten validiert nicht den Inhalt. Das Format signalisiert nur "Ich habe die Vorlage befolgt"; es bestätigt nicht, dass der Inhalt korrekt, gut belegt oder relevant für das ist, was gefragt wurde. Bevor du die Speicherung anwendest, führe diese 4-Punkte-Prüfung durch:

1. Relevanz: Beantwortet die Zusammenfassung tatsächlich das, was gefragt wurde? Wenn der Agent ein mehrdeutiges Thema disambiguiert hat (eine Interpretation von mehreren gewählt), bestätige, dass es der Benutzerabsicht entspricht. Wenn falsch, starte mit einer engeren Aufgabenstellung neu; speichere nicht.
2. Quellenqualität: Zähle die primären URLs im Vergleich zu aggregierten WebSearch-Snippets im ## Sources-Block. Wenn die meisten Quellen Suchergebnis-Zusammenfassungen ohne spezifische abgerufene URLs sind, ist der Eintrag schwächer als er aussieht. Entweder fülle die Primärquellen selbst mit gezieltem WebFetch, oder speichere, aber markiere die Schwäche explizit in ## Open questions.
3. Belege für die konträre Prüfung: "keiner gefunden" ist bei nicht-trivialen Themen selten. Wenn du "keiner gefunden" bekommen hast, sei skeptisch: Entweder ist das Thema wirklich unumstritten (selten), oder der Subagent hat Phase 4 übersprungen (häufig). Wenn übersprungen, fülle selbst mit gezielten konträren Suchen, oder starte neu.
4. Zitierungsbereinigung: Wenn die Rückgabe [n]-Markierungen im Findings-Text enthält, obwohl die Aufgabenstellung die [n]-Regel enthält, entferne sie vor dem Schreiben von FINDINGS.md. Dies ist ein bekannter Fehlermodus (Subagenten fallen auf akademische Zitiergewohnheiten zurück). Gib das Rauschen nicht weiter. Gleiches gilt für Inline-URLs im Findings-Text: Entferne sie. Quellen gehören ins Frontmatter.

Wenn die Überprüfung behebbare Lücken aufdeckt, fülle sie selbst mit einer gezielten WebSearch / WebFetch (günstiger als ein Neustart). Wenn die Lücken systemisch sind, starte mit einer verfeinerten Aufgabenstellung neu; schreibe keinen halbfertigen Eintrag.

Speicherung anwenden

Nachdem die Untersuchung ihre Synthese zurückgegeben hat (oder der Benutzer Ergebnisse eingefügt hat), schließt du (Hauptagent, niemals der Subagent) die Datenebene ab. Zwei Pfade, ausgewählt basierend auf dem in der Abrufphase 5 gewählten Modus:

Pfad "Neuer Eintrag":

1. Erstelle <root>/.research/<Thema-slug>/.
2. Schreibe FINDINGS.md unter Verwendung des Schemas in Dateischemas. Frontmatter: created und last_verified = heute; status: active; sources aus der Subagentenrückgabe; raw: ausgelassen (noch keine Rohdaten); related: [] es sei denn, Querverweise gelten.
3. Lese INDEX.md, füge eine Zeile hinzu: Thema, Pfad, heutiges Datum, eine spezifische Kurzbeschreibung.

Pfad "Zusammenführung":

1. Lese die vorhandene FINDINGS.md.
2. Aktualisiere Frontmatter: last_verified = heute; hänge neue Quellen an.
3. Wende die ## Supersedes-Liste des Subagenten an: Verschiebe jede genannte Behauptung aus ## Findings nach ## Discarded approaches mit Datum und Grund. Siehe Konflikthandhabung.
4. Aktualisiere / erweitere ## Findings um neue Behauptungen.
5. Füge einen Eintrag in ## Timeline hinzu, der die Änderung zusammenfasst.
6. Lese INDEX.md, aktualisiere die Spalte Zuletzt überprüft der Zeile. Aktualisiere die Kurzbeschreibung, wenn sich das Bild geändert hat.

Verwende Kebab-Case-Slugs, die dazu passen, wie der Benutzer wahrscheinlich wieder fragen wird – z.B. tailwind-v5, 2d-engines-clonable, orm-comparison-2026. Der Slug sollte disambiguieren.

4. Vergangenheit

…

[gekürzt für die Übersetzung]