@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/audit-db-schema/references/details.md

@@ -0,0 +1,110 @@
+## Step 5: Prisma Schema Audit
+
+When auditing `schema.prisma`, check:
+
+| Rule | Pattern |
+|------|---------|
+| `@id @default(cuid())` or `@default(uuid())` | On every model |
+| `@updatedAt` | On `updatedAt` field |
+| `@default(now())` | On `createdAt` field |
+| `@@index([field])` | On FK and query fields |
+| `@unique` | On email, slug, external IDs |
+| `@relation(onDelete: Cascade)` | Explicit delete behavior |
+| `enum` | For fixed value sets |
+| `@map` / `@@map` | snake_case DB names if needed |
+
+Use `Grep` to find violations:
+
+```
+Grep: "@relation" in prisma/schema.prisma — check all have onDelete
+Grep: "@@index" in prisma/schema.prisma — count indexed fields
+Grep: "String" fields without @unique that should be unique (email, slug)
+```
+
+---
+
+## Output Template
+
+````markdown
+## Database Schema Audit Report
+
+**Date:** [date]
+**Database:** [Supabase Postgres / etc.]
+**ORM:** [Prisma / Drizzle / none]
+**Schema:** public
+**Tables Audited:** [count]
+**Issues Found:** [count]
+
+---
+
+### Supabase Advisor Findings
+
+#### Security Advisors
+[List each advisory with description and remediation URL]
+
+#### Performance Advisors
+[List each advisory with description and remediation URL]
+
+---
+
+### Audit Summary
+
+| Category | Status | Issues |
+|----------|--------|--------|
+| Naming Conventions | [pass/warn/fail] | [count] |
+| Data Types | [pass/warn/fail] | [count] |
+| Timestamps | [pass/warn/fail] | [count] |
+| Constraints | [pass/warn/fail] | [count] |
+| Indexes | [pass/warn/fail] | [count] |
+| RLS Policies | [pass/warn/fail] | [count] |
+| Relationships | [pass/warn/fail] | [count] |
+| Migrations | [pass/warn/fail] | [count] |
+| Security | [pass/warn/fail] | [count] |
+
+---
+
+### Research Findings Applied
+
+- [Pattern from Firecrawl/Context7]: [how it applies to this schema]
+- [Best practice]: [gap identified in current schema]
+
+---
+
+### Critical Issues (Must Fix)
+
+#### 1. [Table] — [Issue]
+- **Problem:** [description]
+- **Risk:** [data loss / security / performance]
+- **Fix:**
+```sql
+-- migration SQL
+```
+
+---
+
+### Warnings (Should Fix)
+
+#### 1. [Description]
+- **Table:** [table]
+- **Impact:** [description]
+- **Recommendation:** [fix]
+
+---
+
+### Table-by-Table Summary
+
+| Table | PK | Timestamps | RLS | Indexes | FK Constraints | Status |
+|-------|----|------------|-----|---------|----------------|--------|
+| users | uuid | both | enabled | 3 | 0 | pass |
+| posts | uuid | created only | disabled | 1 | 1 missing | fail |
+
+---
+
+### Next Steps
+
+1. [ ] Fix critical issues: [list]
+2. [ ] Enable RLS on: [tables]
+3. [ ] Add missing indexes: [list]
+4. [ ] Add updated_at triggers: [tables]
+5. [ ] Re-run `get_advisors` after fixes to verify
+````

