docs: openrouter-byok-visual-review known-pattern (cross-town contribution from midgard)

docs/known-patterns/example-files/instrument-vars.example.yaml

@@ -0,0 +1,63 @@
+
+name: boardroom-visual-review-vars
+version: 1
+description: Visual review via inline HTML template substitution.
+author: mayor
+instrument:
+  version: 3
+  rounds:
+  - name: first_impressions
+    questions:
+    - text: 'You are reviewing the rendered UI of an internal Boardroom ACK page used
+        to approve LLM-generated implementation specs. Below is its complete HTML+CSS
+        source — read it carefully, mentally render it, then react.
+
+
+        ---
+
+        {ack_html}
+
+        ---
+
+
+        Reconstruct the visual experience: layout, hierarchy, color, density. What
+        does this page communicate, and to whom?'
+    - text: On a scale of 1-10, how visually pleasant would the page above be when
+        rendered? Brief reasoning anchored to specific CSS choices (font stack, colors,
+        spacing, border-radius).
+  - name: comprehension
+    questions:
+    - text: In the page above, the buttons at the bottom are labeled Approve, Reject,
+        and Re-queue. Without explanation, what would each one do in your mental model?
+        Are any ambiguous?
+    - text: In the page above, the middle block (`pre.spec`) renders preformatted
+        monospace text with literal markdown headers (the actual string `# Context`
+        etc., not rendered headings). Is that the right presentation, or would you
+        expect rendered headings/lists?
+  - name: list_view
+    questions:
+    - text: 'Here is the complete HTML+CSS for the sessions list page in the same
+        Boardroom UI:
+
+
+        ---
+
+        {list_html}
+
+        ---
+
+
+        If this were your dashboard, would the layout help you find a specific past
+        Board Meeting? What would you change?'
+  - name: brand_fit
+    questions:
+    - text: 'Across both pages above (ACK + sessions list): DataViking is a small
+        AI/synthetic-research startup. The brand should feel sharp, technical, and
+        trustworthy — not enterprise CRM, not consumer SaaS. Does this UI hit that
+        target? If not, what specific moves (font, color, density, ornament) would
+        shift it?'
+  - name: concrete_changes
+    questions:
+    - text: Give three concrete CSS-level changes (specific properties + values, not
+        vague directions) that would noticeably improve the visual quality of these
+        screens. Order by impact-per-effort, highest first.

docs/known-patterns/example-files/synthesize.example.py

@@ -0,0 +1,53 @@
+import json
+import os
+import urllib.error
+import urllib.request
+
+key = os.environ["OPENROUTER_API_KEY"]
+with open("/tmp/sp-synthesis-input.json") as f:
+    payload_text = f.read()
+
+prompt = (
+    "Below are 210 responses from 30 synthetic personas (15 developers + 15 "
+    "enterprise buyers) reviewing the visual presentation of the DataViking "
+    "Boardroom internal UI — an LLM-generated implementation spec ACK page and "
+    "a sessions list dashboard.\n\n"
+    "Synthesize their feedback into a tight executive summary for Wesley "
+    "(founder/operator). Focus on:\n\n"
+    "1. **Visual quality verdict** — overall rating, with 2-3 things personas "
+    "consistently praised AND 2-3 things they consistently criticized.\n"
+    "2. **Re-queue button verdict** — was its purpose understood? Recommend "
+    "rename or keep.\n"
+    "3. **Pre-block markdown rendering verdict** — should literal `# Context` "
+    "stay or render as H1?\n"
+    "4. **Brand-fit verdict** — does this feel like a sharp AI startup tool, "
+    "or drift toward enterprise CRM / consumer SaaS?\n"
+    "5. **Top 5 concrete CSS changes** — extract the most-mentioned specific "
+    "improvements (with property:value pairs where given). Order by "
+    "frequency × persona-type weight.\n"
+    "6. **One sentence each on developer vs enterprise-buyer divergence.**\n\n"
+    "Be terse. Quote directly only when a phrase captures something multiple "
+    "personas echoed. No filler. This is for someone who runs companies.\n\n"
+    "Responses (JSON array):\n" + payload_text
+)
+
+body = json.dumps(
+    {
+        "model": "anthropic/claude-sonnet-4.5",
+        "messages": [{"role": "user", "content": prompt}],
+        "max_tokens": 2500,
+    }
+).encode()
+
+req = urllib.request.Request(
+    "https://openrouter.ai/api/v1/chat/completions",
+    data=body,
+    headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+)
+try:
+    with urllib.request.urlopen(req, timeout=300) as r:
+        d = json.loads(r.read())
+        print(d["choices"][0]["message"]["content"])
+        print(f"\n[usage: {d.get('usage')}]")
+except urllib.error.HTTPError as e:
+    print("ERROR", e.code, e.read().decode())

docs/known-patterns/example-files/vars.example.yaml

@@ -0,0 +1,26 @@
+
+# vars.yaml — example
+# Use literal-block scalars (|) to preserve HTML whitespace and newlines.
+
+ack_html: |
+  <!doctype html>
+  <html lang="en">
+  <head><title>Example</title></head>
+  <body>
+    <h1>Example page</h1>
+    <p>Content here.</p>
+  </body>
+  </html>
+
+list_html: |
+  <!doctype html>
+  <html>
+  <body>
+    <table>
+      <thead><tr><th>Col1</th><th>Col2</th></tr></thead>
+      <tbody>
+        <tr><td>a</td><td>b</td></tr>
+      </tbody>
+    </table>
+  </body>
+  </html>