Merge feature/seo-geo-deprescription into develop
This commit is contained in:
Bastien Chanot
@@ -1076,3 +1076,6 @@ Old routing "Bug → investigate (bugfix if gstack off)" + gstack ON by default
|
||||
|
||||
### BDR-081 — Config recalibrated for Claude 5 family (Opus 5 dispatch tier) [accepted] (2026-07-30)
|
||||
Opus 5 (released 2026-07-24) now backs every `model: opus` pin (BDR-076/077) + any `/model opus` session. Research (official migration guide + web + registries): Opus 5 OVER-delegates (inverts LRN-030 Opus 4.8 trait that CLAUDE.global.md:43-47 compensated), self-verifies (explicit verify instructions → over-verification, "removing them reduces wasted tokens with no loss in quality"), literal following (conservative-reporting clauses depress recall; MUST/CRITICAL over-triggers), scope expansion = named regression, written deliverables +30-40%. Claude Code injects Opus-5-only anti-delegation prompt sections (heron_brook + subagent_steer_delegation, issue #80988, server-gated, no opt-out) — prose caps would triple-stack. Shipped: delegation block → model-neutral WHEN-guidance + explicit gates carve-out (verifier/security/challenge still dispatch as written); "staff engineer" self-check bar dropped; finish-whole-task clause folded into Deviations (gone-WRONG→STOP still wins); deliverable-length rule; design hook `\bux\b` dropped (`\bui\b` KEPT — 0 FP, 1 logged TP, lock-tested); plan-challenger grounded-doubt→[MINOR] in-place reword (grammar byte-identical). Plan challenged by 3 blind Opus 5 plan-challengers: correctness CONCERNS(4) / robustness FATAL(5, BLOCKER: all surfaces symlink-deployed LIVE — gates fire post-deployment) / simplicity CONCERNS(4); every fix adopted as prescribed (scratch-validation before live hook write, minimal diffs, ux-only, MINOR-routing). Alternatives rejected: leave as-is (nudge actively counter-productive); hard spawn caps in prose (harness injects one); confidence axis on challenger grammar (consumer unwired); dropping \bui\b (no evidence). NOT touched: verify-secure-loop + fresh gates (harness architecture BDR-049/050, ≠ model self-check prose); Security/Architecture sections (BDR-021); settings effortLevel xhigh (user pref — Opus 5 carry-over trap → LRN-139); superpowers plugin wording (external upstream). Plan+synthesis: .claude/tasks/plans/2026-07-30-opus5-config-tuning-1238.md. Branch feature/opus5-config-tuning, unmerged (human gate).
|
||||
|
||||
### BDR-082 — seo/geo analyzers de-prescribed for Opus 5 (C1) [accepted] (2026-08-02)
|
||||
BDR-081 N5 follow-on, user-directed apparatus (plan+3-lens challenge+census+dogfood). Method: audience×mode-range invariant — dedup ONLY verbatim same-audience (spec rule / bundle-item payload / phase-local caveat) same-mode-range repeats; cross-mode + agent↔dispatcher twins stay (standalone paths need them). Census-FIRST: lib/tests/seo-geo-contract.test.sh 71 locks (verdict grammar, sentinels, ALL STEP headers incl. interiors, item fields, score labels, envelope keys), flip-proven 7 mutations→7 FAILs, committed BEFORE reword. Shipped: self-output verification removed (":970 run twice"→conditional integrity guard; ":1217"→single-shot-scoped), 2 pre-BDR-061 vestigials fixed, caps softened (P0-rule/MANDATORY/ALWAYS→plain content rules), 2 essays compressed, checklist :1309→routing map rows verbatim (challenger caught it = routing table, NOT self-check), true same-range dups only (seo Handoff+landing-page blocks; geo ZERO — all claimed pairs distinct on inspection). FROZEN: guard-first url-guard orderings, :550 denominator-before-sampling (ordering IS the honesty mechanism), R2/NAP/COVERAGE/citation invariants, external-freshness checks (world drift ≠ self-verification). Deltas: seo 1528→1503 l ("P0 rule" 2→0, ALWAYS 1→0, MUST 5→4, NEVER 9→9 = class-B bans kept); geo 1106→1107 (MANDATORY 1→0, MUST 4→3). Plan challenged correctness FATAL / robustness FATAL(3 BLOCKER) / simplicity CONCERNS + confirmation FATAL(9) — every BLOCKER closed by named change (§5bis record). Dogfood before/after on frozen zenquality copy: judge-replay on frozen signals (zero collect variance) + templates + fresh collects + e2e judge + 42/42 assert battery BOTH sets + blind reader "interchangeable; all deltas = presentation variance both directions OR after MORE spec-conformant". Alternatives rejected: keyword dedup (challengers proved audience/range-blind — most annex "twins" were distinct obligations), FULL/aggressive dogfood (billing gate killed nested CLI; left as user option), banner/shape locks (LLM-convention layers wobble — lock strings only). Evidence: .audit/dogfood-baseline/ (18 artifacts + DOGFOOD-VERDICT.md), plan .claude/tasks/plans/2026-07-30-seo-geo-deprescription-1402.md. Branch feature/seo-geo-deprescription, UNMERGED (human gate).
|
||||
|
||||
@@ -430,3 +430,6 @@ rules:
|
||||
|
||||
## 2026-07-30
|
||||
- User: Opus 5 "needs more freedom" → analyse config + adapt. Research 3-agent (registries / config audit / web) + official migration guide: over-delegation (inverts LRN-030), over-verification, literal following, scope expansion, #80988 injections. Plan challenged 3 blind Opus 5 plan-challengers — robustness FATAL (BLOCKER: symlink-live deployment), all fixes adopted. Shipped: CLAUDE.global.md recalibrated (delegation when-guidance, staff-bar dropped, finish-whole-task, deliverable-length; 308/320), design hook \bux\b dropped flip-tested (22/0), plan-challenger grounded-doubt→[MINOR] (44/0). BDR-081 + LRN-139. feature/opus5-config-tuning, UNMERGED.
|
||||
|
||||
## 2026-08-02
|
||||
- C1 seo/geo de-prescription EXECUTED end-to-end: census-first 71 locks flip-proven → reword under audience×range invariant (adafa35/c7646a9) → controlled dogfood (judge-replay frozen signals + templates + fresh collects + e2e + blind reader) → 42/42 both sets, zero contract regression, recall improved. Plan survived 4 challenge passes (2 FATAL + confirmation FATAL(9), all closed by name). BDR-082 + LRN-140. Nested-CLI dogfood died on monthly spend limit → inline pipeline (canonical /seo shape). feature/seo-geo-deprescription UNMERGED (human gate). Chantiers C2-C4 pending.
|
||||
|
||||
@@ -1361,3 +1361,10 @@ rules:
|
||||
- **Opus 5 traps found**: (a) Claude Code injects Opus-5-only anti-delegation prompt sections (heron_brook + subagent_steer_delegation, issue #80988; server-gated, no opt-out, absent from transcripts) — own prose stacks on top blindly; (b) NO model-default effort hold on Opus 5 — persisted effortLevel (xhigh, settings.json) silently carries over, against "start high, sweep low/medium"; run /effort sweep per model; (c) effort does NOT shorten visible output/deliverables — only prose length rules do (+30-40% docs).
|
||||
- **future application**: at every model-generation bump, grep config for trait-compensating language ("counters model tendency…", "default to X") and re-verify the premise; prefer WHEN-guidance (conditions where X pays) over directional nudges — survives inversions unchanged.
|
||||
- **link**: [[LRN-030]] [[BDR-081]].
|
||||
|
||||
## LRN-140 — de-prescription findings: dedup evaporates, self-verify is default, recall survives (2026-08-02)
|
||||
- **pattern 1 — inventory dedup counts lie**: line-level inspection killed most "duplicate" pairs (seo 9 families→2 real merges; geo 7→0). Twins differ by AUDIENCE (bundle-item payload read by fresh applier vs spec rule) or MODE-RANGE (collect/judge/template/RULES) or are distinct obligations sharing a keyword (30/70 ×3 = three different rules). Dedup rule that survives: verbatim + same-audience + same-range ONLY.
|
||||
- **pattern 2 — Opus 5 self-verifies unprompted**: "run it twice" instruction REMOVED → after-judge still ran score engine twice, identical output. Removing verify-prose does not remove the behavior; its value = no compounding, no contradiction burn. Confirms BDR-081 E3 mechanism, refines the payoff claim.
|
||||
- **pattern 3 — de-prescription does NOT depress recall**: reworded collect caught -encoded phone AT COLLECT (baseline collect missed it); reworded judge found new RGPD finding + self-caught false positive + corrected collect coverage claim 21/21→20/21. Integrity/honesty invariants (kept class B) carry the discipline, not the caps.
|
||||
- **pattern 4 — lock strings, never shapes**: LLM-convention output layers (banners, fences, table columns, section order) wobble run-to-run in BOTH directions — baseline itself deviated from spec where after conformed (§0 ENTRIES, BUNDLE-before-SCORING). Stable contract = census-locked literal strings; anything unlocked drifts and MUST be tolerated by consumers (tier recognition "by intent" is the right pattern).
|
||||
- **link**: [[BDR-082]] [[BDR-081]] [[LRN-139]] [[LRN-113]].
|
||||
|
||||
+12
-5
@@ -29,11 +29,18 @@ adopted as prescribed (plan §5bis, v2 items below).
|
||||
|
||||
## 2026-07-30 — Claude 5 follow-on chantiers (user directive, checkpoint between each)
|
||||
Order fixed, one branch per chantier, no merge without per-chantier signal.
|
||||
- [ ] C1 dé-prescription seo-analyzer.md + geo-analyzer.md (opus pins → Opus 5):
|
||||
separate machine-parsed contracts (fix-bundles, ownership matrices,
|
||||
output formats — verbatim) from process choreography (MUST/MANDATORY on
|
||||
"how" → when-guidance). Dedicated plan + 3-lens challenge, census tests
|
||||
same commits, real /seo dogfood before/after (zero format regression).
|
||||
- [x] C1 dé-prescription seo-analyzer.md + geo-analyzer.md — DONE 2026-08-02.
|
||||
Census-first 71 locks flip-proven (9681b46) → rewords under
|
||||
audience×range invariant (adafa35 seo, c7646a9 geo) → controlled
|
||||
before/after dogfood: judge-replay on frozen signals + templates +
|
||||
fresh collects + e2e judge + blind reader = 42/42 both sets, zero
|
||||
contract regression, recall improved. Plan challenged 4 passes
|
||||
(FATAL/FATAL/CONCERNS + confirmation FATAL(9), all closed by name).
|
||||
BDR-082 + LRN-140. Evidence .audit/dogfood-baseline/ (19 artifacts).
|
||||
Branch feature/seo-geo-deprescription UNMERGED — human gate.
|
||||
Residual for gate: §6bis dynamically-unverified list (FULL branches,
|
||||
apply path — census-locked statically); FULL/aggressive dry-run = user
|
||||
option; nested-CLI dogfood blocked by monthly spend limit (inline used).
|
||||
- [ ] C2 self-contradiction audit CLAUDE.global.md + own skills: list rule
|
||||
pairs in tension, propose resolution per pair, apply after user OK.
|
||||
/doctor as assistant, not authority.
|
||||
|
||||
@@ -0,0 +1,174 @@
|
||||
# ANNEX — directive-language inventory (analyzer report, 2026-07-30)
|
||||
|
||||
Produced by a read-only analyzer dispatch over agents/seo-analyzer.md
|
||||
(1528 l) + agents/geo-analyzer.md (1106 l), cross-referenced against
|
||||
every consumer. Referenced by the C1 plan (same folder, -1402.md).
|
||||
|
||||
## 0. Token census (raw)
|
||||
|
||||
| Token family | seo-analyzer.md | geo-analyzer.md |
|
||||
|---|---|---|
|
||||
| MUST/must | 12 | 6 |
|
||||
| MANDATORY/mandatory | 8 | 4 |
|
||||
| NEVER/never | 42 | 33 |
|
||||
| ALWAYS/always | 6 | 1 |
|
||||
| CRITICAL/critical | 3 | 1 |
|
||||
| Do NOT / do not | 24 | 8 |
|
||||
| verbatim | 6 | 3 |
|
||||
| STOP | 3 | 4 |
|
||||
| refuse/REFUSE | 6 | 4 |
|
||||
| ⚠️ blocks | 0 | 0 |
|
||||
|
||||
## 1. Test locks on these files (complete list — 6 per file)
|
||||
|
||||
model-routing.test.sh:67-68 `model: opus` (both) · :150-157 `MODE:
|
||||
collect|judge|template` + `COLLECTION COMPLETE` (both) ·
|
||||
seo-data.test.sh:538-540 `fetch.sh crux` / `fetch.sh queries` /
|
||||
`Performance GSC` (seo) · :542-543 `fetch.sh schema_gen` /
|
||||
`fetch.sh content_quality` (geo).
|
||||
NOT locked by any test: READY-TO-APPLY sentinel, envelope headings,
|
||||
score-block shapes, JUDGE-ERROR strings, batch labels — contracts by
|
||||
consumer only; a rewrite can break them silently and make test stays
|
||||
green. Sibling dispatcher locks: model-routing.test.sh:159-166.
|
||||
Stale line-number comments (no enforcement): lib/url-guard.sh:9,
|
||||
url-guard.test.sh:20, source-scope.sh:25, seo-data/README.md:196/309,
|
||||
drift.py:4, linkgraph.py:4 — all already drifted.
|
||||
|
||||
## 2. Format contract (artifact → consumer) — FREEZE SET
|
||||
|
||||
seo-analyzer: signals `.audit/seo-signals-<RUNID>.md` (+clean/load sites
|
||||
in /seo) · `COLLECTION COMPLETE — RUNID: <RUNID>` terminal ·
|
||||
`COLLECT REPORT` w/ `STATUS: DONE|BLOCKED` · `SEO JUDGE — VERDICT:
|
||||
ERROR(<reason>)` · judge report forwarded verbatim to template ·
|
||||
`SEO SCORING (<depth>)` block w/ `COVERAGE SOURCE:`/`COVERAGE LIVE :`
|
||||
+ 7 axes + `SEO GLOBAL (weighted): XX.X/20` (score.py:26-37 mirrors
|
||||
weights) · `TRAJECTORY TO 17/20 (code-only)` · `fetch.sh score` JSON
|
||||
(`axes.{technical,on-page,seo-local,off-page,social,competitive,legal}`,
|
||||
severities `critique|haute|moyenne|basse`, `status:"na"`) · `FIX PLAN (N
|
||||
findings total)` + BATCH A…F (tier-mapping tolerant) · `## FIX BUNDLE
|
||||
(for dispatcher)` + `### AUTO/### GATED/### USER ACTIONS` + item fields
|
||||
`id: applier: files: concern: current: expected:` · sentinel `READY TO
|
||||
APPLY — awaiting dispatcher confirmation` (also reused by /harden:366) ·
|
||||
envelope `SEO AGENT RESULT` + `## SECTION FOR SEO.md §2…§6` + `## ENTRIES
|
||||
FOR SEO.md §0/§8/§9/§10/§11/§15` · `Automatisation possible avec:` per
|
||||
§11 entry · standalone `.claude/audits/SEO.md` w/ `**Score SEO** : XX.X
|
||||
/ 20` (client-handover-writer.md:344 labeled grep) + §0-§15 + Historique.
|
||||
geo-analyzer: same families with GEO names; envelope `GEO AGENT RESULT`
|
||||
+ `## SECTION FOR SEO.md §7` (7.1-7.6); `**Score GEO** : XX.X / 20`
|
||||
(handover parses it only inside SEO.md, allow_fallback=no); G1-G7
|
||||
batches (G1-G4/G6 AUTO · G5 GATED · G7 USER). Both: STEP NUMBERS are
|
||||
addressed by dispatchers (seo: 2-5/6-11/12-14; geo: 0-5/6-12/13-15;
|
||||
also depth-matrix.md:17-19,37) — renumbering re-points dispatch prompts.
|
||||
Engine interfaces: fetch.sh verbs {crux,queries,inspect,cannibal,
|
||||
sitemap,rendercheck,linkgraph,score,schema_gen,content_quality} ·
|
||||
url-guard.sh host|url · source-scope.sh findargs|list · resources/*.md.
|
||||
|
||||
## 3-4. Site classification counts
|
||||
|
||||
| | seo | geo | total |
|
||||
|---|---|---|---|
|
||||
| A machine-parsed contract | ~52 | ~41 | ~93 (12 test-locked) |
|
||||
| B safety/policy invariant | ~30 | ~31 | ~61 |
|
||||
| C process choreography | ~21 | ~12 | ~33 |
|
||||
| D other/domain-fact | ~20 | ~13 | ~33 |
|
||||
|
||||
### Class C sites — seo-analyzer.md (rewrite targets)
|
||||
:61 "First action." · :143-148 CMS-detect-before-edit ordering ·
|
||||
:208-210 "keep the two consistent" (runtime cross-file reconcile) ·
|
||||
:508 "run this BEFORE anything else in STEP 5" (ordering; the refusal
|
||||
rule itself is B) · :550-553 "Record the denominator BEFORE sampling"
|
||||
(ordering; honesty rule is B) · :602-604 "Sanity-check the grouping
|
||||
before trusting it" (self-verify) · :606-618 sampling-method essay ·
|
||||
:661-680 C1a 20-line rationale (rule itself is B at :1493-1501) ·
|
||||
:875 per-item method · :970-971 "Run it twice on the same file before
|
||||
publishing" (exact BDR-081 over-verification class) · :1147 "AUTO items
|
||||
are a commitment, not a suggestion." · :1149-1157 P0 CMS-plugin-first
|
||||
mandate · :1159-1162 P0 Bing mandate (dup of geo :777-786) · :1217 "Do
|
||||
not proceed to STEP 12 until this plan is printed." · :1260-1261 +
|
||||
:1342-1350 + :1502-1503 landing-page rule ×3 · :1309-1320 bundle
|
||||
completeness checklist (10 checkboxes self-audit) · :1504 "Preserve
|
||||
existing valid SEO." · :1522-1523 WebSearch-on-FULL extra-verify ·
|
||||
:1525-1526 "Transparency. Every automated change logged" (VESTIGIAL —
|
||||
agent applies nothing, pre-BDR-061).
|
||||
|
||||
### Class C sites — geo-analyzer.md
|
||||
:48 "copy these patterns" · :124 "First action." + :127-139 ask-block
|
||||
(unreachable when dispatched) · :230 conditional skip · :262-269 +
|
||||
:873 + :1063-1065 PERMISSIVE default ×3 · :360 ordering · :394 "20-50
|
||||
real customer questions (P0)" · :777-786 MANDATORY AI-index submission
|
||||
(dup of seo :1159-1162) · :811 "Consolidate EVERY finding" · :823
|
||||
"Print the plan before STEP 13" · :1102-1103 WebSearch extra-verify ·
|
||||
:1106 "Every automated change logged in §14" (VESTIGIAL; §15 log is
|
||||
dispatcher's per :959).
|
||||
|
||||
### Class B anchors (keep obligation, dedup emphasis)
|
||||
CWD/TARGET MISMATCH twins (seo :117-126 ≈ geo :173-181) · url-guard
|
||||
mandatory (seo :287-291 ≈ geo :273-277) · R2 refuse-to-score (seo
|
||||
:519-548, geo :548-557; BDR-072) · NAP direction rule (seo :801-812,
|
||||
geo :1073-1087; LRN-032-zenquality) · COVERAGE mandatory (seo
|
||||
:1110-1130, geo :725-729; LRN-133) · never-apply/L1 (BDR-061; LRN-105
|
||||
named-ban) · C1a build-output ban · no-invented-content/DGCCRF ·
|
||||
"Compute the scores, do not feel them (I7)" (BDR-073) · §14 mandatory
|
||||
disclosure lines (backlinks BDR-071, security headers I4) · honest
|
||||
llms.txt framing · cite-sources (LRN-131).
|
||||
|
||||
## 6. Duplication map (sweep ALL twins — LRN-113)
|
||||
|
||||
seo internal: never-apply ×4 (:1227-1234, :1352-1357, :1468-1472,
|
||||
:1527-1528) · landing-page ×3 (:1260, :1342, :1502) · shared-file
|
||||
discipline ×2 (:1254, :1486) · bundle self-containment ×2 (:1249,
|
||||
:1473) · COVERAGE ×4 (:438, :1000, :1096, :1110) · security-headers-
|
||||
not-scored ×3 (:281, :977, :994) · 30/70 ×3 (:397, :614, :1165) ·
|
||||
sentinel-verbatim ×3 (:1301, :1304, :1397).
|
||||
geo internal: PERMISSIVE ×3 · never-apply ×4 (:826-832, :842-848,
|
||||
:1031-1034, :1104-1105) · tier-mapping ×2 (:824, :850) ·
|
||||
content_quality-advisory ×2 (:584, :622) · shared-file ×2 (:858,
|
||||
:1047) · llms-honest ×2 (:337, :1066) · cite-sources ×2 (:17, :1089).
|
||||
Cross-agent twins (stay twins — both files dispatch standalone):
|
||||
CWD block · url-guard block · MODE DETECTION · MODE BOUNDARY · R2 ·
|
||||
COVERAGE · NAP rule · RULES section skeleton · C1a · automation rule ·
|
||||
Bing/AI-index action · CDN/WAF check.
|
||||
Agent↔dispatcher duplication (stays — dispatch prompt is per-run
|
||||
context, agent spec serves standalone/no-MODE paths): NAP ×4 total ·
|
||||
shared-file ×7 · security-headers ×5 · domain split · weights 80/20-
|
||||
75/25 · Historique · never-re-derive (test-locked dispatcher side).
|
||||
|
||||
## 7. Contradictions / ambiguities found
|
||||
|
||||
1. seo :1525-1526 + geo :1106 vestigial "automated change logged"
|
||||
(agent applies nothing; geo :959 says dispatcher fills §15).
|
||||
2. Ask-the-user blocks unreachable in dispatched path (seo :64-75,
|
||||
:88-112; geo :127-139, :153-168); /geo:41 states it outright.
|
||||
3. Collect boundary wording: agents "STEP 0-5 ONLY" vs /seo "STEP 2-5
|
||||
only (context replaces STEP 0-1)" — works by prompt override.
|
||||
4. geo judge does live work (sameAs curls :477-492, web_search) unlike
|
||||
pure-judgment seo judge — asymmetric split, by design.
|
||||
5. /harden imposes its own output contract (HARDEN.md, /100) the agent
|
||||
spec never acknowledges; keys on "NARROW-SCOPE" in dispatch prompt.
|
||||
6. "LRN-032" cite is ambiguous in THIS repo (local LRN-032 = different
|
||||
lesson; the NAP lesson is zenquality's registry) — keep the
|
||||
"zenquality" qualifier wherever cited.
|
||||
7. geo :376-377 uncited FAQ-citation-rate claim vs geo :1089-1097
|
||||
cite-sources rule (LRN-131 failure class).
|
||||
8. Score-label parse fragility: client-handover extract_score fallback
|
||||
greps FIRST X/20 in file — losing the `Score SEO` label would
|
||||
silently read `TRAJECTORY TO 17/20` as 17.0. (Latent, downstream.)
|
||||
9. GEO scoring has no deterministic engine (score.py covers SEO axes
|
||||
only) — BDR-073 binds only half the pair.
|
||||
|
||||
## 8. Binding memory (from the analyzer's read-before)
|
||||
|
||||
IN FORCE: BDR-081 (premise) · LRN-139 (when-guidance shape) · BDR-061
|
||||
(bundle+sentinel decision) · BDR-077 (mode split, fail-closed, locks
|
||||
survive) · BDR-073 (deterministic scoring) · BDR-072 (R2 refuse) ·
|
||||
BDR-071 (off-page ceiling + §14 line) · BDR-010/LRN-011 (labeled
|
||||
scores gate) · LRN-133 (omission legible) · LRN-131/132/EVAL-025
|
||||
(WebSearch ≠ verification) · LRN-105 (named ban stays explicit) ·
|
||||
LRN-080/088 (measure before delete → dogfood) · LRN-113 (sweep whole
|
||||
surface) · LRN-093 (no vacuous locks; single-line anchors) ·
|
||||
LRN-126/137 (mode split carries data paths) · BLK-017 (Bing deferred).
|
||||
|
||||
## 9. Open questions → dispatcher decisions (see plan §4b)
|
||||
|
||||
Q1 freeze scope · Q2 census extension · Q3 dedup strategy ·
|
||||
Q4 vestigial lines · Q5 /harden //onboard reconciliation.
|
||||
@@ -0,0 +1,342 @@
|
||||
# PLAN v2 — De-prescribe seo-analyzer.md + geo-analyzer.md for Opus 5
|
||||
|
||||
Date: 2026-07-30 · Branch: feature/seo-geo-deprescription (off develop, started)
|
||||
KIND: build-plan · Author: main-loop session (Fable 5)
|
||||
Parent decision: BDR-081 N5 (deferred as separate project) · Method: LRN-139
|
||||
v2: revised after the 3-lens challenge (§5bis) — every BLOCKER closed by a
|
||||
named change; one confirmation challenger pass follows before execution.
|
||||
|
||||
## 1. Context & evidence (v2 — sizing corrected per simplicity#1)
|
||||
|
||||
Both agents are opus-pinned (BDR-076) → every judge phase runs Opus 5.
|
||||
BDR-081 profile applies: literal following, over-verification when told
|
||||
to verify, conflicting/duplicated rules burn reasoning tokens. These are
|
||||
the LONGEST agent files in the repo (1528 + 1106 l) with real downstream
|
||||
parsers — NOT the densest (measured: ~4.5 directive hits/100 l, ranks
|
||||
20th/22nd; security-auditor is 17/100). What this pass buys, honestly:
|
||||
(a) removal of self-output-verification demands (the one pattern the
|
||||
baseline dogfood caught live: the judge reported "run twice, identical
|
||||
output" — seo:970 firing), (b) removal of vestigial pre-BDR-061 lines
|
||||
and 2 real contradictions, (c) small same-audience/same-range dedup,
|
||||
(d) caps→when-guidance on choreography. The verification apparatus
|
||||
(census + 3-lens challenge + before/after dogfood) is USER-DIRECTED for
|
||||
this chantier, not derived from the density premise.
|
||||
|
||||
## 2. Contract surface (v2 — split per correctness#5)
|
||||
|
||||
### 2a. Machine-parsed (named non-LLM consumer: test, script, or literal
|
||||
grep in a dispatcher step) — byte-frozen
|
||||
- `model: opus`, `MODE: collect|judge|template`, `COLLECTION COMPLETE`
|
||||
(model-routing.test.sh:67-68,150-157).
|
||||
- `fetch.sh crux|queries` + `Performance GSC` (seo), `fetch.sh
|
||||
schema_gen|content_quality` (geo) (seo-data.test.sh:538-543).
|
||||
- `SEO|GEO JUDGE — VERDICT: ERROR(` — dispatcher ERROR CONTRACT
|
||||
fail-closes on it (skills/seo:316-318, skills/geo:65-68).
|
||||
- `## FIX BUNDLE` + sentinel `READY TO APPLY — awaiting dispatcher
|
||||
confirmation` — apply step keys on it (skills/seo:524, skills/geo:101;
|
||||
reused by /harden:366).
|
||||
- `.audit/<seo|geo>-signals-<RUNID>.md` names + fail-closed load.
|
||||
- STEP numbering: dispatchers address ranges literally (seo 2-5/6-11/
|
||||
12-14; geo 0-5/6-12/13-15; depth-matrix:17-19,37).
|
||||
- `**Score SEO** : XX.X / 20` / `**Score GEO** : XX.X / 20` labels —
|
||||
client-handover-writer.md:344-345 labeled grep (BDR-010/LRN-011);
|
||||
losing the SEO label silently falls back to first-X/20-in-file.
|
||||
- Bundle item fields `id: applier: files: current: expected:` — pasted
|
||||
verbatim into hotfixer/feater at L1; `applier: bash` run in-loop.
|
||||
- url-guard call sites: seo-analyzer.md:287-295, geo-analyzer.md:273-280
|
||||
(NOT ":257" as v1 said — robustness#5) + sitemap-URL guard seo:573-582.
|
||||
- `NARROW-SCOPE` keying of the I4 carve-out (seo:981-983) — /harden's
|
||||
dispatch prompt relies on it.
|
||||
|
||||
### 2b. LLM-convention contracts (no code consumer; the dispatcher LLM
|
||||
merges by these shapes) — locked in the census, still frozen
|
||||
`SEO|GEO AGENT RESULT` envelopes · `## SECTION FOR SEO.md §N` ·
|
||||
`## ENTRIES FOR SEO.md` · `SEO|GEO SCORING (` blocks + `COVERAGE
|
||||
SOURCE`/`COVERAGE LIVE` lines + `GLOBAL (weighted)` · `TRAJECTORY TO
|
||||
17/20 (code-only)` · `FIX PLAN (` (seo) · batch labels A-F / G1-G7
|
||||
(tier recognition tolerant, labels nominal) · `COLLECT REPORT` +
|
||||
`STATUS: DONE|BLOCKED` · `Automatisation possible avec:` · §0-§15
|
||||
report skeleton + Historique. CROSS-AGENT NOTES emit-instruction lives
|
||||
in /seo's dispatch prompts (dispatcher-side lock only).
|
||||
|
||||
## 3. Class B invariants — obligation kept, single strongest statement;
|
||||
security ORDERINGS byte-frozen (robustness#5/#7)
|
||||
|
||||
- Guard-first orderings, frozen verbatim: seo:287-291 / geo:273-277
|
||||
("Guard the domain before it reaches a shell… Run the guard FIRST…
|
||||
never 'clean up' the value and retry") + seo:573-582 URL loop.
|
||||
- seo:550 "Record the denominator BEFORE sampling" — the ordering IS
|
||||
the honesty mechanism (a post-hoc denominator is self-serving);
|
||||
frozen; only surrounding prose may compress.
|
||||
- NAP direction rule (LRN-032-zenquality — keep the qualifier, the bare
|
||||
ID is ambiguous in this repo), R2 refuse-to-score (BDR-072), COVERAGE
|
||||
obligations (LRN-133 — note :436-439 is a DISTINCT index-reach
|
||||
obligation, not a repeat), §14 mandatory disclosure lines (BDR-071
|
||||
backlinks verbatim line, I4 security-headers), never-apply/L1
|
||||
(BDR-061; LRN-105 named ban), C1a build-output ban, no-invented-
|
||||
content/DGCCRF, deterministic scoring (BDR-073), fail-closed judge,
|
||||
shared-file Edit-not-Write discipline, honest llms.txt framing,
|
||||
cite-sources (LRN-131).
|
||||
- External-freshness checks are NOT self-verification (robustness#6):
|
||||
seo:1522-1523 + geo:1102-1103 verify a DRIFTING WORLD feeding an
|
||||
AUTO-tier robots.txt edit — kept, reworded as when-guidance ("crawler
|
||||
lists shift; cross-check before emitting G1 from the dated resource").
|
||||
|
||||
## 4. Work items v2
|
||||
|
||||
- P0 SEQUENCING + LIVE-TREE EXPOSURE (robustness#4, conf#2/#3/#4/#9):
|
||||
agents/ resolves through ~/.claude symlinks to the WORKING TREE —
|
||||
edits are live between Edit calls, before any commit. Rules:
|
||||
(1) the FULL baseline completes before the first agent edit —
|
||||
signals + judge reports + TEMPLATE envelopes + merged SEO.md +
|
||||
HUMAN-ACTIONS.md (conf#2: without frozen template artifacts the
|
||||
template-range edits would have no differential and P0 makes one
|
||||
unobtainable later);
|
||||
(2) all baseline artifacts copied to the DURABLE, gitignored
|
||||
`.audit/dogfood-baseline/` in this repo before the first edit
|
||||
(conf#9: the session scratchpad dies with the session/reboot;
|
||||
LRN-124: .audit/** is never committed);
|
||||
(3) freeze window: no /seo //geo //harden //onboard AND no
|
||||
/client-handover (spawns /seo — conf#3) nor any skill transitively
|
||||
dispatching either analyzer, in ANY project, until the after-dogfood
|
||||
verdict;
|
||||
(4) aborts (conf#4): mid-reword interrupt or after-dogfood failure →
|
||||
`git checkout HEAD -- agents/seo-analyzer.md agents/geo-analyzer.md`
|
||||
(in-flight revert, index-safe); `git checkout develop -- agents/…`
|
||||
is reserved for a WHOLE-BRANCH abandon; after an abort the named
|
||||
exit is either (a) fix + re-run the after-dogfood, or (b) present
|
||||
the static evidence (census + git diff review) to the human who may
|
||||
accept or abandon at the gate — no open-ended reverted state.
|
||||
- P1 CENSUS (commit 1, test-only, green pre-reword — compatible with
|
||||
§7's same-commit rule: it locks EXISTING state and changes no agent
|
||||
file; reword commits carry any census DELTA): DONE in working tree —
|
||||
lib/tests/seo-geo-contract.test.sh 54/0, shellcheck clean, real
|
||||
flip-test run: 7 scratch mutations → 7 FAILs (not "by construction" —
|
||||
robustness#10). File-qualified locks (correctness#4): `FIX PLAN (` +
|
||||
`applier: bash` + `Score SEO` seo-only; `Score GEO` geo-only.
|
||||
Incidental locks dropped (CROSS-AGENT NOTE agent-side, bare
|
||||
`applier:`). Item fields locked both files. v3 (conf#5): EVERY
|
||||
`## STEP n —` header locked, interiors included (seo 0-14, geo 0-15)
|
||||
— census now 71/0. Freeze mechanism for the
|
||||
~40 A-sites the census does not cover: reviewed `git diff -U0
|
||||
agents/*.md` on each reword commit (simplicity#4).
|
||||
- P2 REWORD seo-analyzer.md (commit 2):
|
||||
(a) Self-OUTPUT verification, v3 (conf#1/#8 — neither is deleted
|
||||
outright): :970-971 "run it twice" → when-guidance integrity
|
||||
guard ("if the findings JSON changed after scoring, re-run and
|
||||
explain the move" — score.py is deterministic, so a moving
|
||||
output means mutated findings: anti-score-shopping, BDR-073;
|
||||
the unconditional double-run the baseline judge burned goes
|
||||
away, the guard stays); :1217 "Do not proceed until printed" →
|
||||
when-guidance scoped to the single-shot path ("single-shot runs
|
||||
print the FIX PLAN before STEP 12 serializes it" — MODE: judge
|
||||
stops at 11, but /harden //onboard execute the whole file,
|
||||
conf#1). The completeness checklist :1309-1320 is NOT deleted:
|
||||
its routing rows (stock-photo→GATED(E), compression→AUTO(bash)
|
||||
or §11, aggregateRating→AUTO(hotfixer), structural→GATED(D)…)
|
||||
are unique routing content (robustness#3) — reshape into a plain
|
||||
mapping table, drop only the checkbox self-audit framing.
|
||||
(b) DELETE vestigial :1525-1526 (contradicts BDR-061; Q4).
|
||||
(c) DEDUP under the invariant (correctness#1 + robustness#1): only
|
||||
VERBATIM same-AUDIENCE (spec rule / bundle-item payload /
|
||||
phase-local caveat) same-MODE-RANGE (collect 0-5 / judge 6-11 /
|
||||
template 12-14 / RULES=global) repeats merge. Expected survivors
|
||||
per family listed at execution in the commit message; honest
|
||||
net: never-apply 4→3 (RULES pair merges; template-range
|
||||
statements stay), sentinel-verbatim reminders 3→2, landing-page
|
||||
3→2 (payload instance :1260 + one spec statement; :1342 vs
|
||||
:1502 merge), bundle-self-containment 2→1 (same range).
|
||||
NOT deduped (v1 was wrong — distinct rules or cross-range):
|
||||
COVERAGE ×4, 30/70 ×3, security-headers ×3, shared-file
|
||||
discipline (payload vs spec audiences).
|
||||
(d) SOFTEN caps/orderings to when-guidance, keeping semantics:
|
||||
:61, :508 (gate stays before on-page scoring; emphasis drops),
|
||||
:875, :1147, :1149-1157 CMS-plugin-first folded together with
|
||||
:143-148 into ONE statement (correctness#3 — two strengths of
|
||||
one rule otherwise), :1159-1162 Bing (content rule kept, caps
|
||||
drop; FULL-only → statically verified), essays :606-618 +
|
||||
:661-680 compressed keeping the rule + LRN citations; :602-604
|
||||
kept as a when-guidance failure detector ("families ≈ URLs →
|
||||
the heuristic broke — say so"), not deleted (robustness#8).
|
||||
(e) Dispositions completing the C-list (correctness#3): :208-210 →
|
||||
static pointer ("the CDN/WAF twin check lives in geo STEP 4");
|
||||
:1504 KEEP as-is (one-line scope guard).
|
||||
- P3 REWORD geo-analyzer.md (commit 3), same invariant:
|
||||
PERMISSIVE ×3: ALL survive (collect/template/RULES ranges;
|
||||
:873 is the item-level default guarding an unconfirmed AUTO
|
||||
robots.txt edit — named survivor, robustness#9). never-apply 4→3
|
||||
(RULES pair merges). tier-mapping :824/:850 BOTH stay (judge vs
|
||||
template ranges). content_quality-advisory 2→1 (same range).
|
||||
shared-file 2× stays (payload vs spec). llms-honest 2× stays
|
||||
(collect vs RULES). cite-sources 2× stays (:17 guards the header
|
||||
stats specifically). :1106 vestigial → reworded to the truth
|
||||
(dispatcher fills the log — matches :959; Q4). :777-786 caps →
|
||||
plain content rule (FULL-only). :1102-1103 → freshness
|
||||
when-guidance (kept — §3). :394 quantity softened ("substantial,
|
||||
real customer questions"). :48 softened. :124-139 ask-block KEPT
|
||||
(standalone path). Orderings :360/:811/:823 softened. :376-377
|
||||
uncited claim → honest framing (no invented source).
|
||||
- P4 DOGFOOD AFTER (v3 — ordered by decisiveness, conf#7): fresh copy
|
||||
of zenquality-frozen; phases in this order so a mid-run death still
|
||||
leaves the decisive evidence (billing class already realised once):
|
||||
(ii-first) judges fed the FROZEN baseline signals
|
||||
(.audit/dogfood-baseline/) → judge reports vs frozen baseline judge
|
||||
reports, ZERO collect variance — the decisive Opus-judge-prose
|
||||
differential; (iii) templates on those judge reports → envelopes,
|
||||
compared against the frozen BASELINE envelopes — the template
|
||||
verdict anchors on ENVELOPES only (SEO.md/HUMAN-ACTIONS.md are
|
||||
dispatcher-merged by this authoring session, non-attributable —
|
||||
conf#10); (i-last) fresh collects, same pre-answered context →
|
||||
(a) shape check of signals/COLLECT REPORT vs baseline, (b)
|
||||
FIELD-LEVEL diff of the fresh signals vs baseline signals (record
|
||||
blocks, COVERAGE counts, denominators — a shape-valid file with a
|
||||
dropped field must be caught, conf#6), and (c) ONE end-to-end seo
|
||||
judge on the FRESH signals (the domain with the most collect-range
|
||||
edits) so the reworded collect→judge handoff runs at least once.
|
||||
Comparison mechanical-first: presence-assertion script (named home:
|
||||
`.audit/dogfood-baseline/assert-after.sh`, session-reproducible,
|
||||
never committed — conf#11) + a FRESH reader agent diffing
|
||||
before/after WITHOUT this plan in context (correctness#7); the
|
||||
authoring session only arbitrates its report. If the after-run dies:
|
||||
P0(4) abort + named exit applies; no merge request meanwhile.
|
||||
- P5 GATES: make test full suite (census + model-routing + seo-data +
|
||||
no-vacuous-locks) · shellcheck on touched .sh · per-RANGE grep sweep
|
||||
for every deduped family (asserts the named survivor lines exist in
|
||||
their ranges — mode-blind ≥1× sweep is insufficient, robustness#1) ·
|
||||
MEASURED deltas recorded (simplicity#7): wc -l + directive-token
|
||||
census (annex §0 grep set) per file, before/after, into the BDR.
|
||||
(v1's manual MODE/STEP sweep dropped — the census asserts it,
|
||||
simplicity#5.)
|
||||
- P6 CAPITALIZE: BDR (decision, invariant, deltas, alternatives), LRN
|
||||
(audience×range dedup invariant — reusable), journal, CHANGELOG.
|
||||
TODO C1 checked. NO merge (human gate). Checkpoint report includes
|
||||
the DYNAMICALLY-UNVERIFIED list (§6bis).
|
||||
|
||||
## 4b. Dispatcher decisions (v2)
|
||||
|
||||
- Q1 freeze scope: all §2a byte-frozen + §2b frozen via census; the
|
||||
remaining unlocked A-prose freeze = per-commit git diff review.
|
||||
- Q2 census: done (P1), flip-proven.
|
||||
- Q3 dedup: WITHIN-file, same-AUDIENCE, same-MODE-RANGE, verbatim
|
||||
repeats only. Cross-agent + agent↔dispatcher twins stay. (Mechanism
|
||||
note correcting robustness#1's premise: every dispatch loads the FULL
|
||||
agent file; the risk is ATTENTIONAL — a literal-following model told
|
||||
"run STEP 13-15" deprioritizes guidance scoped to another step's
|
||||
body — not access. Same fix either way.)
|
||||
- Q4 vestigial: seo :1525-1526 DELETE; geo :1106 REWORD to
|
||||
dispatcher-owns-log (correctness#6 resolved).
|
||||
- Q5 /harden //onboard: out of scope (N6); their dispatch-prompt
|
||||
contracts are untouched by agent-file rewording; `NARROW-SCOPE`
|
||||
keying frozen (§2a).
|
||||
|
||||
## 5. Dogfood protocol (v2)
|
||||
|
||||
Baseline (DONE for collect+judge SEO; geo judge in flight at v2 time):
|
||||
frozen zenquality copy (no .env), inline pipeline (canonical /seo shape
|
||||
— the nested-CLI attempt died on the CLI monthly spend limit, recorded),
|
||||
absolute PROJECT ROOT in every dispatch, `/seo local conservative`,
|
||||
STEP 0 pre-answered, NAP = NAP-KIT.md (user-confirmed 2026-07-10).
|
||||
Baseline artifacts frozen under the DURABLE `.audit/dogfood-baseline/`
|
||||
(gitignored, never committed — conf#9): signals ×2, judge reports ×2,
|
||||
template ENVELOPES ×2, merged SEO.md, HUMAN-ACTIONS.md (conf#2 — the
|
||||
template phase runs to completion BEFORE the first agent edit).
|
||||
After-run per P4. LIMITS stated honestly
|
||||
(robustness#2): conservative never enters STEP 1b/1.5 (no applier parses
|
||||
an item this run — the item-field contract is census-locked statically);
|
||||
LOCAL never executes STEP 3-4/6-7 FULL branches (Bing/AI-index emission
|
||||
text, live checks — the FULL-only conditionals were exercised and
|
||||
correctly declined in the baseline judge). These stay on the
|
||||
§6bis unverified list for the human gate; a FULL/aggressive dry-run is
|
||||
an OPTION the user may order at checkpoint, not part of this plan.
|
||||
|
||||
## 5bis. CHALLENGE SYNTHESIS (2026-07-30)
|
||||
|
||||
Verdicts: correctness FATAL(3) [1 BLOCKER, 2 MAJOR, 4 MINOR] ·
|
||||
robustness FATAL(9) [3 BLOCKER, 6 MAJOR, 2 MINOR] · simplicity
|
||||
CONCERNS(3) [3 MAJOR, 4 MINOR]. All three lenses returned. Every
|
||||
BLOCKER closed by a named v2 change:
|
||||
- correctness#1 (audience-blind dedup) + robustness#1 (mode-blind
|
||||
dedup) → §4b Q3 invariant + P2(c)/P3 rewritten + P5 per-range sweep.
|
||||
- robustness#2 (dogfood can't reach riskiest edits) → §5 honest limits
|
||||
+ §6bis unverified list + P2(d)/P3 minimal-diff on FULL-only sites +
|
||||
static census cover; FULL/aggressive run offered to the human, not
|
||||
silently added (billing exposure robustness#11).
|
||||
- robustness#3 (routing table misfiled as self-check) → P2(a) keeps
|
||||
routing rows verbatim.
|
||||
Majors adopted: R4 live-tree abort path (P0) · R5 url-guard anchors
|
||||
corrected + security orderings frozen (§2a/§3) · R6 external-freshness
|
||||
kept (§3) · R7 :550 frozen (§3) · R8 :602 kept as detector (P2(d)) ·
|
||||
R9 :873 named survivor (P3) · C2 folded into R2's resolution · C3 full
|
||||
dispositions (P2(d)/(e), P3) · S1 §1 rewritten · S2 controlled
|
||||
judge-replay (P4) · S3 mechanical presence script (P4). Minors adopted:
|
||||
C4 file-qualified locks · C5 §2 split · C6 three inconsistencies
|
||||
resolved (P1 note, Q4, N1 marker) · C7 fresh-reader diff · S4 diff-
|
||||
review freeze · S5 sweep dropped · S6+R10 census corrected+flip-proven ·
|
||||
S7 measured deltas. Rejected/scoped: S1's apparatus-shrinking (the
|
||||
apparatus is user-directed); R1's access premise corrected to
|
||||
attentional (fix adopted unchanged).
|
||||
|
||||
CONFIRMATION PASS (robustness lens, v2 → v3): FATAL(9) — 2 BLOCKER +
|
||||
7 MAJOR/MINOR, all targeting the v2 amendments as asked. Closed by
|
||||
name: conf#1 no-MODE single-shot → §6bis + P2(a) :1217 scoped-softened
|
||||
· conf#2 missing baseline template artifacts → P0(1) full-baseline
|
||||
precondition · conf#3 /client-handover freeze → P0(3) · conf#4 abort
|
||||
HEAD-vs-develop + named exit → P0(4) · conf#5 interior STEP locks →
|
||||
census extended to all headers (71/0) · conf#6 collect→judge seam →
|
||||
P4(i) field-diff + one end-to-end seo judge on fresh signals · conf#7
|
||||
decisiveness order → P4 reordered (ii)→(iii)→(i) · conf#8 :970
|
||||
anti-score-shopping → when-guidance reword, not deletion · conf#9
|
||||
volatile baseline → durable .audit/dogfood-baseline/ · conf#10
|
||||
dispatcher-owned artifacts → envelope-anchored template verdict ·
|
||||
conf#11 script home named. Challenge budget exhausted (1 re-pass max):
|
||||
residual risk goes to the human gate with this record.
|
||||
|
||||
## 6. Explicitly NOT doing
|
||||
|
||||
- N1 No dispatcher (SKILL.md) edits.
|
||||
- N2 No scoring-weight, axis, or depth-matrix changes.
|
||||
- N3 No model-pin changes (BDR-076).
|
||||
- N4 No weakening of class-B invariants (§3 hardened in v2: security
|
||||
orderings byte-frozen).
|
||||
- N5 No new modes, no pipeline reshaping (BDR-077).
|
||||
- N6 No /harden //onboard contract reconciliation (annex §7.5).
|
||||
- N7 No collect-boundary wording fix (works by prompt override).
|
||||
- N8 No cross-agent shared-resource consolidation.
|
||||
- N9 No deterministic GEO score engine (annex §7.9).
|
||||
- N10 No FULL/aggressive dogfood in this plan (user option at gate).
|
||||
|
||||
## 6bis. Dynamically-unverified edit surface (for the human gate)
|
||||
|
||||
Sites edited by P2/P3 that no dogfood run executes: FULL-branch content
|
||||
(seo :1159-1162 Bing emission, geo :777-786 AI-index emission, both
|
||||
freshness when-guidances), apply-path parsing (STEP 1b/1.5 — item
|
||||
pasted into appliers; covered statically by census item-field locks +
|
||||
frozen bundle templates), STEP 6-7 external-presence prose, and the
|
||||
no-MODE single-shot path (conf#1: /harden and /onboard dispatch the
|
||||
agents without a MODE line — "all steps in sequence" — so the whole
|
||||
reworded body drives those runs; every never-apply and ordering
|
||||
statement that path relies on keeps a surviving instance, and :1217
|
||||
is softened-scoped to it, never deleted). Mitigation: minimal diffs
|
||||
there (caps→plain only), census locks, git-diff review.
|
||||
|
||||
## 4c. Backlog surfaced (not this branch)
|
||||
|
||||
- Score-label fallback fragility in client-handover-writer.md (can read
|
||||
`TRAJECTORY TO 17/20` as 17.0 if the label vanishes) — annex §7.8.
|
||||
- Stale lib/ line-number comments pointing at agent lines (annex §1).
|
||||
- Baseline judge's gate observation: /client-handover 17/20 gate passes
|
||||
with an open `critique` finding — "open critique = independent
|
||||
blocker" is worth its own decision.
|
||||
|
||||
## 7. Constraints for challengers
|
||||
|
||||
- Registries append-only; census green throughout; reword commits keep
|
||||
54/0 + model-routing + seo-data locks green.
|
||||
- Agent files symlink-live INCLUDING between Edit calls (P0 abort path).
|
||||
- §2a byte-identical; §2b frozen; STEP numbering preserved; §3 security
|
||||
orderings verbatim.
|
||||
- Dedup only same-audience + same-mode-range verbatim repeats; named
|
||||
survivors per family in commit messages; P5 per-range sweep.
|
||||
- The judge phase is Opus 5; collect/template Sonnet — literal
|
||||
following applies to all (E5 "since 4.7").
|
||||
- Baseline artifacts frozen before first edit; after-run design per P4.
|
||||
@@ -142,6 +142,12 @@ desktop.ini
|
||||
# an update. The source is always re-synced, so no offline copy is needed.
|
||||
skills-external/frontend-design/
|
||||
|
||||
# Emil Design Eng — machine-owned copy curl'd from emilkowalski/skill by
|
||||
# install-plugins.sh (Step 8, when absent) and re-fetched on every update-all.sh
|
||||
# run. Not vendored: tracking it produced a repo diff each time upstream shipped
|
||||
# an edit. The source is always re-fetched, so no offline copy is needed.
|
||||
skills-external/emil-design-eng/
|
||||
|
||||
# Impeccable — machine-owned dist produced by `npx impeccable skills install`
|
||||
# (install-plugins.sh Step 8d, update-all.sh), pinned in plugins.lock.json.
|
||||
# Not vendored: the installer owns the layout and rewrites it on update
|
||||
|
||||
@@ -7,6 +7,23 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
|
||||
## [Unreleased]
|
||||
|
||||
### Changed
|
||||
- **seo-analyzer + geo-analyzer de-prescribed for Opus 5 (BDR-082)** —
|
||||
process choreography converted to when-guidance under an
|
||||
audience×mode-range invariant; self-output verification demands removed
|
||||
(the score-engine "run it twice" became a conditional integrity guard);
|
||||
two pre-BDR-061 vestigial rules fixed; P0/MANDATORY/ALWAYS caps softened
|
||||
to plain content rules. Machine contract byte-frozen and locked by the
|
||||
new `lib/tests/seo-geo-contract.test.sh` census (71 locks, flip-proven);
|
||||
proven by a controlled before/after `/seo` dogfood — judge replay on
|
||||
frozen signals, 42/42 presence assertions on both runs, blind structural
|
||||
reader: interchangeable, recall improved.
|
||||
|
||||
### Added
|
||||
- **`lib/tests/seo-geo-contract.test.sh`** — census locking the seo/geo
|
||||
agent ⇄ dispatcher machine contract: judge verdict grammar, FIX BUNDLE +
|
||||
READY-TO-APPLY sentinel, signals handoff, every STEP header (interiors
|
||||
included), bundle item fields, score labels, scoring blocks, envelope
|
||||
keys (46→71 assertions across the C1 chantier).
|
||||
- **Global instruction layer recalibrated for the Claude 5 family (BDR-081)** —
|
||||
delegation block is now model-neutral when-guidance (the Opus 4.8
|
||||
under-delegation counter inverted on Opus 5, which over-delegates and gets
|
||||
|
||||
+11
-10
@@ -45,7 +45,7 @@ This anchors the agent's output so the user can compare audits over time.
|
||||
effort : <S | M | L> weight: <1-5>
|
||||
```
|
||||
|
||||
Worked examples (1 per axis, copy these patterns when reporting):
|
||||
Worked examples (1 per axis — the reporting shape to match):
|
||||
|
||||
```
|
||||
[HIGH] [ai-crawlers] GPTBot blocked in robots.txt
|
||||
@@ -391,7 +391,7 @@ Emit finding:
|
||||
FAQ PAGE : present at <path> | absent
|
||||
FAQ SCHEMA : FAQPage (collection) | QAPage (single Q) | none
|
||||
Q&A COUNT : <n> | not applicable
|
||||
RECOMMENDATION : CREATE /faq with 20-50 real customer questions (P0 for GEO) | ADD schema to existing page | OK
|
||||
RECOMMENDATION : CREATE /faq with real customer questions (typically dozens — high GEO priority) | ADD schema to existing page | OK
|
||||
```
|
||||
|
||||
If absent and site is informational/service/B2B → emit as MEDIUM-term
|
||||
@@ -774,9 +774,8 @@ High-impact, low-effort. For each:
|
||||
- Expected impact (high/medium/low)
|
||||
- AUTO (bundled in STEP 13, applied by the dispatcher) or USER (documented in §11 of SEO.md)
|
||||
|
||||
**MANDATORY user action — AI index submission**: every FULL audit
|
||||
MUST emit these 3 user actions (they are the entry points for AI
|
||||
search engines into your site):
|
||||
**AI index submission** (FULL audits — emit these 3 user actions;
|
||||
they are the entry points for AI search engines into the site):
|
||||
|
||||
1. **Bing Webmaster Tools** — submit + verify sitemap. Critical
|
||||
because ChatGPT Search, Copilot, DuckDuckGo index through Bing.
|
||||
@@ -808,7 +807,8 @@ Additionally, if business is local: **Apple Business Connect**
|
||||
|
||||
## STEP 12 — TRIAGE FIX BATCHES `[both]`
|
||||
|
||||
Consolidate EVERY finding from STEPs 4-9 into structured batches.
|
||||
Consolidate the findings from STEPs 4-9 into structured batches —
|
||||
every finding lands in exactly one batch.
|
||||
|
||||
| Batch | Agent | Scope | Confirmation |
|
||||
|---|---|---|---|
|
||||
@@ -820,7 +820,8 @@ Consolidate EVERY finding from STEPs 4-9 into structured batches.
|
||||
| **G6 — Entity @id + sameAs wiring** | `feater` | JSON-LD graph restructure | No |
|
||||
| **G7 — User actions** | documented in §11 | Wikidata, KP, monitoring | N/A |
|
||||
|
||||
Print the plan before STEP 13, then map into the bundle tiers:
|
||||
Single-shot runs (no MODE line) print this plan before STEP 13
|
||||
serializes it; `MODE: judge` simply ends at STEP 12. Tier mapping:
|
||||
G1–G4/G6 → AUTO, G5 → GATED, G7 → USER ACTIONS.
|
||||
|
||||
**Apply-vs-report is the DISPATCHER's call, not yours.** You ALWAYS emit
|
||||
@@ -1101,6 +1102,6 @@ PROCHAINE ETAPE : <highest-priority>
|
||||
`automation-catalog.md`. No exceptions.
|
||||
- **WebSearch on FULL audits** to cross-check crawler list + tool
|
||||
landscape before emitting — these shift quickly.
|
||||
- **Dispatcher verifies.** Build pass + invalid-JSON-LD revert happen in
|
||||
the dispatcher after it applies the bundle — never in this agent.
|
||||
- **Transparency.** Every automated change logged in §14.
|
||||
- **Dispatcher verifies.** Build pass, invalid-JSON-LD revert and the
|
||||
applied-change log (SEO.md §15) happen in the dispatcher after it
|
||||
applies the bundle — never in this agent.
|
||||
|
||||
+54
-79
@@ -58,8 +58,8 @@ STEP 1-2 business/tech context is consumed by all later steps).
|
||||
|
||||
## STEP 0 — AUDIT DEPTH
|
||||
|
||||
**First action.** If a parent skill (`/seo` dispatcher) passed depth
|
||||
in $ARGUMENTS, use it. Otherwise:
|
||||
If a parent skill (`/seo` dispatcher) passed depth in $ARGUMENTS, use
|
||||
it. Otherwise:
|
||||
|
||||
```
|
||||
SEO AUDIT DEPTH — choose one:
|
||||
@@ -141,11 +141,10 @@ Record rendering: **SSR / SSG / SPA / hybrid / ISR**.
|
||||
|
||||
### CMS detection + SEO plugin presence (plugin-first strategy)
|
||||
|
||||
Before proposing any manual edit, detect if the site runs on a CMS
|
||||
and whether a SEO plugin is already handling the heavy lifting. If a
|
||||
CMS is detected WITHOUT a SEO plugin, the highest-priority quick win
|
||||
is to install the appropriate plugin — editing theme files manually
|
||||
is a last resort and creates maintenance debt.
|
||||
Detect whether the site runs on a CMS and whether a SEO plugin is
|
||||
already handling the heavy lifting; record the signals. The
|
||||
plugin-first ranking policy (CMS without plugin → installation is the
|
||||
top quick win) lives in STEP 10.
|
||||
|
||||
```bash
|
||||
# WordPress signals
|
||||
@@ -206,8 +205,7 @@ topology — TLS terminated upstream, the origin sees plain HTTP plus
|
||||
|
||||
`/harden` reuses this agent for its entire config-hardening axis, so a wrong
|
||||
topology call scores a client's server config against a file that never ran.
|
||||
geo-analyzer STEP 4 already carries the matching CDN/WAF-override check —
|
||||
keep the two consistent.
|
||||
(The same CDN/WAF-override check lives in geo-analyzer STEP 4.)
|
||||
|
||||
```bash
|
||||
# Server / hosting
|
||||
@@ -505,7 +503,7 @@ Fetch rendered HTML. Extract and analyze:
|
||||
|
||||
## STEP 5 — ON-PAGE AUDIT `[both]`
|
||||
|
||||
### Rendering gate — run this BEFORE anything else in STEP 5 (R2)
|
||||
### Rendering gate (R2) — it gates every on-page check below
|
||||
|
||||
```bash
|
||||
bash ~/.claude/lib/seo-data/fetch.sh rendercheck --url "https://$DOMAIN/"
|
||||
@@ -599,9 +597,9 @@ doorway-page risk — the exact thing the 30/70 rule exists to catch — is
|
||||
invisible. Group by shared parent AND by shared slug prefix; if ≥3 URLs share
|
||||
a prefix of 2+ hyphen tokens, that is a family whatever the depth.
|
||||
|
||||
Sanity-check the grouping before trusting it: a site whose sitemap yields
|
||||
almost as many families as URLs has probably defeated your heuristic, not
|
||||
proved it has no templates.
|
||||
A sitemap that yields almost as many families as URLs has probably
|
||||
defeated the heuristic, not proved the site has no templates — say so
|
||||
instead of trusting the grouping.
|
||||
|
||||
**Sample by finding class, because the classes need opposite samples:**
|
||||
|
||||
@@ -611,10 +609,9 @@ proved it has no templates.
|
||||
| **Duplication / 30-70 / cannibalisation** | **≥3 from the LARGEST family** | invisible with one page each. You cannot tell whether 25 city pages are 70% unique by reading one of them. |
|
||||
| Per-page content (title/description length, H1 wording) | spread across families + GSC position 4-10 quick wins | these vary per page even from one template. |
|
||||
|
||||
"One per template" is right for code and **wrong for the 30/70 rule** — a
|
||||
rule this spec mandates in §9. Sampling one page per family makes that check
|
||||
structurally impossible, so take the third page of the biggest family even
|
||||
though it is "the same template".
|
||||
The split is deliberate: one-per-family alone makes the §9 30/70 check
|
||||
structurally impossible — hence ≥3 pages from the biggest family, even
|
||||
though they share a template.
|
||||
|
||||
An un-sampled family is an un-audited family. Name the ones you skipped.
|
||||
|
||||
@@ -658,16 +655,11 @@ mapfile -t FEXCL < <(bash ~/.claude/lib/source-scope.sh findargs)
|
||||
find . "${FEXCL[@]}" -type f \( -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.png" -o -iname "*.gif" \) -printf "%s %p\n" 2>/dev/null | sort -rn | head -20
|
||||
```
|
||||
|
||||
**Why the guard, and why `find` specifically (C1a).** `grep` and `find`
|
||||
disagree about this repo and you use both. Claude Code routes `grep` through
|
||||
ugrep with `--ignore-files`, so it honours `.gitignore` and never descends
|
||||
into a gitignored `dist/`. `find` honours nothing. Measured on a real Astro
|
||||
repo: this command returned **92 images, 45 of them under `dist/`** — every
|
||||
asset twice, source and generated copy, byte-identical. So "top 20 by size"
|
||||
was ~10 real images dressed as 20, and a batch-C item
|
||||
(`cwebp -q 80 <img> -o <img>.webp`) could target `dist/og-image.png`, whose
|
||||
`.webp` the dispatcher's own `npm run build` then erases. The fix lands,
|
||||
verification passes, nothing survives.
|
||||
**Why the guard, and why `find` specifically (C1a).** Claude Code routes
|
||||
`grep` through ugrep with `--ignore-files` (honours `.gitignore`); `find`
|
||||
honours nothing. Measured on a real Astro repo: without the guard this
|
||||
command returned 92 images, 45 under `dist/` — and a batch-C item built
|
||||
on that targets an artifact the dispatcher's own `npm run build` erases.
|
||||
|
||||
`FEXCL` MUST be consumed as a quoted array. `find . $FEXCL …` lets the shell
|
||||
glob `*/dist/*` against the CWD and hand the matches to find as search paths
|
||||
@@ -967,8 +959,9 @@ disagree, and `/client-handover` gates on 17/20.
|
||||
**N/A is not a zero** and the engine will not let it behave like one.
|
||||
- `status: "error"` → malformed findings. Fix them; never fall back to
|
||||
eyeballing a number.
|
||||
- Run it twice on the same file before publishing. If the output moved, your
|
||||
findings moved, and that is the thing to explain.
|
||||
- The engine is deterministic: if you modified the findings JSON after
|
||||
scoring, re-run and explain the move — a shifted score means shifted
|
||||
findings, never engine noise.
|
||||
|
||||
**Technical axis note:** CWV scored on CrUX field data (75th percentile,
|
||||
real users, from STEP 4) when available; otherwise lab PageSpeed
|
||||
@@ -1144,22 +1137,19 @@ For each:
|
||||
- Expected impact (high / medium / low)
|
||||
- AUTO (bundled in STEP 12, applied by the dispatcher) or USER (in SEO.md §11, with automation options)
|
||||
|
||||
AUTO items are a commitment, not a suggestion.
|
||||
**CMS plugin first**: a CMS detected in STEP 2 without a SEO plugin
|
||||
makes plugin installation the top quick win —
|
||||
RankMath/Yoast/SEOPress (WordPress), Yoast SEO (Drupal), SEO Suite
|
||||
Ultimate (Magento), Plug in SEO (Shopify) deliver meta + sitemap +
|
||||
OG + breadcrumbs + JSON-LD in ~15 min of admin UI, where hand-editing
|
||||
theme files first creates duplication, conflicts, and maintenance
|
||||
debt. See `~/.claude/agents/resources/automation-catalog.md` CMS
|
||||
plugins section for the exact install path per CMS.
|
||||
|
||||
**P0 rule — CMS plugin first**: if STEP 2 detected a CMS without a
|
||||
SEO plugin, the FIRST quick win MUST be plugin installation. Reason:
|
||||
installing RankMath/Yoast/SEOPress (WordPress), Yoast SEO (Drupal),
|
||||
SEO Suite Ultimate (Magento), Plug in SEO (Shopify) takes ~15 min
|
||||
via admin UI and delivers meta + sitemap + OG + breadcrumbs + JSON-LD
|
||||
in one shot. Editing theme files by hand before this creates
|
||||
duplication, conflicts, and maintenance debt. See
|
||||
`~/.claude/agents/resources/automation-catalog.md` CMS plugins
|
||||
section for the exact install path per CMS.
|
||||
|
||||
**P0 rule — Bing Webmaster Tools**: on FULL audit, ALWAYS emit
|
||||
"Submit site to Bing Webmaster Tools" as a user action — ChatGPT
|
||||
Search uses the Bing index, so this is also a GEO signal. See
|
||||
automation-catalog.md for IndexNow + Bing.
|
||||
**Bing Webmaster Tools** (FULL audits): emit "Submit site to Bing
|
||||
Webmaster Tools" as a user action — ChatGPT Search uses the Bing
|
||||
index, so this is also a GEO signal. See automation-catalog.md for
|
||||
IndexNow + Bing.
|
||||
|
||||
### Medium term (1-3 months)
|
||||
City/service pages (30/70 rule: 30% shared, 70% unique per city),
|
||||
@@ -1214,7 +1204,8 @@ BATCH F — USER ACTIONS (N items, documented in SEO.md §11 with automation cat
|
||||
...
|
||||
```
|
||||
|
||||
Do not proceed to STEP 12 until this plan is printed.
|
||||
Single-shot runs (no MODE line) print this plan before STEP 12
|
||||
serializes it; `MODE: judge` simply ends here.
|
||||
|
||||
---
|
||||
|
||||
@@ -1306,18 +1297,19 @@ as the last line of the bundle — the dispatcher keys its apply step on it.
|
||||
Do NOT run any post-fix verification (build/lint, NAP consistency); the
|
||||
dispatcher does that after it applies. Your job ends at the sentinel.
|
||||
|
||||
### Bundle completeness checklist (did every finding reach the bundle?)
|
||||
### Finding-class → tier routing (complete map: every finding lands in
|
||||
exactly one tier; §11 mirrors USER ACTIONS)
|
||||
|
||||
- [ ] Meta/title/OG/canonical → AUTO (hotfixer)
|
||||
- [ ] JSON-LD LocalBusiness/Organization → AUTO (hotfixer/feater) — detailed GEO schema → geo-analyzer
|
||||
- [ ] Image alt/dimensions → AUTO (hotfixer); compression → AUTO (bash) or §11 if tools absent
|
||||
- [ ] robots.txt / sitemap.xml → AUTO (hotfixer) — AI-bot directives → geo-analyzer
|
||||
- [ ] .htaccess security headers, image/video sitemap, hreflang → AUTO (feater)
|
||||
- [ ] Legal pages, CMP, footer links → AUTO (feater)
|
||||
- [ ] Heading hierarchy, noindex on technical pages → AUTO (hotfixer)
|
||||
- [ ] Unverifiable aggregateRating removal → AUTO (hotfixer); stock-photo testimonials → GATED (E)
|
||||
- [ ] Structural / new pages → GATED (D)
|
||||
- [ ] Video transcripts, GMB, directories → USER ACTIONS (§11)
|
||||
- Meta/title/OG/canonical → AUTO (hotfixer)
|
||||
- JSON-LD LocalBusiness/Organization → AUTO (hotfixer/feater) — detailed GEO schema → geo-analyzer
|
||||
- Image alt/dimensions → AUTO (hotfixer); compression → AUTO (bash) or §11 if tools absent
|
||||
- robots.txt / sitemap.xml → AUTO (hotfixer) — AI-bot directives → geo-analyzer
|
||||
- .htaccess security headers, image/video sitemap, hreflang → AUTO (feater)
|
||||
- Legal pages, CMP, footer links → AUTO (feater)
|
||||
- Heading hierarchy, noindex on technical pages → AUTO (hotfixer)
|
||||
- Unverifiable aggregateRating removal → AUTO (hotfixer); stock-photo testimonials → GATED (E)
|
||||
- Structural / new pages → GATED (D)
|
||||
- Video transcripts, GMB, directories → USER ACTIONS (§11)
|
||||
|
||||
### Framework-specific notes
|
||||
|
||||
@@ -1339,23 +1331,6 @@ Carry the relevant note into each bundle item so the applier honors it:
|
||||
- **Ghost** — Native SEO strong (meta + OG + JSON-LD out of box). Usually no plugin needed; handle gaps via `default.hbs` edits.
|
||||
- **Wix / Squarespace / Webflow (hosted CMS)** — No theme file access. ALL SEO changes happen in the admin UI: meta, alt, sitemap, redirects, JSON-LD (partial). Agent emits detailed USER action list per panel to touch — cannot auto-apply anything.
|
||||
|
||||
### Landing page rule
|
||||
|
||||
Zero visible change on landing/homepage except:
|
||||
- Meta tags (invisible)
|
||||
- Footer links (discreet)
|
||||
- JSON-LD (invisible)
|
||||
- Image fixes: compression, alt, dimensions (invisible or quasi)
|
||||
|
||||
Anything else → batch D (confirmation).
|
||||
|
||||
### Handoff to dispatcher
|
||||
|
||||
Post-fix verification (build/lint, NAP consistency across JSON-LD /
|
||||
visible / GMB, revert-on-break) and the §15 change log are the
|
||||
DISPATCHER's responsibility, AFTER it applies the bundle at L1. You
|
||||
emitted the bundle terminated by the sentinel — stop here.
|
||||
|
||||
---
|
||||
|
||||
## STEP 13 — OUTPUT `[both]`
|
||||
@@ -1519,10 +1494,10 @@ PROCHAINE ETAPE : <highest-priority>
|
||||
### Process
|
||||
- **Every user action lists automation.** Mandatory from
|
||||
`~/.claude/agents/resources/automation-catalog.md`.
|
||||
- **WebSearch on FULL** to validate tool landscape + cross-check
|
||||
competitor state before emitting.
|
||||
- **WebSearch on FULL when naming drifting externals** — tool
|
||||
landscapes and competitor state shift; cross-check before a
|
||||
recommendation names them.
|
||||
- **Iterative SEO.md.** Preserve Historique section.
|
||||
- **Transparency.** Every automated change logged with file, change,
|
||||
reason.
|
||||
- **Dispatcher verifies.** Build/lint pass + revert-on-break happen in
|
||||
the dispatcher after it applies the bundle — never in this agent.
|
||||
- **Dispatcher verifies.** Build/lint pass, revert-on-break and the §15
|
||||
change log happen in the dispatcher after it applies the bundle —
|
||||
never in this agent.
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
#!/usr/bin/env bash
|
||||
# lib/tests/seo-geo-contract.test.sh — census: seo/geo agent ⇄ dispatcher
|
||||
# machine contract (C1 de-prescription, 2026-07-30). Locks every string a
|
||||
# consumer parses BEFORE the choreography reword, so the reword commits
|
||||
# prove contract preservation by keeping this green. Complements
|
||||
# model-routing.test.sh (which already locks model pins + MODE:* +
|
||||
# COLLECTION COMPLETE).
|
||||
set -u
|
||||
R="$(cd "$(dirname "$0")/../.." && pwd)"
|
||||
pass=0; fail=0
|
||||
ok() { pass=$((pass+1)); }
|
||||
ko() { fail=$((fail+1)); printf 'FAIL %s\n' "$1"; }
|
||||
has() { if grep -qF "$2" "$R/$1"; then ok; else ko "$1 missing: $2"; fi; }
|
||||
|
||||
SEO=agents/seo-analyzer.md
|
||||
GEO=agents/geo-analyzer.md
|
||||
|
||||
# 1) judge verdict grammar — DISPATCHER ERROR CONTRACT (skills/seo STEP 1,
|
||||
# skills/geo STEP 1B) fail-closes on this exact shape
|
||||
has "$SEO" 'SEO JUDGE — VERDICT: ERROR('
|
||||
has "$GEO" 'GEO JUDGE — VERDICT: ERROR('
|
||||
has "skills/seo/SKILL.md" 'SEO JUDGE — VERDICT: ERROR('
|
||||
has "skills/geo/SKILL.md" 'GEO JUDGE — VERDICT: ERROR('
|
||||
|
||||
# 2) fix-bundle section + apply sentinel — parsed by /seo STEP 1b/1.5 and
|
||||
# /geo STEP 1b/2 before any L1 apply
|
||||
for f in "$SEO" "$GEO" skills/seo/SKILL.md skills/geo/SKILL.md; do
|
||||
has "$f" '## FIX BUNDLE'
|
||||
has "$f" 'READY TO APPLY — awaiting dispatcher confirmation'
|
||||
done
|
||||
|
||||
# 3) signals handoff — judge loads the collect artifact fail-closed
|
||||
has "$SEO" '.audit/seo-signals-'
|
||||
has "$GEO" '.audit/geo-signals-'
|
||||
has "skills/seo/SKILL.md" '.audit/seo-signals-<RUNID_SEO>.md'
|
||||
has "skills/geo/SKILL.md" '.audit/geo-signals-<RUNID>.md'
|
||||
|
||||
# 4) STEP numbering — dispatchers reference agent step ranges literally:
|
||||
# /seo: "STEP 2-5" collect · "STEP 6-11" seo judge · "STEP 6-12" geo
|
||||
# judge · "STEP 12-14" seo template · "STEP 13-15" geo template;
|
||||
# /geo: "STEP 0-5". Lock EVERY step header on the agent side (interiors
|
||||
# too — merging/renumbering one silently re-points the dispatch ranges)
|
||||
# and the ranges on the dispatcher side.
|
||||
for n in 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14; do has "$SEO" "## STEP $n —"; done
|
||||
for n in 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15; do has "$GEO" "## STEP $n —"; done
|
||||
has "skills/seo/SKILL.md" 'STEP 2-5'
|
||||
has "skills/seo/SKILL.md" 'STEP 6-11'
|
||||
has "skills/seo/SKILL.md" 'STEP 6-12'
|
||||
has "skills/seo/SKILL.md" 'STEP 12-14'
|
||||
has "skills/seo/SKILL.md" 'STEP 13-15'
|
||||
has "skills/geo/SKILL.md" 'STEP 0-5'
|
||||
has "skills/geo/SKILL.md" '6-12, report scoring' # "STEP\n6-12" line-wraps
|
||||
has "skills/geo/SKILL.md" 'STEP 13-15'
|
||||
|
||||
# 5) collect-mode report emission (dispatcher waits on it between phases)
|
||||
has "$SEO" 'COLLECT REPORT'
|
||||
has "$GEO" 'COLLECT REPORT'
|
||||
|
||||
# 6) bundle-item routing + the item fields the L1 appliers parse
|
||||
# (the item is pasted verbatim into hotfixer/feater — /seo STEP 1.5)
|
||||
for f in "$SEO" "$GEO"; do
|
||||
has "$f" 'applier: hotfixer'
|
||||
has "$f" 'applier: feater'
|
||||
has "$f" ' files:'
|
||||
has "$f" ' current:'
|
||||
has "$f" ' expected:'
|
||||
done
|
||||
has "$SEO" 'applier: bash'
|
||||
|
||||
# 7) cross-agent escalation block — merged into SEO.md §11 by /seo STEP 2.
|
||||
# The emit instruction lives in /seo's DISPATCH PROMPTS, not in the agent
|
||||
# specs (geo-analyzer.md never mentions it; seo-analyzer.md only once,
|
||||
# incidentally — NOT locked, it is prose). Lock the dispatcher side only.
|
||||
has "skills/seo/SKILL.md" 'CROSS-AGENT NOTES TO'
|
||||
|
||||
# 8) trajectory block — mandatory in envelopes (/geo audit-end deliverables,
|
||||
# /seo §1 merge)
|
||||
has "$SEO" 'TRAJECTORY TO 17/20'
|
||||
has "$GEO" 'TRAJECTORY TO 17/20'
|
||||
|
||||
printf 'seo-geo contract locks: %d pass, %d fail\n' "$pass" "$fail"
|
||||
[ "$fail" -eq 0 ]
|
||||
+1
-1
@@ -36,7 +36,7 @@
|
||||
"source": "https://github.com/emilkowalski/skill",
|
||||
"path": "skills/emil-design-eng/SKILL.md",
|
||||
"managed_by": "curl",
|
||||
"note": "Emil Kowalski's design engineering skill — UI polish, animations, component craft. Downloaded to skills-external/emil-design-eng/, symlinked by link.sh."
|
||||
"note": "Emil Kowalski's design engineering skill — UI polish, animations, component craft. Machine-owned: curl'd to skills-external/emil-design-eng/ (gitignored, re-fetched by update-all.sh), symlinked by link.sh."
|
||||
},
|
||||
"impeccable": {
|
||||
"source": "npm:impeccable",
|
||||
|
||||
@@ -1,679 +0,0 @@
|
||||
---
|
||||
name: emil-design-eng
|
||||
description: This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.
|
||||
---
|
||||
|
||||
# Design Engineering
|
||||
|
||||
## Initial Response
|
||||
|
||||
When this skill is first invoked without a specific question, respond only with:
|
||||
|
||||
> I'm ready to help you build interfaces that feel right, my knowledge comes from Emil Kowalski's design engineering philosophy. If you want to dive even deeper, check out Emil’s course: [animations.dev](https://animations.dev/).
|
||||
|
||||
Do not provide any other information until the user asks a question.
|
||||
|
||||
You are a design engineer with the craft sensibility. You build interfaces where every detail compounds into something that feels right. You understand that in a world where everyone's software is good enough, taste is the differentiator.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
### Taste is trained, not innate
|
||||
|
||||
Good taste is not personal preference. It is a trained instinct: the ability to see beyond the obvious and recognize what elevates. You develop it by surrounding yourself with great work, thinking deeply about why something feels good, and practicing relentlessly.
|
||||
|
||||
When building UI, don't just make it work. Study why the best interfaces feel the way they do. Reverse engineer animations. Inspect interactions. Be curious.
|
||||
|
||||
### Unseen details compound
|
||||
|
||||
Most details users never consciously notice. That is the point. When a feature functions exactly as someone assumes it should, they proceed without giving it a second thought. That is the goal.
|
||||
|
||||
> "All those unseen details combine to produce something that's just stunning, like a thousand barely audible voices all singing in tune." - Paul Graham
|
||||
|
||||
Every decision below exists because the aggregate of invisible correctness creates interfaces people love without knowing why.
|
||||
|
||||
### Beauty is leverage
|
||||
|
||||
People select tools based on the overall experience, not just functionality. Good defaults and good animations are real differentiators. Beauty is underutilized in software. Use it as leverage to stand out.
|
||||
|
||||
## Review Format (Required)
|
||||
|
||||
When reviewing UI code, you MUST use a markdown table with Before/After columns. Do NOT use a list with "Before:" and "After:" on separate lines. Always output an actual markdown table like this:
|
||||
|
||||
| Before | After | Why |
|
||||
| --- | --- | --- |
|
||||
| `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; avoid `all` |
|
||||
| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing in the real world appears from nothing |
|
||||
| `ease-in` on dropdown | `ease-out` with custom curve | `ease-in` feels sluggish; `ease-out` gives instant feedback |
|
||||
| No `:active` state on button | `transform: scale(0.97)` on `:active` | Buttons must feel responsive to press |
|
||||
| `transform-origin: center` on popover | `transform-origin: var(--radix-popover-content-transform-origin)` | Popovers should scale from their trigger (not modals — modals stay centered) |
|
||||
|
||||
Wrong format (never do this):
|
||||
|
||||
```
|
||||
Before: transition: all 300ms
|
||||
After: transition: transform 200ms ease-out
|
||||
────────────────────────────
|
||||
Before: scale(0)
|
||||
After: scale(0.95)
|
||||
```
|
||||
|
||||
Correct format: A single markdown table with | Before | After | Why | columns, one row per issue found. The "Why" column briefly explains the reasoning.
|
||||
|
||||
## The Animation Decision Framework
|
||||
|
||||
Before writing any animation code, answer these questions in order:
|
||||
|
||||
### 1. Should this animate at all?
|
||||
|
||||
**Ask:** How often will users see this animation?
|
||||
|
||||
| Frequency | Decision |
|
||||
| ----------------------------------------------------------- | ---------------------------- |
|
||||
| 100+ times/day (keyboard shortcuts, command palette toggle) | No animation. Ever. |
|
||||
| Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |
|
||||
| Occasional (modals, drawers, toasts) | Standard animation |
|
||||
| Rare/first-time (onboarding, feedback forms, celebrations) | Can add delight |
|
||||
|
||||
**Never animate keyboard-initiated actions.** These actions are repeated hundreds of times daily. Animation makes them feel slow, delayed, and disconnected from the user's actions.
|
||||
|
||||
Raycast has no open/close animation. That is the optimal experience for something used hundreds of times a day.
|
||||
|
||||
### 2. What is the purpose?
|
||||
|
||||
Every animation must have a clear answer to "why does this animate?"
|
||||
|
||||
Valid purposes:
|
||||
|
||||
- **Spatial consistency**: toast enters and exits from the same direction, making swipe-to-dismiss feel intuitive
|
||||
- **State indication**: a morphing feedback button shows the state change
|
||||
- **Explanation**: a marketing animation that shows how a feature works
|
||||
- **Feedback**: a button scales down on press, confirming the interface heard the user
|
||||
- **Preventing jarring changes**: elements appearing or disappearing without transition feel broken
|
||||
|
||||
If the purpose is just "it looks cool" and the user will see it often, don't animate.
|
||||
|
||||
### 3. What easing should it use?
|
||||
|
||||
Is the element entering or exiting?
|
||||
Yes → ease-out (starts fast, feels responsive)
|
||||
No →
|
||||
Is it moving/morphing on screen?
|
||||
Yes → ease-in-out (natural acceleration/deceleration)
|
||||
Is it a hover/color change?
|
||||
Yes → ease
|
||||
Is it constant motion (marquee, progress bar)?
|
||||
Yes → linear
|
||||
Default → ease-out
|
||||
|
||||
**Critical: use custom easing curves.** The built-in CSS easings are too weak. They lack the punch that makes animations feel intentional.
|
||||
|
||||
```css
|
||||
/* Strong ease-out for UI interactions */
|
||||
--ease-out: cubic-bezier(0.23, 1, 0.32, 1);
|
||||
|
||||
/* Strong ease-in-out for on-screen movement */
|
||||
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
|
||||
|
||||
/* iOS-like drawer curve (from Ionic Framework) */
|
||||
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
|
||||
```
|
||||
|
||||
**Never use ease-in for UI animations.** It starts slow, which makes the interface feel sluggish and unresponsive. A dropdown with `ease-in` at 300ms _feels_ slower than `ease-out` at the same 300ms, because ease-in delays the initial movement — the exact moment the user is watching most closely.
|
||||
|
||||
**Easing curve resources:** Don't create curves from scratch. Use [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/) to find stronger custom variants of standard easings.
|
||||
|
||||
### 4. How fast should it be?
|
||||
|
||||
| Element | Duration |
|
||||
| ------------------------ | ------------- |
|
||||
| Button press feedback | 100-160ms |
|
||||
| Tooltips, small popovers | 125-200ms |
|
||||
| Dropdowns, selects | 150-250ms |
|
||||
| Modals, drawers | 200-500ms |
|
||||
| Marketing/explanatory | Can be longer |
|
||||
|
||||
**Rule: UI animations should stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one. A faster-spinning spinner makes the app feel like it loads faster, even when the load time is identical.
|
||||
|
||||
### Perceived performance
|
||||
|
||||
Speed in animation is not just about feeling snappy — it directly affects how users perceive your app's performance:
|
||||
|
||||
- A **fast-spinning spinner** makes loading feel faster (same load time, different perception)
|
||||
- A **180ms select** animation feels more responsive than a **400ms** one
|
||||
- **Instant tooltips** after the first one is open (skip delay + skip animation) make the whole toolbar feel faster
|
||||
|
||||
The perception of speed matters as much as actual speed. Easing amplifies this: `ease-out` at 200ms _feels_ faster than `ease-in` at 200ms because the user sees immediate movement.
|
||||
|
||||
## Spring Animations
|
||||
|
||||
Springs feel more natural than duration-based animations because they simulate real physics. They don't have fixed durations — they settle based on physical parameters.
|
||||
|
||||
### When to use springs
|
||||
|
||||
- Drag interactions with momentum
|
||||
- Elements that should feel "alive" (like Apple's Dynamic Island)
|
||||
- Gestures that can be interrupted mid-animation
|
||||
- Decorative mouse-tracking interactions
|
||||
|
||||
### Spring-based mouse interactions
|
||||
|
||||
Tying visual changes directly to mouse position feels artificial because it lacks motion. Use `useSpring` from Motion (formerly Framer Motion) to interpolate value changes with spring-like behavior instead of updating immediately.
|
||||
|
||||
```jsx
|
||||
import { useSpring } from 'framer-motion';
|
||||
|
||||
// Without spring: feels artificial, instant
|
||||
const rotation = mouseX * 0.1;
|
||||
|
||||
// With spring: feels natural, has momentum
|
||||
const springRotation = useSpring(mouseX * 0.1, {
|
||||
stiffness: 100,
|
||||
damping: 10,
|
||||
});
|
||||
```
|
||||
|
||||
This works because the animation is **decorative** — it doesn't serve a function. If this were a functional graph in a banking app, no animation would be better. Know when decoration helps and when it hinders.
|
||||
|
||||
### Spring configuration
|
||||
|
||||
**Apple's approach (recommended — easier to reason about):**
|
||||
|
||||
```js
|
||||
{ type: "spring", duration: 0.5, bounce: 0.2 }
|
||||
```
|
||||
|
||||
**Traditional physics (more control):**
|
||||
|
||||
```js
|
||||
{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
|
||||
```
|
||||
|
||||
Keep bounce subtle (0.1-0.3) when used. Avoid bounce in most UI contexts. Use it for drag-to-dismiss and playful interactions.
|
||||
|
||||
### Interruptibility advantage
|
||||
|
||||
Springs maintain velocity when interrupted — CSS animations and keyframes restart from zero. This makes springs ideal for gestures users might change mid-motion. When you click an expanded item and quickly press Escape, a spring-based animation smoothly reverses from its current position.
|
||||
|
||||
## Component Building Principles
|
||||
|
||||
### Buttons must feel responsive
|
||||
|
||||
Add `transform: scale(0.97)` on `:active`. This gives instant feedback, making the UI feel like it is truly listening to the user.
|
||||
|
||||
```css
|
||||
.button {
|
||||
transition: transform 160ms ease-out;
|
||||
}
|
||||
|
||||
.button:active {
|
||||
transform: scale(0.97);
|
||||
}
|
||||
```
|
||||
|
||||
This applies to any pressable element. The scale should be subtle (0.95-0.98).
|
||||
|
||||
### Never animate from scale(0)
|
||||
|
||||
Nothing in the real world disappears and reappears completely. Elements animating from `scale(0)` look like they come out of nowhere.
|
||||
|
||||
Start from `scale(0.9)` or higher, combined with opacity. Even a barely-visible initial scale makes the entrance feel more natural, like a balloon that has a visible shape even when deflated.
|
||||
|
||||
```css
|
||||
/* Bad */
|
||||
.entering {
|
||||
transform: scale(0);
|
||||
}
|
||||
|
||||
/* Good */
|
||||
.entering {
|
||||
transform: scale(0.95);
|
||||
opacity: 0;
|
||||
}
|
||||
```
|
||||
|
||||
### Make popovers origin-aware
|
||||
|
||||
Popovers should scale in from their trigger, not from center. The default `transform-origin: center` is wrong for almost every popover. **Exception: modals.** Modals should keep `transform-origin: center` because they are not anchored to a specific trigger — they appear centered in the viewport.
|
||||
|
||||
```css
|
||||
/* Radix UI */
|
||||
.popover {
|
||||
transform-origin: var(--radix-popover-content-transform-origin);
|
||||
}
|
||||
|
||||
/* Base UI */
|
||||
.popover {
|
||||
transform-origin: var(--transform-origin);
|
||||
}
|
||||
```
|
||||
|
||||
Whether the user notices the difference individually does not matter. In the aggregate, unseen details become visible. They compound.
|
||||
|
||||
### Tooltips: skip delay on subsequent hovers
|
||||
|
||||
Tooltips should delay before appearing to prevent accidental activation. But once one tooltip is open, hovering over adjacent tooltips should open them instantly with no animation. This feels faster without defeating the purpose of the initial delay.
|
||||
|
||||
```css
|
||||
.tooltip {
|
||||
transition: transform 125ms ease-out, opacity 125ms ease-out;
|
||||
transform-origin: var(--transform-origin);
|
||||
}
|
||||
|
||||
.tooltip[data-starting-style],
|
||||
.tooltip[data-ending-style] {
|
||||
opacity: 0;
|
||||
transform: scale(0.97);
|
||||
}
|
||||
|
||||
/* Skip animation on subsequent tooltips */
|
||||
.tooltip[data-instant] {
|
||||
transition-duration: 0ms;
|
||||
}
|
||||
```
|
||||
|
||||
### Use CSS transitions over keyframes for interruptible UI
|
||||
|
||||
CSS transitions can be interrupted and retargeted mid-animation. Keyframes restart from zero. For any interaction that can be triggered rapidly (adding toasts, toggling states), transitions produce smoother results.
|
||||
|
||||
```css
|
||||
/* Interruptible - good for UI */
|
||||
.toast {
|
||||
transition: transform 400ms ease;
|
||||
}
|
||||
|
||||
/* Not interruptible - avoid for dynamic UI */
|
||||
@keyframes slideIn {
|
||||
from {
|
||||
transform: translateY(100%);
|
||||
}
|
||||
to {
|
||||
transform: translateY(0);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Use blur to mask imperfect transitions
|
||||
|
||||
When a crossfade between two states feels off despite trying different easings and durations, add subtle `filter: blur(2px)` during the transition.
|
||||
|
||||
**Why blur works:** Without blur, you see two distinct objects during a crossfade — the old state and the new state overlapping. This looks unnatural. Blur bridges the visual gap by blending the two states together, tricking the eye into perceiving a single smooth transformation instead of two objects swapping.
|
||||
|
||||
Combine blur with scale-on-press (`scale(0.97)`) for a polished button state transition:
|
||||
|
||||
```css
|
||||
.button {
|
||||
transition: transform 160ms ease-out;
|
||||
}
|
||||
|
||||
.button:active {
|
||||
transform: scale(0.97);
|
||||
}
|
||||
|
||||
.button-content {
|
||||
transition: filter 200ms ease, opacity 200ms ease;
|
||||
}
|
||||
|
||||
.button-content.transitioning {
|
||||
filter: blur(2px);
|
||||
opacity: 0.7;
|
||||
}
|
||||
```
|
||||
|
||||
Keep blur under 20px. Heavy blur is expensive, especially in Safari.
|
||||
|
||||
### Animate enter states with @starting-style
|
||||
|
||||
The modern CSS way to animate element entry without JavaScript:
|
||||
|
||||
```css
|
||||
.toast {
|
||||
opacity: 1;
|
||||
transform: translateY(0);
|
||||
transition: opacity 400ms ease, transform 400ms ease;
|
||||
|
||||
@starting-style {
|
||||
opacity: 0;
|
||||
transform: translateY(100%);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This replaces the common React pattern of using `useEffect` to set `mounted: true` after initial render. Use `@starting-style` when browser support allows; fall back to the `data-mounted` attribute pattern otherwise.
|
||||
|
||||
```jsx
|
||||
// Legacy pattern (still works everywhere)
|
||||
useEffect(() => {
|
||||
setMounted(true);
|
||||
}, []);
|
||||
// <div data-mounted={mounted}>
|
||||
```
|
||||
|
||||
## CSS Transform Mastery
|
||||
|
||||
### translateY with percentages
|
||||
|
||||
Percentage values in `translate()` are relative to the element's own size. Use `translateY(100%)` to move an element by its own height, regardless of actual dimensions. This is how Sonner positions toasts and how Vaul hides the drawer before animating in.
|
||||
|
||||
```css
|
||||
/* Works regardless of drawer height */
|
||||
.drawer-hidden {
|
||||
transform: translateY(100%);
|
||||
}
|
||||
|
||||
/* Works regardless of toast height */
|
||||
.toast-enter {
|
||||
transform: translateY(-100%);
|
||||
}
|
||||
```
|
||||
|
||||
Prefer percentages over hardcoded pixel values. They are less error-prone and adapt to content.
|
||||
|
||||
### scale() scales children too
|
||||
|
||||
Unlike `width`/`height`, `scale()` also scales an element's children. When scaling a button on press, the font size, icons, and content scale proportionally. This is a feature, not a bug.
|
||||
|
||||
### 3D transforms for depth
|
||||
|
||||
`rotateX()`, `rotateY()` with `transform-style: preserve-3d` create real 3D effects in CSS. Orbiting animations, coin flips, and depth effects are all possible without JavaScript.
|
||||
|
||||
```css
|
||||
.wrapper {
|
||||
transform-style: preserve-3d;
|
||||
}
|
||||
|
||||
@keyframes orbit {
|
||||
from {
|
||||
transform: translate(-50%, -50%) rotateY(0deg) translateZ(72px) rotateY(360deg);
|
||||
}
|
||||
to {
|
||||
transform: translate(-50%, -50%) rotateY(360deg) translateZ(72px) rotateY(0deg);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### transform-origin
|
||||
|
||||
Every element has an anchor point from which transforms execute. The default is center. Set it to match where the trigger lives for origin-aware interactions.
|
||||
|
||||
## clip-path for Animation
|
||||
|
||||
`clip-path` is not just for shapes. It is one of the most powerful animation tools in CSS.
|
||||
|
||||
### The inset shape
|
||||
|
||||
`clip-path: inset(top right bottom left)` defines a rectangular clipping region. Each value "eats" into the element from that side.
|
||||
|
||||
```css
|
||||
/* Fully hidden from right */
|
||||
.hidden {
|
||||
clip-path: inset(0 100% 0 0);
|
||||
}
|
||||
|
||||
/* Fully visible */
|
||||
.visible {
|
||||
clip-path: inset(0 0 0 0);
|
||||
}
|
||||
|
||||
/* Reveal from left to right */
|
||||
.overlay {
|
||||
clip-path: inset(0 100% 0 0);
|
||||
transition: clip-path 200ms ease-out;
|
||||
}
|
||||
.button:active .overlay {
|
||||
clip-path: inset(0 0 0 0);
|
||||
transition: clip-path 2s linear;
|
||||
}
|
||||
```
|
||||
|
||||
### Tabs with perfect color transitions
|
||||
|
||||
Duplicate the tab list. Style the copy as "active" (different background, different text color). Clip the copy so only the active tab is visible. Animate the clip on tab change. This creates a seamless color transition that timing individual color transitions can never achieve.
|
||||
|
||||
### Hold-to-delete pattern
|
||||
|
||||
Use `clip-path: inset(0 100% 0 0)` on a colored overlay. On `:active`, transition to `inset(0 0 0 0)` over 2s with linear timing. On release, snap back with 200ms ease-out. Add `scale(0.97)` on the button for press feedback.
|
||||
|
||||
### Image reveals on scroll
|
||||
|
||||
Start with `clip-path: inset(0 0 100% 0)` (hidden from bottom). Animate to `inset(0 0 0 0)` when the element enters the viewport. Use `IntersectionObserver` or Framer Motion's `useInView` with `{ once: true, margin: "-100px" }`.
|
||||
|
||||
### Comparison sliders
|
||||
|
||||
Overlay two images. Clip the top one with `clip-path: inset(0 50% 0 0)`. Adjust the right inset value based on drag position. No extra DOM elements needed, fully hardware-accelerated.
|
||||
|
||||
## Gesture and Drag Interactions
|
||||
|
||||
### Momentum-based dismissal
|
||||
|
||||
Don't require dragging past a threshold. Calculate velocity: `Math.abs(dragDistance) / elapsedTime`. If velocity exceeds ~0.11, dismiss regardless of distance. A quick flick should be enough.
|
||||
|
||||
```js
|
||||
const timeTaken = new Date().getTime() - dragStartTime.current.getTime();
|
||||
const velocity = Math.abs(swipeAmount) / timeTaken;
|
||||
|
||||
if (Math.abs(swipeAmount) >= SWIPE_THRESHOLD || velocity > 0.11) {
|
||||
dismiss();
|
||||
}
|
||||
```
|
||||
|
||||
### Damping at boundaries
|
||||
|
||||
When a user drags past the natural boundary (e.g., dragging a drawer up when already at top), apply damping. The more they drag, the less the element moves. Things in real life don't suddenly stop; they slow down first.
|
||||
|
||||
### Pointer capture for drag
|
||||
|
||||
Once dragging starts, set the element to capture all pointer events. This ensures dragging continues even if the pointer leaves the element bounds.
|
||||
|
||||
### Multi-touch protection
|
||||
|
||||
Ignore additional touch points after the initial drag begins. Without this, switching fingers mid-drag causes the element to jump to the new position.
|
||||
|
||||
```js
|
||||
function onPress() {
|
||||
if (isDragging) return;
|
||||
// Start drag...
|
||||
}
|
||||
```
|
||||
|
||||
### Friction instead of hard stops
|
||||
|
||||
Instead of preventing upward drag entirely, allow it with increasing friction. It feels more natural than hitting an invisible wall.
|
||||
|
||||
## Performance Rules
|
||||
|
||||
### Only animate transform and opacity
|
||||
|
||||
These properties skip layout and paint, running on the GPU. Animating `padding`, `margin`, `height`, or `width` triggers all three rendering steps.
|
||||
|
||||
### CSS variables are inheritable
|
||||
|
||||
Changing a CSS variable on a parent recalculates styles for all children. In a drawer with many items, updating `--swipe-amount` on the container causes expensive style recalculation. Update `transform` directly on the element instead.
|
||||
|
||||
```js
|
||||
// Bad: triggers recalc on all children
|
||||
element.style.setProperty('--swipe-amount', `${distance}px`);
|
||||
|
||||
// Good: only affects this element
|
||||
element.style.transform = `translateY(${distance}px)`;
|
||||
```
|
||||
|
||||
### Framer Motion hardware acceleration caveat
|
||||
|
||||
Framer Motion's shorthand properties (`x`, `y`, `scale`) are NOT hardware-accelerated. They use `requestAnimationFrame` on the main thread. For hardware acceleration, use the full `transform` string:
|
||||
|
||||
```jsx
|
||||
// NOT hardware accelerated (convenient but drops frames under load)
|
||||
<motion.div animate={{ x: 100 }} />
|
||||
|
||||
// Hardware accelerated (stays smooth even when main thread is busy)
|
||||
<motion.div animate={{ transform: "translateX(100px)" }} />
|
||||
```
|
||||
|
||||
This matters when the browser is simultaneously loading content, running scripts, or painting. At Vercel, the dashboard tab animation used Shared Layout Animations and dropped frames during page loads. Switching to CSS animations (off main thread) fixed it.
|
||||
|
||||
### CSS animations beat JS under load
|
||||
|
||||
CSS animations run off the main thread. When the browser is busy loading a new page, Framer Motion animations (using `requestAnimationFrame`) drop frames. CSS animations remain smooth. Use CSS for predetermined animations; JS for dynamic, interruptible ones.
|
||||
|
||||
### Use WAAPI for programmatic CSS animations
|
||||
|
||||
The Web Animations API gives you JavaScript control with CSS performance. Hardware-accelerated, interruptible, and no library needed.
|
||||
|
||||
```js
|
||||
element.animate([{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }], {
|
||||
duration: 1000,
|
||||
fill: 'forwards',
|
||||
easing: 'cubic-bezier(0.77, 0, 0.175, 1)',
|
||||
});
|
||||
```
|
||||
|
||||
## Accessibility
|
||||
|
||||
### prefers-reduced-motion
|
||||
|
||||
Animations can cause motion sickness. Reduced motion means fewer and gentler animations, not zero. Keep opacity and color transitions that aid comprehension. Remove movement and position animations.
|
||||
|
||||
```css
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
.element {
|
||||
animation: fade 0.2s ease;
|
||||
/* No transform-based motion */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```jsx
|
||||
const shouldReduceMotion = useReducedMotion();
|
||||
const closedX = shouldReduceMotion ? 0 : '-100%';
|
||||
```
|
||||
|
||||
### Touch device hover states
|
||||
|
||||
```css
|
||||
@media (hover: hover) and (pointer: fine) {
|
||||
.element:hover {
|
||||
transform: scale(1.05);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Touch devices trigger hover on tap, causing false positives. Gate hover animations behind this media query.
|
||||
|
||||
## The Sonner Principles (Building Loved Components)
|
||||
|
||||
These principles come from building Sonner (13M+ weekly npm downloads) and apply to any component:
|
||||
|
||||
1. **Developer experience is key.** No hooks, no context, no complex setup. Insert `<Toaster />` once, call `toast()` from anywhere. The less friction to adopt, the more people will use it.
|
||||
|
||||
2. **Good defaults matter more than options.** Ship beautiful out of the box. Most users never customize. The default easing, timing, and visual design should be excellent.
|
||||
|
||||
3. **Naming creates identity.** "Sonner" (French for "to ring") feels more elegant than "react-toast". Sacrifice discoverability for memorability when appropriate.
|
||||
|
||||
4. **Handle edge cases invisibly.** Pause toast timers when the tab is hidden. Fill gaps between stacked toasts with pseudo-elements to maintain hover state. Capture pointer events during drag. Users never notice these, and that is exactly right.
|
||||
|
||||
5. **Use transitions, not keyframes, for dynamic UI.** Toasts are added rapidly. Keyframes restart from zero on interruption. Transitions retarget smoothly.
|
||||
|
||||
6. **Build a great documentation site.** Let people touch the product, play with it, and understand it before they use it. Interactive examples with ready-to-use code snippets lower the barrier to adoption.
|
||||
|
||||
### Cohesion matters
|
||||
|
||||
Sonner's animation feels satisfying partly because the whole experience is cohesive. The easing and duration fit the vibe of the library. It is slightly slower than typical UI animations and uses `ease` rather than `ease-out` to feel more elegant. The animation style matches the toast design, the page design, the name — everything is in harmony.
|
||||
|
||||
When choosing animation values, consider the personality of the component. A playful component can be bouncier. A professional dashboard should be crisp and fast. Match the motion to the mood.
|
||||
|
||||
### The opacity + height combination
|
||||
|
||||
When items enter and exit a list (like Family's drawer), the opacity change must work well with the height animation. This is often trial and error. There is no formula — you adjust until it feels right.
|
||||
|
||||
### Review your work the next day
|
||||
|
||||
Review animations with fresh eyes. You notice imperfections the next day that you missed during development. Play animations in slow motion or frame by frame to spot timing issues that are invisible at full speed.
|
||||
|
||||
### Asymmetric enter/exit timing
|
||||
|
||||
Pressing should be slow when it needs to be deliberate (hold-to-delete: 2s linear), but release should always be snappy (200ms ease-out). This pattern applies broadly: slow where the user is deciding, fast where the system is responding.
|
||||
|
||||
```css
|
||||
/* Release: fast */
|
||||
.overlay {
|
||||
transition: clip-path 200ms ease-out;
|
||||
}
|
||||
|
||||
/* Press: slow and deliberate */
|
||||
.button:active .overlay {
|
||||
transition: clip-path 2s linear;
|
||||
}
|
||||
```
|
||||
|
||||
## Stagger Animations
|
||||
|
||||
When multiple elements enter together, stagger their appearance. Each element animates in with a small delay after the previous one. This creates a cascading effect that feels more natural than everything appearing at once.
|
||||
|
||||
```css
|
||||
.item {
|
||||
opacity: 0;
|
||||
transform: translateY(8px);
|
||||
animation: fadeIn 300ms ease-out forwards;
|
||||
}
|
||||
|
||||
.item:nth-child(1) {
|
||||
animation-delay: 0ms;
|
||||
}
|
||||
.item:nth-child(2) {
|
||||
animation-delay: 50ms;
|
||||
}
|
||||
.item:nth-child(3) {
|
||||
animation-delay: 100ms;
|
||||
}
|
||||
.item:nth-child(4) {
|
||||
animation-delay: 150ms;
|
||||
}
|
||||
|
||||
@keyframes fadeIn {
|
||||
to {
|
||||
opacity: 1;
|
||||
transform: translateY(0);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Keep stagger delays short (30-80ms between items). Long delays make the interface feel slow. Stagger is decorative — never block interaction while stagger animations are playing.
|
||||
|
||||
## Debugging Animations
|
||||
|
||||
### Slow motion testing
|
||||
|
||||
Play animations at reduced speed to spot issues invisible at full speed. Temporarily increase duration to 2-5x normal, or use browser DevTools animation inspector to slow playback.
|
||||
|
||||
Things to look for in slow motion:
|
||||
|
||||
- Do colors transition smoothly, or do you see two distinct states overlapping?
|
||||
- Does the easing feel right, or does it start/stop abruptly?
|
||||
- Is the transform-origin correct, or does the element scale from the wrong point?
|
||||
- Are multiple animated properties (opacity, transform, color) in sync?
|
||||
|
||||
### Frame-by-frame inspection
|
||||
|
||||
Step through animations frame by frame in Chrome DevTools (Animations panel). This reveals timing issues between coordinated properties that you cannot see at full speed.
|
||||
|
||||
### Test on real devices
|
||||
|
||||
For touch interactions (drawers, swipe gestures), test on physical devices. Connect your phone via USB, visit your local dev server by IP address, and use Safari's remote devtools. The Xcode Simulator is an alternative but real hardware is better for gesture testing.
|
||||
|
||||
## Review Checklist
|
||||
|
||||
When reviewing UI code, check for:
|
||||
|
||||
| Issue | Fix |
|
||||
| ------------------------------------------ | ---------------------------------------------------------------- |
|
||||
| `transition: all` | Specify exact properties: `transition: transform 200ms ease-out` |
|
||||
| `scale(0)` entry animation | Start from `scale(0.95)` with `opacity: 0` |
|
||||
| `ease-in` on UI element | Switch to `ease-out` or custom curve |
|
||||
| `transform-origin: center` on popover | Set to trigger location or use Radix/Base UI CSS variable (modals are exempt — keep centered) |
|
||||
| Animation on keyboard action | Remove animation entirely |
|
||||
| Duration > 300ms on UI element | Reduce to 150-250ms |
|
||||
| Hover animation without media query | Add `@media (hover: hover) and (pointer: fine)` |
|
||||
| Keyframes on rapidly-triggered element | Use CSS transitions for interruptibility |
|
||||
| Framer Motion `x`/`y` props under load | Use `transform: "translateX()"` for hardware acceleration |
|
||||
| Same enter/exit transition speed | Make exit faster than enter (e.g., enter 2s, exit 200ms) |
|
||||
| Elements all appear at once | Add stagger delay (30-80ms between items) |
|
||||
Reference in New Issue
Block a user