@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/audit-skill-conflicts/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: audit-skill-conflicts
+description: >
+  Read-only audit of a skill pack for contradictory directives, overlapping
+  triggers, stale cross-refs, and context bloat. Use when "audit my skills",
+  "conflicting skills", "wrong skill triggered", or after adding a batch.
+  Authoring → meta-skill-creator.
+license: MIT
+effort: high
+---
+
+# audit-skill-conflicts — Pack coherence, not product QA
+
+**Degree of freedom: MIXED** — Phases 0–1 `[HIGH freedom]`; Phase 2 routing
+dry-run `[LOW freedom]` — skip explicitly if the harness cannot show
+selection. The retired `audit-responsive-layout` name appears in your report only as a dangling-reference finding, never as a handoff.
+
+Read-only. Most other `audit-*` skills inspect an app or repository you
+ship. This one inspects **the skill pack it lives in**.
+
+`npm run validate:skills` checks each file in isolation (name = dir, description
+≤320, body <500). It cannot see two skills giving opposite advice, six
+descriptions all matching "audit my UI", a handoff to a renamed skill, or a
+greedy description that fires constantly and burns context.
+
+**A skill collection is a system. Its failure modes are between files.**
+
+> **Present findings. Rewrite nothing until approved.** Highest-leverage
+> first: description rewrites (routing) — they change which skill fires
+> without changing any skill's behavior.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **audit-skill-conflicts** (this) | Cross-skill contradictions, routing, dangling refs, bloat |
+| `meta-skill-creator` | How to *write* a SKILL.md |
+| `validate:skills` (script) | Per-file spec lint — not semantic coherence |
+| `enhance-agent-guardrails` | Guardrails in an *app* repo, not this pack |
+| `plan-docs-sync` | Docs vs code drift — not skill vs skill |
+
+Do **not** fire for "create a skill" → `meta-skill-creator`.
+Do **not** fire for "audit my app's UI" → `audit-ux` / `audit-responsive` /
+`audit-ui-states` (this skill would *flag* that cluster).
+
+## How to reason
+
+1. **Observe** — quote both descriptions (or rule vs skill) that appear to collide
+2. **Interpret** — can one user phrase honor both, or do they contradict / steal routing?
+3. **Classify** — contradiction / trigger overlap / stale ref / bloat / correct carve-out
+4. **Severity** — opposite stance on the same situation, or a greedy description, first
+
+## Worked example
+
+> **Observe:** "audit my UI" matches `audit-ux`, `audit-responsive`,
+> `audit-ui-states` with no carve-out in two of the three descriptions.
+> **Interpret:** the agent cannot know whether to score heuristics, breakpoints,
+> or empty states.
+> **Classify:** trigger overlap without disambiguation.
+> **Severity:** major — wrong skill fires; wasted context.
+> **Fix:** each description names when *it* wins (layout vs heuristics vs states).
+
+---
+
+## Phase 0 — Load the corpus  [HIGH freedom]
+
+Enumerate:
+
+- `skills/*/SKILL.md` and `skills-cursor/*/SKILL.md`
+- `commands/*.md` and `commands-portable/*.md`
+- `agents/*.md`
+- `rules/*.mdc` and `.cursor/rules/*.mdc` — **highest-risk**. Always-on
+  rules silently override a skill's intent.
+
+For each skill extract: `name`, `description` (routing surface), claimed
+triggers, cross-referenced skills, core directives (read-only vs apply-fixes,
+plan-first vs edit, hard always/never). One index. Compare the set, not
+pairwise guesswork.
+
+House skill name in *this* repo is `audit-responsive`.
+`audit-responsive-layout` is retired. `/responsive-audit` is a valid command
+alias, but bare/backticked `responsive-audit` is not a skill handoff.
+
+---
+
+## Phase 1 — Conflict and drift  [HIGH freedom]
+
+**Contradictory directives** — Opposite behavior for an overlapping situation
+(e.g. "fix inline" vs "never edit in the audit pass"). Rules-vs-skill is
+worst. List every pair that cannot both be honored.
+
+**Trigger overlap / mis-routing** — Phrases that match many skills. Example
+cluster in this pack:
+
+> "audit my UI" → `audit-ux`, `audit-uiux-design-system`, `audit-responsive`,
+> `audit-ui-states`, `thirdparty-web-interface-guidelines`,
+> `plan-uiux-unification`
+
+Overlap is fine **if** each description carves out *when it, specifically,*
+applies. Flag members that do not disambiguate.
+
+**Duplicated guidance** — The same block copy-pasted across skills. Drift
+risk. Name an extraction target (shared rule or one canonical skill).
+
+**Stale cross-references** — Handoff to a renamed/removed skill. Resolve every
+backtick skill name against the live directory list.
+
+**Scope gaps & double-coverage** — Two skills claiming the same task with no
+delineation, or a chain step no skill owns. This is *pack* coverage, not
+product gaps.
+
+**Context-budget bloat** — Over-broad descriptions (narrow skill, greedy
+triggers): descriptions ride in every request, so they are the always-on
+cost. Bodies load only on trigger and cache well; flag a body for dated
+instructions, not for length alone. User-initiated rituals should carry
+`disable-model-invocation: true` (drops the description from the roster;
+Cursor and Claude Code both honor it); reference-only skills
+`user-invocable: false` (Claude Code).
+
+**Convention drift** — Family-placement (audit-and-fix under `enhance-*` is
+OK when called out, like `enhance-email-deliverability`). Inconsistent
+read-only/plan-only semantics inside a family. Description-voice drift.
+
+---
+
+## Phase 2 — Routing dry-run (optional)  [LOW freedom — skip honestly]
+
+If a harness can show which skill the agent selects for a phrase, feed
+realistic user lines and record matches. Ambiguous phrases that should map to
+one skill but match several confirm Phase 1 empirically.
+
+**Cursor / Claude Code usually do not expose selection.** Skip this phase
+explicitly; static description analysis still stands. Do not pretend a
+dry-run ran.
+
+---
+
+## Definition of Done
+
+- [ ] Corpus indexed: skills + commands + subagents + rules
+- [ ] Contradictory-directive pairs listed (rules-vs-skill included)
+- [ ] Trigger-overlap clusters identified; carve-outs checked
+- [ ] Duplicated blocks + extraction targets named
+- [ ] Cross-refs resolved; dangling listed (incl. retired
+      `audit-responsive-layout` and bare `responsive-audit` skill handoffs)
+- [ ] Double-coverage and handoff gaps surfaced
+- [ ] Bloat / convention drift noted
+- [ ] Routing dry-run run **or** explicitly skipped
+- [ ] Nothing edited without approval
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **Quoted pair** — every contradiction cites both texts
+2. **Dry-run honesty** — skipped if no harness; do not pretend it ran
+3. **Name hygiene** — retired `audit-responsive-layout` and bare
+   `responsive-audit` skill handoffs listed; `/responsive-audit` command kept
+4. **Right owner** — how to *write* a skill → `meta-skill-creator`; how to
+   upgrade prompts → `enhance-skill-prompts`
+5. **Nothing rewritten** until approved; description fixes first (routing)
+
+## Output format
+
+1. **Conflict table** — A | B (or rule) | type | why they can't coexist | severity
+2. **Trigger-overlap clusters** — phrase | skills | who should win | description fix
+3. **Dangling references** — skill | broken ref | correct target
+4. **Coverage map** — double-coverage + gaps
+5. **Bloat / convention** — item | issue | fix
+6. **Fix plan** — description rewrites first, then dedupe/extraction, then
+   convention. Propose only.
+
+## Related
+
+- `meta-skill-creator` — write a new SKILL.md
+- `enhance-skill-prompts` — upgrade an existing skill's prompt (T1–T8), not its behavior
+- `validate:skills` — per-file spec after description edits
+- `enhance-agent-guardrails` — app-repo policy, not pack coherence
+- `plan-docs-sync` — docs vs code
+- `audit-responsive` / `audit-ux` / `audit-ui-states` — the UI-audit cluster this skill is expected to flag

