oliverswitzer/lens

Was macht lens?

Ein Lens ist ein JSON-Graph, <lens>/model.json, der in eine eigenständige <lens>/index.html gebaut wird, die jeder öffnen und kommentieren kann. <lens> ist das Verzeichnis, in das es eingerichtet wurde (Standard: docs/lens). Die Datei <lens>/README.md dokumentiert die Knotentypen, Beziehungen, die Struktur von Behauptungen und die Integritätsregeln. Der Build-Vorgang weigert sich, ein Modell zu bauen, das eine Regel verletzt – ein grüner Build ist die erste Validierung.

Das eigene Verzeichnis dieses Skills enthält template/ (was in ein Repository kopiert wird), scripts/ (Helfer für Wettbewerber) und competitors.md. Es befindet sich unter .claude/skills/lens/ im Repository oder unter ~/.claude/skills/lens/ bei globaler Installation; nachfolgend steht $SKILL für dieses Verzeichnis.

Voraussetzungen: Node 20+ und Git. Kein package.json, keine Abhängigkeiten.

Ein neues Lens einrichten

1. Verzeichnis wählen. Frage den Benutzer, wo das Lens leben soll; Standard: docs/lens. Lehne es ab, ein vorhandenes model.json zu überschreiben.

2. Das Template kopieren (alles außer einer gebauten index.html):

   mkdir -p docs/lens && cp -R "$SKILL/template/." docs/lens/ && rm -f docs/lens/index.html
   echo '[]' > docs/lens/ids.lock.json      # die IDs des Starters sind nicht deine; beginne mit einer leeren Sperrdatei
   

3. Den Benutzer interviewen, dann das Starter-Modell ersetzen. model.json wird mit einem fiktiven Beispiel namens "Acme Notes" ausgeliefert, das jede gängige Knotenart zeigt. Behalte seine Struktur bei, ersetze seinen Inhalt. Frage Thema für Thema und gib einen konkreten Entwurf zur Korrektur, anstatt eine leere Frage zu stellen:

   • der Name des Produkts (title) und der Name des Eigentümers (der owner-Personenknoten, id p-owner, sofern der Benutzer nichts anderes bevorzugt; dessen title wird bei jeder Ansichtsbehauptung als "s Sicht" angezeigt);
   • der Zweck in einem Satz (purpose, eine view-Behauptung, die auf die Quelle des Eigentümers verweist);
   • der Kernzyklus, 2–5 geordnete loop-steps;
   • für wen das Produkt ist (avatars mit einer Persona-Karte) und was wehtut (problems);
   • bereits vorhandene Interviews oder andere Belege (source + person-Knoten; erfinde niemals Zitate oder Zeitstempel – wenn es kein Transkript gibt, zeichne es als Bericht des Eigentümers auf);
   • was bereits ausgeliefert wurde (surface, shipped: true, mit einem echten Screenshot) und was nur eine Idee ist (shipped: false);
   • was die Leute stattdessen nutzen (alternatives);
   • bis zu drei Wetten, die jetzt bewiesen werden sollen (hypothesis-Knoten mit focus: 1|2|3). Alles, was der Benutzer ohne Beleg sagt, ist eine view (seine) oder eine hypothesis; nichts ist observed ohne eine Quelle und ein at. Verwende Platzhalternamen ("Interviewpartner A"), es sei denn, der Benutzer möchte echte Namen in einer Datei, die öffentlich sein könnte.

4. Das Beispiel bereinigen. Lösche assets/example.png, sobald kein Knoten mehr darauf verweist, und setze Screenshots auf assets/surfaces/<surface-id>/<slug>.png. Die Pfade für code und adrs einer Oberfläche sind relativ zum Repository-Stammverzeichnis und müssen existieren (setze adrs auf das Verzeichnis, in dem das Repository Entscheidungsaufzeichnungen führt, z. B. docs/adr/).

