| 1 | # Calculon's History |
| 2 | |
| 3 | ## Core Context |
| 4 | - **Project:** SquadScope |
| 5 | - **User:** jmservera |
| 6 | - **Created:** 2026-05-25 |
| 7 | - **Stack:** Hugo (v0.161.1) static site, PaperMod-derived theme, GitHub Pages deploy, Pagefind search |
| 8 | - **Description:** Weekly editorial trend analysis of GitHub repos and tech press. Editorial publication, not a dashboard. Reader-first. |
| 9 | - **Current state:** Site has functional content (W21, W22 published) but visuals are inherited from a generic PaperMod-style theme. Needs distinct editorial design direction. |
| 10 | |
| 11 | ## What the team has built |
| 12 | - Crawl → analyze → publish pipeline (Mon 08:30 UTC + manual) |
| 13 | - W21 article: "Agent Skills Go Mainstream While Star Farmers Game the Charts" |
| 14 | - W22 article: "Supply-Chain Scanners, Skills Economies, and GitHub's Star-Farm Flood" |
| 15 | - Monthly + yearly rollups |
| 16 | - TechCrunch press correlation |
| 17 | - Cost dashboard shortcode |
| 18 | |
| 19 | ## Key files in my domain |
| 20 | - `hugo.toml` — theme params, mounts, colors (currently default PaperMod) |
| 21 | - `layouts/` — Hugo templates (header.html, weekly/single.html, partials/report-metrics.html, shortcodes/cost-dashboard.html, index.html) |
| 22 | - `assets/` — CSS, JS (theme-derived) |
| 23 | - `static/` — favicons, icons, social images (currently default Hugo favicon) |
| 24 | |
| 25 | ## Learnings |
| 26 | |
| 27 | ### 2026-05-25: Playwright Visual Verification Pattern |
| 28 | |
| 29 | **Pattern:** Visual verification via Playwright snapshot diffs at viewport × theme × page matrix. |
| 30 | |
| 31 | - **Viewport matrix:** mobile (375), tablet (768), desktop (1280), wide (1920) |
| 32 | - **Theme matrix:** light + dark |
| 33 | - **Pages matrix:** home, latest weekly, monthly rollup, yearly rollup |
| 34 | - **Key gotcha:** Dynamic content (cost dashboard date, run counter) must be hidden via CSS injection (`visibility: hidden !important`) before screenshotting — otherwise every run will produce a false diff. |
| 35 | - **Anti-aliasing noise:** Set `maxDiffPixels: 150` as default; tighten once baselines are stable. |
| 36 | - **Font settle:** Always `waitForLoadState('networkidle')` + 300ms extra before capture. |
| 37 | - **When to bump skill confidence:** After 2+ PRs successfully use it and at least one real mismatch was caught. |
| 38 | - **Files:** `scripts/design/verify-visual.mjs`, `tests/visual/playwright.config.mjs`, `tests/visual/visual.spec.mjs`, `docs/design/visual-verification.md`, `.squad/skills/design-visual-verification/SKILL.md` |
| 39 | |
| 40 | ### 2026-05-25: Initial Design Direction |
| 41 | |
| 42 | **Design Principles Established:** |
| 43 | 1. Reading First — Typography/spacing optimized for long-form scanning |
| 44 | 2. One Signal Per Glance — Each content block delivers single clear message |
| 45 | 3. Dense ≠ Cluttered — White space between dense blocks, not padding around sparse content |
| 46 | |
| 47 | **Icon Concept:** Radar Sweep — concentric circles with sweep line and signal blip. Represents continuous scanning of GitHub landscape. Geometric, scales from 16px to 512px. Uses `currentColor` for automatic light/dark adaptation. |
| 48 | |
| 49 | **Palette Decisions:** |
| 50 | - Light: bg #FAFAFA, text #1A1A1A, accent #0066CC |
| 51 | - Dark: bg #0D0D0D, text #E8E8E8, accent #4DA3FF |
| 52 | - All combinations WCAG AA verified |
| 53 | |
| 54 | **Key Files Created:** |
| 55 | - `docs/design/redesign-proposal-2026-05.md` — Full design proposal with tokens, layout specs, component specs |
| 56 | - `docs/design/icon-spec.md` — Icon concept, SVG code, asset list |
| 57 | |
| 58 | **Migration Phases:** 6 phases (tokens → header/footer → home → articles → cost dashboard → icons) |
| 59 | |
| 60 | **Issues Created:** #170-#177 |
| 61 | |
| 62 | ### 2026-05-25: Icon Safety Check Pattern |
| 63 | |
| 64 | **Trigger:** User directive caught potential misreading of double-S letterform as Nazi SS rune — flagged before Phase 6 shipped. |
| 65 | |
| 66 | **Pattern — Icon Silhouette Safety Check:** |
| 67 | 1. **Pre-design:** Avoid letterforms or geometric patterns that could be misread as extremist/hate symbols (double-S monograms, single-rune lightning bolts, certain cross/sun variants, certain hand signs) |
| 68 | 2. **Post-design verification:** |
| 69 | - Render at 16px, 32px, 64px, 512px — ambiguity often hides at small sizes |
| 70 | - Test rotation/flip — no problematic shapes should emerge |
| 71 | - Check negative space — no hidden symbols in whitespace |
| 72 | - Cross-reference against ADL Hate on Display database or similar |
| 73 | 3. **Document:** Include silhouette safety check results in icon spec |
| 74 | |
| 75 | **Replacement design:** Robot with binoculars (keeps "scope" metaphor, adds friendly personality, zero symbol ambiguity). See updated `docs/design/icon-spec.md`. |
| 76 | |
| 77 | **Skill created:** `.squad/skills/icon-safety-check/SKILL.md` at confidence: low (needs validation across more icon designs) |
| 78 | |
| 79 | ### 2026-05-25: Icon Redo Learnings (PR #189) |
| 80 | |
| 81 | **The hallucinated-success failure mode:** |
| 82 | The first pass on PR #189 reported success ("robot+binoculars SVG produced") but the actual file content still contained the old radar-sweep SVG. The edit tool appeared to confirm changes but they didn't persist. **Lesson:** After any file edit, verify file content with `cat` or `head` — don't trust the edit confirmation alone. |
| 83 | |
| 84 | **Pattern: asset-first, text-second:** |
| 85 | When redesigning, write the new asset (SVG code) FIRST, then update all surrounding text (spec doc, header.html, CSS) to match. Never the other way around. If you write the text description first, you risk describing an asset that doesn't exist. |
| 86 | |
| 87 | **Read the bug report exactly:** |
| 88 | The user flagged the "SS" text monogram in `layouts/partials/header.html` (line 4: `<span class="site-brand__mark">SS</span>`). The first pass updated `docs/design/icon-spec.md` without touching `header.html` — missing the actual user-visible problem entirely. **Lesson:** Trace the reported issue to the exact file/line before planning fixes. |
| 89 | |
| 90 | **Verification via bash:** |
| 91 | For multi-file atomic changes, use bash heredocs (`cat > file << 'EOF'`) to write complete file content. This guarantees the file matches what you intended, unlike incremental edits that can silently fail. |