package/skills/audit-ui-states/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: audit-ui-states
+description: >
+  Read-only audit of unhappy-path UI states — empty, loading, error, offline,
+  zero-results, permission, overflow — then a fix plan. Use when "check
+  empty/error states", "audit loading states", or "what happens when this
+  fails".
+license: MIT
+effort: high
+---
+
+# audit-ui-states — Unhappy-path state matrix
+
+**Degree of freedom: MIXED** — Phases 0–1 `[HIGH freedom]`; Phase 2 live
+force `[LOW freedom — run exactly]`. Read `protocol-browser-anti-stall`
+before any browser work.
+
+Read-only. Map every meaningful screen against the states it can be in. Flag
+blank boxes, infinite spinners, raw error objects, and broken overflow.
+
+**Happy-path-only UI is the signature of generated code:** it looks finished
+in the demo and falls apart the first time a list is empty or a request fails.
+
+> **Present the matrix first. Implement only on approval.**
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **audit-ui-states** (this) | Per-screen empty/loading/error/offline/overflow matrix |
+| `plan-stub-checker` | Dead buttons, fake data, unwired handlers |
+| `audit-resilience` | Backend timeouts/retries — not the front-end empty state |
+| `audit-responsive` | Breakpoint layout / linearized desktop |
+| `audit-ux` | Heuristics and microcopy voice |
+| `enhance-web-forms` | Form field/error/success patterns |
+| `test-visual-regression` | Lock the states this skill designs |
+
+Do **not** fire for "desktop looks like a phone" → `audit-responsive`.
+Do **not** fire for "this button does nothing" → `plan-stub-checker`.
+
+## How to reason
+
+1. **Observe** — what renders when the list is empty / the request fails / the network drops?
+2. **Interpret** — is that a designed state or a void / spinner / raw error?
+3. **Classify** — present / missing / broken
+4. **Severity** — blank or raw-error on a core screen = major+
+
+## Worked example
+
+> **Observe:** Orders page: `if (!data) return null`. No empty component.
+> Forced empty account → white content area.
+> **Interpret:** first-run users see a void, not an onboarding empty state.
+> **Classify:** missing empty (zero data, valid).
+> **Severity:** major — core loop looks broken with no data.
+> **Finding:** Orders | empty | major | void | designed empty + CTA
+
+---
+
+## Phase 0 — Enumerate screens and data dependencies  [HIGH freedom]
+
+List screens/views/major components. For each: data fetch, mutation,
+permission, network, variable-length content. A static page has few states;
+a data-driven list has all of them.
+
+Detect stack (framework, data library, design system) and reuse existing
+empty/error primitives — do not invent a second pattern.
+
+---
+
+## Phase 1 — The state matrix  [HIGH freedom]
+
+For every data-driven screen, mark present / missing / broken:
+
+**Loading** — Shape-matched skeleton (good) vs centered spinner / layout flash.
+Handles *slow* (3s+), not just pending.
+
+**Empty (zero data, valid)** — First-run / no-content-yet. Designed empty
+state with next action — not a void. This is an onboarding surface.
+
+**Zero-results** — Search/filter returned nothing. Distinct from empty.
+Offers clear-filters.
+
+**Error** — Human message + retry. Not a raw object, white screen, or swallow.
+Voice matches `design-frontend` / `audit-ux` ("Couldn't load your orders.
+Retry." — not "Error: undefined").
+
+**Offline** — Detected and communicated. Queued mutations survive reconnect
+(PWA / Capacitor especially).
+
+**Partial / permission** — Logged-out, free vs paid, role-gated: deliberate
+state, not a crash on null fields.
+
+**Overflow** — Long names, huge numbers, missing images. Layout holds or
+truncates. Long lists virtualize. Note overlap with `audit-responsive`;
+don't duplicate breakpoint work.
+
+**Optimistic rollback** — Failed mutation rolls the UI back; does not leave a lie.
+
+---
+
+## Phase 2 — Live verification  [LOW freedom — force each state]
+
+Force each state; "exists in code" that throws is *broken*:
+
+```bash
+PW='npx --yes @playwright/cli@latest'
+$PW -s=ui-states navigate "$APP"
+# Empty: fresh account. Error: block the request. Offline: toggle network.
+# Overflow: long string / large list. Zero-results: nonsense search.
+```
+
+Save evidence under `.playwright-mcp/`.
+
+---
+
+## Definition of Done
+
+- [ ] Every data-driven screen has applicable states enumerated
+- [ ] Loading / empty / zero-results / error / offline / permission / overflow scored
+- [ ] States forced live, not only read in code
+- [ ] Fix plan in PR-sized chunks; nothing patched without approval
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **Forced, not inferred** — "exists in code" that throws is *broken*
+2. **Empty ≠ zero-results** — do not collapse those two states
+3. **Right owner** — dead button → `plan-stub-checker`; linearized desktop → `audit-responsive`
+4. **Evidence** — screenshot under `.playwright-mcp/`
+5. **Nothing patched** until the matrix is approved
+
+## Output format
+
+1. **State matrix** — screen × state → present / missing / broken
+2. **Findings** — screen | state | severity | renders now | should
+3. **Live log** — state forced | result | screenshot
+4. **Fix plan** — empty/error first, then loading/offline
+
+## Related
+
+- `plan-stub-checker` — unwired controls
+- `audit-resilience` — server timeouts
+- `audit-responsive` — breakpoint layout
+- `audit-ux` / `design-frontend` — copy voice
+- `enhance-web-forms` — form states
+- `test-visual-regression` — lock the matrix
+- `test-playwright` — functional coverage of recoveries