5. Bauen und testen:

   node docs/lens/build.mjs && node --test docs/lens/tests/*.test.mjs
   

6. Anschauen. Kommentare werden im Browser pro Herkunft gespeichert, also diene die Datei, anstatt sie direkt zu öffnen:

   python3 -m http.server 8767 --bind 127.0.0.1    # vom Repository-Stammverzeichnis
   open "http://127.0.0.1:8767/docs/lens/index.html"
   

7. Schlagen Sie eine .gitignore-Zeile für docs/lens/assets/ads/**/*.mp4 vor, falls der Benutzer Wettbewerbsanzeigen verfolgen möchte. Committe model.json, ids.lock.json, index.html, assets/ und den Rest des Verzeichnisses gemäß den Commit-Regeln des Repositorys.

Die Arbeit grundieren

Lies die relevanten Knoten, ihre Behauptungen und ihre Quellen, bevor du den Eigentümer etwas fragst. Gib ihm eine konkrete Synthese zur Korrektur. Überprüfe bei einer Oberfläche den von ihr genannten Code (code, adrs), wenn ihr Verhalten relevant ist; ein Entscheidungsprotokoll sagt, was entschieden wurde, nicht, was der Code heute tut.

Belege hinzufügen

Jede Aussage ist eine Behauptung mit kind, evidence und optional next:

• observed (Gehört / gesehen): was jemand gesagt oder getan hat. Zitiere die Quelle mit at (ein Transkript-Zeitstempel oder ein Abschnitt für ein Dokument). Zitiere oder paraphrasiere genau; upgrade niemals eine Abschwächung ("könnte nützlich sein").
• view (Sicht des Eigentümers): die Interpretation des Eigentümers. Sie muss eine Quelle zitieren, deren people den owner des Modells enthalten.
• hypothesis (Ungetestet): alles Ungetestete, einschließlich Agentenvorschlägen und Implementierungsideen.
• Eine Hypothese ist auch eine Knotenart: Protokolliere jeden Beleg mit stance (supports oder contradicts) und at. Setze niemals eine Konfidenz; die Anzeige auf den focus-Hypothesen wird beim nächsten Build aus diesen Belegen berechnet (verschiedene Interviewpartner, die sie unterstützen; eine Stufe niedriger, wenn jemand ihr widerspricht; die Sicht des Eigentümers erhöht sie nie). Protokolliere widersprechende Belege genauso bereitwillig wie unterstützende.
• Gib jeder schwachen Behauptung ein next: eine Frage, die spezifisch genug ist, um sie in einem Gespräch zu stellen. Sie erscheint unter Nächstes Gespräch.
• Behalte den Überblick, wer was gesagt hat: Eine Idee, die der Eigentümer aufgebracht hat und der jemand zugestimmt hat, ist nicht dessen Bedürfnis.
• Ein neues Interview ist eine source mit date, people, locator und kurzen takeaways, die von den Behauptungen zitiert werden, die sie unterstützt. Lasse persönliche Details weg, die nicht mit dem Produkt zusammenhängen. Archiviere Transkripte unter <lens>/sources/ nur, wenn das Repository privat ist und der Interviewpartner zugestimmt hat.

Eine Oberfläche aktualisieren (nach einer Änderung)

Wenn eine Änderung das Aussehen oder Verhalten einer Oberfläche verändert, im selben Branch:

1. Erfasse die geänderten Zustände aus dem laufenden Produkt in <lens>/assets/surfaces/<surface-id>/<slug>.png (ersetze veraltete, behalte 1–4).
2. Aktualisiere die screenshots-Einträge der Oberfläche: caption, capturedAt (heute), origin: "app", version. Die Seite markiert jeden Screenshot, der älter ist als der letzte Commit am code der Oberfläche.
3. Aktualisiere unique / situations, wenn sich das Verhalten geändert hat, und code / adrs, wenn sich Dateien verschoben haben.

Eine brandneue ausgelieferte Oberfläche ist ein neuer surface-Knoten mit shipped: true, mindestens einem Screenshot, serves-Kanten zu den adressierten Problemen und implements-Kanten zu den Schritten des Kernzyklus.

Eine Idee hinzufügen (aus einem Brainstorming)

Eine Oberfläche, die diskutiert, aber nicht gebaut wurde, ist ein surface mit shipped: false; sie erscheint unter Ideen, visuell abgehoben. Gib ihr unique (als hypothesis-Behauptungen), situations, heard (was die Leute gesagt haben, mit Belegen) und Mockups als screenshots mit origin: "design". Wenn sie ausgeliefert wird, setze shipped auf true und ersetze Mockups durch echte Aufnahmen.

