@adia-ai/adia-ui-forge 0.1.2 → 0.1.3

package/skills/dogfood-sweep/README.md

@@ -0,0 +1,105 @@
+# Dogfooding analyzer
+
+Walks every `/site/components/*` demo page in headless Chromium and runs
+visual-correctness probes that type-checks and tests don't catch:
+
+| # | Probe | Bug class it detects |
+|---|-------|----------------------|
+| 1 | Zero-area | Element collapsed (parent `display:none`, toolbar overflow spilled it, layout glitch) |
+| 2 | Transparent fill | `[data-swatch]` / variant pill / button / chart indicator whose computed bg is `rgba(0,0,0,0)` — fallback token doesn't resolve (the chart-legend `--chart-N` class) |
+| 3 | Empty control | `input-ui` / `search-ui` / `button-ui` / `select-ui` / `tag-ui` whose `connected()` should have stamped internals but didn't |
+| 4 | Synonym-attr / synonym-slot drift | Markers from `docs/conventions/attribute-api-migration.md` (`avatar-ui[name]`, `grid-ui[cols]`, `card-ui [slot=meta]`, etc.) |
+| 5 | Alert flex-row | `alert-ui` with multiple bare `<text-ui>` children (need `<col-ui slot="content">` wrap) |
+| 6 | Console | Every `console.error` + `console.warn` during page load + 800ms settling |
+
+Output: severity-ranked markdown report at
+`docs/reports/dogfooding-YYYY-MM-DD.md`.
+
+## Run locally
+
+```bash
+# Terminal 1
+npm run dev
+
+# Terminal 2
+node .agents/skills/dogfood-sweep/analyze.mjs                    # full sweep (~82 pages)
+node .agents/skills/dogfood-sweep/analyze.mjs --filter chart-legend  # one page
+node .agents/skills/dogfood-sweep/analyze.mjs --port 5174            # custom port
+node .agents/skills/dogfood-sweep/analyze.mjs --out /tmp/r.md        # custom path
+```
+
+Exit code: **1** if any **critical** findings, **0** otherwise. CI-friendly.
+
+## Schedule as a remote agent
+
+The script is the data gatherer. The remote agent wraps it with git
+orchestration: clone repo, start dev server, run script, triage findings,
+commit/PR.
+
+Agent prompt (use `/schedule` skill to register; weekly cadence
+recommended — pages drift slowly):
+
+```
+You are the AdiaUI dogfooding agent. Your job is to find visual bugs in
+the component demo pages that type-checks miss.
+
+1. `npm install --frozen-lockfile`
+2. Start the dev server in the background:
+     npm run dev > /tmp/vite.log 2>&1 &
+   Wait for "ready" in /tmp/vite.log (max 30s).
+3. `node .agents/skills/dogfood-sweep/analyze.mjs`
+   The script writes `docs/reports/dogfooding-YYYY-MM-DD.md` and exits
+   non-zero iff any critical findings.
+4. Read the report. For each *critical* finding, evaluate independently:
+   - Is the diagnosis right? (cross-check with component source)
+   - Is the fix mechanical and unambiguous?
+   - Does memory or `attribute-api-migration.md` already document the
+     pattern?
+5. If yes to all three → apply the fix, run the verification gate
+   (`node scripts/build/components.mjs --verify && npm run test:a2ui`),
+   and include the diff in the PR.
+6. If the diagnosis is right but the fix is non-trivial → leave it for
+   a human, just file the report.
+7. Open a PR titled "dogfood: <date> — <N> critical, <M> warning":
+   - body = first 100 lines of the report
+   - link to the full report file
+   - if you applied any fixes, list them as a checklist
+8. If 0 critical and 0 warning, still commit the report file (under
+   `docs/reports/`) so we have a paper trail of "things were fine".
+9. Stop the dev server before exiting.
+
+Hard rules:
+- Never touch `packages/web-components/components/avatar/avatar.js:48`
+  (the deprecation handler string) when sweeping `<avatar-ui name=…>`.
+- Never edit `MIGRATION GUIDE.md` historic sections; only the active
+  v0.0.X section.
+- Don't fix more than 5 critical findings in one PR — leave the rest
+  for follow-up so humans can review fix shape before scaling.
+```
+
+Register via `/schedule weekly node .agents/skills/dogfood-sweep/analyze.mjs` or
+hand-author with the agent prompt above.
+
+## False positives + tuning
+
+The probes are intentionally narrow. Known places where "transparent
+fill" is by design (and shouldn't be added to `COLORED_SELECTORS`):
+
+- `tag-ui` without a variant (`muted` / default) — bg is correctly
+  `--a-bg-muted`, not transparent.
+- `button-ui[variant=ghost]` — transparent by design.
+- `[data-swatch]` for `chart-legend-ui[shape=dashed]` — intentionally
+  transparent bg + colored `border-top`. The probe handles this case.
+
+If a finding is a known false positive, add the parent component or
+selector to the skip-list rather than removing it from
+`COLORED_SELECTORS` (preserves coverage on the canonical case).
+
+## When to revisit the probe set
+
+- New component ships → add to `STAMP_CONTRACTS` if it has internal
+  stamping logic.
+- New synonym-attribute drift class documented in
+  `attribute-api-migration.md` → add to `DRIFT_MARKERS`.
+- A class of bugs slips past the analyzer in a real PR → add a probe
+  for that bug class first, *then* fix it. Test for the test.