package/skills/audit-doctrine/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: audit-doctrine
+description: >
+  Read-only audit of custom lint and ratchet rules: is each rule right on the
+  merits, not just enforced. Use when "is this lint rule wrong", "the ratchet
+  banned a legitimate pattern", or "audit our guardrail doctrine". Enforcement
+  → audit-gate-logic.
+license: MIT
+effort: high
+---
+
+# audit-doctrine — Is the rule right, not merely enforced?
+
+**Degree of freedom: MIXED.**
+
+- Reference-practice comparison and remedy judgment (Phases 1–2):
+  **HIGH freedom** — weigh each rule against how top products actually
+  build.
+- Governance-contract checks (Phases 3–4): **LOW freedom** — the
+  contract's clauses are pass/fail; check each exactly.
+
+Read-only. **`audit-gate-logic` asks "can this gate be bypassed or
+gamed?" — it assumes the rule is correct. This asks the harder
+question: is the rule right on the merits?** A ratchet that flawlessly
+enforces bad doctrine is worse than no ratchet, because greenness
+certifies the mistake and the developer, given only a codemod list,
+restyles legitimate work to appease a regex instead of fixing a real
+problem. An unexplained lint rejection erodes trust at that decision
+point until people "adopt their own truth." This audit finds the rules
+that are measuring taste, not correctness.
+
+Present findings. Do not rewrite detectors, baselines, or tokens here.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **audit-doctrine** (this) | Rule *content* — remedy, named token, Tier-D practice |
+| `audit-gate-logic` | Rule *machinery* — bypass, gaming, required-but-not |
+| `housekeep-gates` | Consolidate / delete duplicate gates (apply-now) |
+| `enhance-arch-boundaries` | Install boundary *enforcement*, not judge doctrine |
+| `housekeep-design` | Token/component SSOT — the sanctioned-form side |
+| `docs-adr` | Record a justified divergence from Tier-D |
+| `housekeep-backlog` | Un-remedied long-tail axes as `BL-` rows |
+
+## The governance contract
+
+A custom rule/axis is sound only if all hold:
+
+1. **Has a remedy** — states the sanctioned alternative by name; a
+   rule that only says "don't" is measuring taste.
+2. **Sanctioned form is reachable** — the approved pattern exists as a
+   named token/class, not folklore the developer must reverse-engineer.
+3. **Teaches on failure** — the failure output prints the remedy AND
+   the offending `file:line`, not just a codemod list.
+4. **Agrees with Tier-D reference practice** — where the rule
+   disagrees with how Stripe / Linear / GitHub / Docusaurus actually
+   ship, the burden of proof is on the rule.
+5. **Exceptions expire; baselines only shrink** — no permanent
+   grandfather; the baseline cannot silently regrow (ratchet integrity
+   still belongs to `audit-gate-logic`).
+
+## How to reason (every axis)
+
+1. **Observe** — what does the detector actually measure? Read the
+   detector, not its name — the name may over-claim (e.g. "no bordered
+   cards" that really counts rounded+border without overflow-clip).
+2. **Interpret** — what real pattern does it catch, and what
+   *legitimate* pattern does it also reject?
+3. **Reference-check** — do top products ship the rejected pattern?
+4. **Contract-check** — run the five clauses.
+5. **Verdict** — sound / taste-measuring / false-positive /
+   folklore-token / missing-remedy, with the fix.
+
+## Worked example
+
+> **Observe:** a `nested-rounded-box` axis counts rounded + border
+> lines without overflow-clip.
+> **Interpret:** it rejects bordered 前の章／次の章 chapter-link cards
+> — but the doctrine's own shell recipe passes it, so the sanctioned
+> form exists.
+> **Reference-check:** bordered chaptered-nav cards are standard —
+> Docusaurus `pagination-nav`, Stripe docs ship the same pattern.
+> **Contract-check:** remedy missing; reachable token missing (the
+> passing form was never named); failure printed only a codemod list.
+> **Verdict:** false-positive + missing-remedy + folklore-token.
+> **Fix:** name the sanctioned form (e.g. `PAGE_LINK_CARD_CLASS` —
+> bordered, clipped, hover-tiered); print remedy + file:line. Baseline
+> unchanged — the token already equals the baseline, proving the ban
+> was never real.
+
+---
+
+## Phase 0 — Locate the doctrine  [LOW freedom — run exactly]
+
+Find the rule surface: custom lint/ratchet axes, the detector suite,
+the doctrine/governance doc (e.g. `MASTER.md`), baseline files,
+exception lists, and the failure-output code. Enumerate every axis
+with: what it detects, its remedy (if any), its baseline, and whether
+a named sanctioned token exists. Record the count — a long tail of
+un-remedied axes is the common state.
+
+## Phase 1 — Separate correctness from taste  [HIGH freedom]
+
+For each axis, classify:
+
+- **Correctness** — catches a real bug / a11y / perf / security issue
+  (missing focus, contrast fail, unclipped overflow that actually
+  breaks layout). These may be stricter with less explanation.
+- **Taste** — enforces a stylistic preference (radius scale, border
+  style, card nesting). Not illegitimate, but they carry a higher
+  burden: they **must** have a remedy and a reachable token, or they
+  generate the appease-the-regex incident.
+
+## Phase 2 — Reference-check taste rules  [HIGH freedom]
+
+For each taste rule, check whether Tier-D products ship the pattern it
+rejects. Use `research` / official docs against Stripe, Linear,
+GitHub, Docusaurus, Radix, shadcn — fetch the live page or docs as
+written; recognizing a product is not knowing what it ships today, and a
+from-memory reference is **needs-reference**, not evidence. Where a rule
+bans what Tier-D
+ships, it is a false-positive *candidate* — the burden of proof is on
+the rule. Document the shipping reference for each disagreement. No
+reference → mark **needs-reference**, not a finding.
+
+## Phase 3 — Run the governance contract  [LOW freedom — do not skip]
+
+Check all five clauses per axis. State coverage honestly: *N of M
+axes carry a remedy* (usually a small fraction — remedies get seeded
+on the axes that bite during feature work; the long tail stays bare).
+Every bare axis is a latent appease-the-regex incident. Flag:
+
+- missing-remedy
+- unreachable-sanctioned-form (folklore)
+- non-teaching failure output
+- unexpiring exceptions
+- regrowable baselines
+
+Un-remedied axes → `housekeep-backlog` as `BL-` rows (junior-PR
+burndown).
+
+## Phase 4 — Freeze against regression  [LOW freedom]
+
+Confirm or recommend a test suite that freezes the governance
+properties so remedies cannot be silently stripped and sanctioned
+tokens cannot drift back into a false-positive form. Without this, the
+fix decays.
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+- **Evidence, not opinion** — every "false positive" cites a specific
+  Tier-D reference that ships the pattern. No reference →
+  needs-reference, not a finding.
+- **Right axis** — content problem (this skill) vs enforcement
+  problem (`audit-gate-logic`). Do not claim a bypass finding.
+- **Remedy is real** — a proposed remedy names an existing or addable
+  token, not "use the right style".
+- **Baseline honesty** — confirm the sanctioned form actually passes
+  at the current baseline before claiming the ban was illusory.
+
+## Definition of Done
+
+- [ ] Every axis enumerated: detect-target, remedy, baseline,
+      sanctioned-token status
+- [ ] Each axis classified correctness vs taste
+- [ ] Taste rules reference-checked; disagreements cite a shipping
+      reference
+- [ ] Five contract clauses run per axis; remedy-coverage stated as
+      N of M
+- [ ] False-positives, folklore-tokens, missing-remedies,
+      non-teaching failures, unexpiring exceptions, regrowable
+      baselines flagged
+- [ ] Freeze-test coverage confirmed or recommended
+- [ ] Self-critique applied
+- [ ] Read-only — propose, do not patch
+
+## Output format
+
+1. **Axis inventory** — axis | detects | correctness/taste | remedy?
+   | reachable token? | teaches? | baseline-shrink-only?
+2. **False-positive findings** — axis | legitimate pattern rejected |
+   Tier-D reference | proposed remedy + token
+3. **Governance gaps** — remedy-coverage (N/M), folklore tokens,
+   non-teaching outputs, exception/baseline integrity
+4. **Backfill burndown** — un-remedied long-tail axes as tracked
+   items (→ `housekeep-backlog` `BL-` rows)
+5. **Handoffs** — enforcement/bypass → `audit-gate-logic`; token
+   SSOT → `housekeep-design`; justified divergence → `docs-adr`

package/skills/audit-env-parity/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: audit-env-parity
+description: >
+  Read-only audit of config parity across dev, staging, and prod: missing or
+  misnamed vars, drifted flags, hardcoded values, reused secrets. Use when
+  "works locally but not in prod", "audit our environments", or "config
+  drift".
+license: MIT
+effort: high
+---
+
+# audit-env-parity — Environments that agree
+
+**Degree of freedom: MIXED** — Phases 0–1 `[HIGH freedom]`; Phase 2
+three-way name diff `[LOW freedom — names only, never values]`.
+
+Read-only. Find where environments disagree in ways that cause "works on my
+machine", silent prod misbehavior, or leaked secrets.
+
+**The classic outage:** a new env var added locally, referenced in code, never
+set in prod — deploy is green, feature is broken.
+
+> **Never print secret values.** Present the gap matrix; do not change host
+> config until approved.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **audit-env-parity** (this) | Same keys exist (and mean the same) in every env |
+| `workflow-environment-ready` | *Local* machine can build/test/reach services |
+| `plan-secrets-audit` | Credential *exposure* in git / over-scoped keys |
+| `plan-data-integrity` | Destructive ops; staging pointing at prod is shared |
+| `workflow-feature-flag` | Flag rollout process, not "staging flag ≠ prod flag" |
+
+Do **not** fire for "did I commit a key" → `plan-secrets-audit`.
+Do **not** fire for "prove this laptop can run the suite" →
+`workflow-environment-ready`.
+
+## How to reason
+
+1. **Observe** — quote the `process.env` / `import.meta.env` read and whether the name exists in each env
+2. **Interpret** — which runtime path breaks if that name is missing or public-prefixed?
+3. **Classify** — referenced-but-unset / naming drift / secret reuse / hardcoded / dead
+4. **Severity** — prod-missing or public-prefix secret = P0 / Critical
+
+## Worked example
+
+> **Observe:** `process.env.STRIPE_WEBHOOK_SECRET` used in
+> `app/api/stripe/route.ts`; name absent from Vercel prod; present locally.
+> **Interpret:** deploy is green; webhook verify fails only in prod.
+> **Classify:** referenced-but-unset (prod).
+> **Severity:** P0.
+> **Finding:** `STRIPE_WEBHOOK_SECRET` | prod absent | P0 | set the name;
+> never print the value
+
+---
+
+## Phase 0 — Enumerate environments and sources  [HIGH freedom]
+
+- Envs: local, preview/staging, prod
+- Sources: `.env*`, `.env.example`, Vercel/Supabase/Fly dashboards, CI secrets,
+  runtime config
+- Demanded set: every `process.env.X` / `import.meta.env` / config object read
+
+---
+
+## Phase 1 — Parity and correctness  [HIGH freedom]
+
+**Referenced-but-unset** — Code reads it; an env that runs that path lacks it.
+P0 if prod-missing. Diff `.env.example` against real usage.
+
+**Set-but-unreferenced** — Dead vars. Low severity; they hide real config.
+
+**Naming drift** — `API_URL` vs `NEXT_PUBLIC_API_URL` vs `VITE_API_URL`.
+Public prefixes shipping a *secret* → Critical; hand to `plan-secrets-audit`.
+
+**Value drift that invalidates staging** — Flags, timeouts, model names that
+make staging a different app than prod.
+
+**Hardcoded-should-be-config** — URLs, regions, magic values in code. Prod
+pointing at a dev resource (or reverse).
+
+**Secret reuse** — Same secret across dev/staging/prod (a dev leak is prod).
+Prod secrets reachable from a dev context.
+
+**Service targeting** — Staging DB/bucket/queue must not be prod
+(`plan-data-integrity` if a test would hit real data).
+
+---
+
+## Phase 2 — Three-way gap  [LOW freedom — names only]
+
+Diff names only (never values) between code-demands × local-has × prod-has.
+A name present in all three with unknown value mismatch is still a manual
+review flag.
+
+---
+
+## Definition of Done
+
+- [ ] Envs + sources enumerated
+- [ ] Code-referenced keys extracted
+- [ ] Every referenced key checked in every env that runs it
+- [ ] `.env.example` drift flagged
+- [ ] Naming + public-prefix leaks identified
+- [ ] Flag/value drift + hardcoded config found
+- [ ] Cross-env secret reuse + staging→prod services checked
+- [ ] Three-way gap produced with **no secret values**
+- [ ] Nothing changed without approval
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **No secret values** — names and present/absent only
+2. **Evidenced** — code read + env-has, not "probably set on Vercel"
+3. **Severity justified** — P0 = prod-missing on a live path
+4. **Right owner** — committed key → `plan-secrets-audit`; staging→prod data → `plan-data-integrity`
+5. **Nothing changed** until approved
+
+## Output format
+
+1. **Parity matrix** — key × env (present/absent/unknown) + demanded-by-code
+2. **Findings** — missing/dead/misnamed/leaked-prefix/hardcoded/drift
+3. **Secret handoff** — `plan-secrets-audit`
+4. **Fix plan** — prod-missing first, then leaks, then drift
+
+## Related
+
+- `workflow-environment-ready` — local preflight
+- `plan-secrets-audit` — exposure / rotation
+- `plan-data-integrity` — staging hitting prod
+- `plan-backup-dr` — reconstructability of config after loss
+- `workflow-feature-flag` — rollout, not parity