Eine Content-Pillar oder Content-Idee hinzufügen

Ein Marketing-Thema ist ein pillar; ein konkreter Beitrag, ein Video oder ein Event ist eine content-idea unter diesem Pillar, mit einem format. Verlinke Pillars oder Ideen mit speaks-to zu Avataren, Ideen mit features zu den Oberflächen, die sie zeigen, und like zu Wettbewerbern, die bereits einen ähnlichen Winkel fahren. Ideen und Pillars sind Ungetestet, bis der Inhalt Menschen erreicht hat; protokolliere, was passiert ist, als Beweis auf einer Hypothese about der Idee.

Eine Markteinblicke hinzufügen

Ein Trend aus externer Recherche ist ein insight auf dem Tab Markteinblicke. Zeichne den Artikel als Marktforschung-Quelle auf (optional einen Schnappschuss unter sources/), gib seine Fakten als beobachtete findings an und behalte, was er für einen Avatar bedeutet, als view oder hypothesis, einschließlich eines Hinweises auf die Grenzen der Quelle. Verlinke ihn mit bears-on auf alles, was er beeinflusst.

Einen Wettbewerber hinzufügen oder aktualisieren

Folge $SKILL/competitors.md: Recherchiere (Echt-Browser-Anzeigenprüfungen, niemals eine Paywall umgehen), scripts/add-product.py, gestaffelte Anzeigenerfassung, scripts/apply-staged-ads.py (prüft alles, wendet dann in einem Schritt an), scripts/smoke-ads.mjs, dann committe ohne .mp4s. Vergleiche mit dem Produkt aus der Perspektive des Lens-Zwecks und der Fokus-Hypothesen, niemals von dessen Marketingseite, und kennzeichne diesen Vergleich als Ungetestet.

Usability-Erkenntnisse gehören nicht in das Lens

Interaktionsprobleme (ein Knopf, den niemand findet, ein fehlender Fokus-Zustand) gehören in das Issue-Tracker des Teams. Erfasse sie dort und zeichne im Lens nur ihre Produktbedeutung auf, falls vorhanden.

Umbenennen oder Entfernen

ids.lock.json zeichnet jede kommentierbare ID aus dem letzten Build auf. Eine ID, die verschwindet, muss in model.json's renamed gemappt sein ("old-id": "new-id" oder null bei absichtlicher Entfernung) – sonst schlägt der Build fehl. Dadurch bleiben vorhandene Kommentare erhalten.

Das Lens selbst ändern

Jede Änderung unter components/ (was eine Ansicht zeigt, Routing, Validierung, der Diff) beginnt mit einem fehlschlagenden Test in <lens>/tests/ (node:test; gemeinsame Fixtures in tests/fixture.mjs, nur fiktive Namen). Halte die Logik in reinen Modulen; nur components/app.js greift auf das DOM zu. Führe dann die Tests aus, überprüfe anschließend dasselbe Szenario in einem Browser.

Den Diff visualisieren

Wenn der Eigentümer sehen, überprüfen oder visualisieren möchte, was sich geändert hat:

node docs/lens/diff.mjs [rev]          # Standard: HEAD; gibt die Änderungsliste aus
python3 -m http.server 8767 --bind 127.0.0.1
open "http://127.0.0.1:8767/docs/lens/index.html"

Grüne Umrandungen sind hinzugefügte Elemente, gelbe sind geänderte; entfernte Elemente werden im Banner rot aufgelistet. Jede hinzugefügte oder geänderte Zeile verlinkt zu ihrem Element. Änderungen werden nach ID abgeglichen, sodass eine einzelne Behauptung aufleuchtet, ohne ihre gesamte Karte. Vor dem Commit immer bereinigen und prüfen:

node docs/lens/build.mjs
grep -c LENS-V2-DIFF docs/lens/index.html   # muss 0 ausgeben

Neu bauen und prüfen

node docs/lens/build.mjs && node --test docs/lens/tests/*.test.mjs

Sieh dir dann die betroffenen Ansichten im Browser an. Kommentare sind browserlokal zur Herkunft; exportiere sie vor dem Wechsel. Beende mit dem Lens-Link, was sich geändert hat, den Belegen und etwaigen Einschränkungen.