@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/audit-code-quality/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: audit-code-quality
+description: >
+  Detect and fix repo-wide anti-patterns and consistency drift (naming,
+  organisation, repeated smells). Use when "code smell", "anti-pattern",
+  "technical debt", or "standardize the codebase". This PR/diff review →
+  audit-code-review.
+license: MIT
+effort: high
+---
+
+# Code Quality Audit
+
+**Degree of freedom: MIXED** — Parts 1–2 judgment `[HIGH freedom]`; convention
+greps and Validation `[LOW freedom — run exactly]`.
+
+> **Audit-and-fix exception.** Detect and then fix. Not present-then-stop.
+>
+> Fix the findings you reported, in the files you named; a repo-wide restyle
+> or rename pass the report did not list is a different session. Edit
+> surgically — the offending hook, key, or import — rather than rewriting
+> whole files. Pre-existing bugs met on the way go in the report as
+> follow-ups. Add or change tests only where the task asks or the repo
+> already keeps them for that surface; one-off greps and scratch scripts stay
+> out of the commit.
+
+Repo-wide React/TypeScript anti-patterns plus naming, organisation, and
+pattern consistency. A named PR/diff → `audit-code-review`.
+
+## How to reason
+
+1. **Observe** — quote the smell (`file:line`) and whether `git blame` / CONTRIBUTING marks it intentional
+2. **Interpret** — bug/perf risk, or style-only drift?
+3. **Classify** — anti-pattern / naming / organisation / pattern-split / intentional
+4. **Severity** — runtime bug or data-fetch `useEffect` = High; naming-only = Low
+
+## Worked example
+
+> **Observe:** `components/PaymentForm.tsx` has `'use server'` and a
+> `useEffect` that fetches invoices; four sortable lists use `key={i}`.
+> **Interpret:** server action lives in UI; fetch refires on remount; reorder remounts rows.
+> **Classify:** organisation + `useEffect`-for-data + index-as-key.
+> **Severity:** High (actions-in-components); Medium (keys).
+> **Finding:** `PaymentForm.tsx` | High | move action to `features/*/server/`;
+> replace fetch effect with TanStack Query
+
+## Before any change  [LOW freedom — run exactly]
+
+```bash
+cat CONTRIBUTING.md .cursor/rules/*.md 2>/dev/null | head -100 # existing conventions
+git log --oneline -20 | grep -i "convention\|pattern\|style" # recent decisions
+```
+
+Verify the "inconsistency" isn't intentional. Check `git blame` before touching working code.
+
+---
+
+## Part 1 — Anti-patterns  [HIGH freedom]
+
+### React
+
+#### Props drilling → Context or composition
+```tsx
+// Bad: prop drilled through 5+ levels
+<Layout user={user}><Sidebar user={user}><UserMenu user={user}><Avatar user={user} />
+
+// Fix: context for global state
+const UserContext = createContext<User | null>(null)
+const useUser = () => useContext(UserContext)
+
+// Fix: composition for UI concerns
+<Layout><Layout.Sidebar><UserMenu /></Layout.Sidebar></Layout>
+```
+
+#### Derived state in `useState` → `useMemo`
+```tsx
+// Bad
+const [items, setItems] = useState([])
+const [filtered, setFiltered] = useState([])
+useEffect(() => { setFiltered(items.filter(i => i.active)) }, [items])
+
+// Fix
+const filtered = useMemo(() => items.filter(i => i.active), [items])
+```
+
+#### `useEffect` for data fetching → Server Components or TanStack Query
+```tsx
+// Fix (Next.js 16 Server Component)
+async function DataDisplay() {
+ const data = await db.getData()
+ return <div>{data.name}</div>
+}
+
+// Fix (client with TanStack Query)
+const { data, isLoading } = useQuery({ queryKey: ['data'], queryFn: fetchData })
+```
+
+#### Object/array in dependency array → memoize or destructure
+```tsx
+// Bad: new object every render → infinite loop
+useEffect(() => { doSomething(options) }, [options])
+
+// Fix
+const options = useMemo(() => ({ page, limit }), [page, limit])
+useEffect(() => { doSomething(options) }, [options])
+```
+
+#### Index as key in dynamic lists → stable IDs
+```tsx
+// Bad
+{items.map((item, i) => <Item key={i} />)}
+// Fix
+{items.map(item => <Item key={item.id} />)}
+```
+
+#### Giant component → composition
+```tsx
+// Split by responsibility
+export function UserDashboard() {
+ const user = useUser()
+ return (
+ <DashboardLayout>
+ <UserHeader user={user} />
+ <UserStats userId={user.id} />
+ <RecentActivity userId={user.id} />
+ </DashboardLayout>
+ )
+}
+```
+
+### TypeScript
+
+```tsx
+// Bad: any
+function processData(data: any) { return data.items.map((i: any) => i.name) }
+
+// Fix: proper types + Zod validation
+const DataSchema = z.object({ items: z.array(z.object({ id: z.string(), name: z.string() })) })
+function processData(data: z.infer<typeof DataSchema>) { return data.items.map(i => i.name) }
+
+// Bad: enums (runtime object, not tree-shakeable)
+enum Status { Pending = 'pending', Active = 'active' }
+// Fix: union types
+type Status = 'pending' | 'active'
+
+// Fix: exhaustive switch
+function handle(s: Status): string {
+ switch (s) {
+ case 'pending': return 'Waiting'
+ case 'active': return 'Running'
+ default:
+ const _: never = s
+ throw new Error(`Unknown: ${_}`)
+ }
+}
+```
+
+### State management
+
+```tsx
+// Rule of thumb:
+// URL state (nuqs) → shareable, bookmarkable
+// Global state (Zustand) → cross-component, persisted
+// Local state (useState) → component-specific, ephemeral
+
+// Stale closure fix
+useEffect(() => {
+ const id = setInterval(() => setCount(c => c + 1), 1000) // functional update
+ return () => clearInterval(id)
+}, [])
+```
+
+### Architecture
+
+```
+// Circular deps → extract shared code / dependency inversion
+// Business logic in components → move to lib/feature/calculations.ts
+// God files → feature-based organisation:
+lib/
+ date/format.ts
+ currency/format.ts
+ validation/schemas.ts
+```
+
+---
+
+## Part 2 — Consistency audit  [HIGH freedom; greps LOW]
+
+### Naming conventions
+
+| Element | Expected | Check |
+|---------|----------|-------|
+| Components | PascalCase | `userCard` vs `UserCard` |
+| Hooks | `use` prefix | `fetchData` vs `useFetchData` |
+| Utils | camelCase | `format_date` vs `formatDate` |
+| Constants | SCREAMING_SNAKE | `apiUrl` vs `API_URL` |
+| Files | kebab-case | `UserCard.tsx` vs `user-card.tsx` |
+| Boolean props | `is/has/should` | `loading` vs `isLoading` |
+
+```bash
+rg "export (function|const|class) [a-z]" --type tsx # lowercase component exports
+rg "use[A-Z]" --type ts # hook patterns
+rg "export default" --type tsx -l | head -20 # mixed default/named exports
+```
+
+### File organisation (feature-sliced)
+
+```
+src/
+ features/{name}/
+ components/ # UI only
+ hooks/ # custom hooks
+ server/ # server actions
+ types.ts
+ schemas.ts
+ components/ui/ # shared primitives
+ lib/ # global utilities
+```
+
+Red flags:
+- Components in `/lib` or `/utils`
+- Server actions in component files
+- Types scattered across component files
+- Zod schemas inline in components
+
+```bash
+rg "z\.object" --glob "*/components/*" # inline schemas
+rg "'use server'" --glob "*/components/*" # actions in wrong place
+rg "from '\.\." --type tsx | head -20 # relative imports instead of @/
+```
+
+### Pattern consistency
+
+| Concern | Check |
+|---------|-------|
+| Server state | All TanStack Query, or mixed with useEffect? |
+| Forms | All React Hook Form, or controlled inputs too? |
+| Error handling | Consistent ActionResult shape? |
+| Styling | cn() used everywhere? Dark mode via CSS vars? |
+| Tests | `*.test.ts` vs `__tests__/`? Consistent mocking? |
+
+---
+
+## Coherency report template
+
+```markdown
+# Code Quality Audit
+
+## Summary
+- Verdict: [one line — what blocks, what is drift]
+- Critical findings: X
+
+## Anti-patterns found
+| Pattern | Files | Severity |
+|---------|-------|----------|
+| useEffect for data | 3 files | High |
+| Index as key | 2 files | Medium |
+
+## Naming convention findings
+| Element | Expected | Actual | Files |
+|---------|----------|--------|-------|
+| Components | PascalCase | Mixed | 4 |
+
+## Organisation findings
+- Server actions found in: components/PaymentForm.tsx
+- Types scattered in: 6 component files
+
+## Priority fixes
+1. Move server actions to features/*/server/
+2. Replace useEffect data fetching with TanStack Query
+3. Standardise component naming to PascalCase
+
+## Conventions to document
+1. Decision on default vs named exports
+2. Where Zod schemas live
+```
+
+---
+
+## Anti-pattern detection checklist
+
+### React checks
+- [ ] No `useEffect` for derived state
+- [ ] No index keys in dynamic lists
+- [ ] No objects/arrays in dependency arrays
+- [ ] Components under 300 lines
+- [ ] No prop drilling beyond 2 levels
+
+### TypeScript checks
+- [ ] No `any` (use `unknown` + validation)
+- [ ] No unsafe type assertions
+- [ ] Exhaustive switch statements
+- [ ] Zod schemas for all external data
+
+### Architecture checks
+- [ ] No circular dependencies
+- [ ] Business logic separated from UI
+- [ ] Files under 400 lines
+- [ ] Clear module boundaries
+
+## Self-critique before applying fixes  [LOW freedom — do not skip]
+
+1. **Evidenced** — `file:line` or rg hit, not "the codebase feels messy"
+2. **Reproducible** — the convention grep still finds it
+3. **Severity justified** — High = bug/perf, not naming taste
+4. **Right owner** — this PR/diff → `audit-code-review`
+5. **No-false-safety** — `git blame` checked; working intentional code left alone
+
+## Validation  [LOW freedom — run exactly]
+
+1. Typecheck with the repo's own script (`package.json` → `typecheck`, else `tsc --noEmit`)
+2. Lint with the repo's own script — not a generic `eslint src/`
+3. Run the repo's test script and confirm no new failures
+4. Document any enforced standard in `CONTRIBUTING.md` or `.cursor/rules/`

package/skills/audit-code-review/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: audit-code-review
+description: >
+  Review a PR or diff for correctness, security, and maintainability. Use for
+  a pull request, a named change set, or "review my changes". Repo-wide
+  anti-patterns → audit-code-quality. Bulk transforms → audit-codemod-safety.
+license: MIT
+effort: high
+---
+
+# Code Review Skill
+
+**Degree of freedom: MIXED** — Phases 1–2 judgment `[HIGH freedom]`;
+mandatory pre-review git/docs `[LOW freedom — run exactly]`.
+
+Review this PR or named diff. Repo-wide anti-patterns → `audit-code-quality`.
+Bulk transform semantics → `audit-codemod-safety`.
+
+## How to reason
+
+1. **Observe** — quote the hunk and the surrounding file (not the line alone)
+2. **Interpret** — what breaks, leaks, or duplicates if this merges?
+3. **Classify** — blocking / suggestion / nit / praise
+4. **Severity** — security, data-loss, or break-existing = blocking
+
+## Worked example
+
+> **Observe:** new `GET /api/invoices/:id` returns `Invoice.findById(id)`
+> with no `userId` predicate (`app/api/invoices/[id]/route.ts` in this diff).
+> **Interpret:** any authenticated caller reads another user's invoice.
+> **Classify:** blocking (IDOR).
+> **Severity:** Critical — must fix before merge.
+> **Finding:** `[id]/route.ts` | add ownership check | blocking
+
+## Pre-review checks  [LOW freedom — run exactly]
+
+**Before reviewing code:**
+
+### 1. Read Relevant Documentation
+```
+README.md (project conventions)
+src/[domain]/@_[domain]-README.md (domain-specific patterns)
+CONTRIBUTING.md (code standards)
+```
+
+### 2. Understand the Full Change
+
+If reviewing a PR or commit:
+```bash
+git log --oneline -10 # recent context
+git diff <base>..HEAD --stat # files changed
+git diff <base>..HEAD # full diff
+```
+
+If reviewing a specific file, read the FULL file for context — not just the changed lines.
+
+### 3. Check for Duplicate Implementations
+
+Use `Grep` and `SemanticSearch` to verify:
+- Does this code duplicate existing functionality?
+- Is there an existing component/service that should have been extended?
+- Does this follow established patterns in the codebase?
+
+### 4. Check Production Impact (Sentry)
+
+If the change touches error-prone code, check if related Sentry issues exist:
+
+```json
+sentry:search_issues
+{
+ "organizationSlug": "<ORG_SLUG>",
+ "query": "issues related to <component or function being changed>",
+ "projectSlugOrId": "<PROJECT_SLUG>",
+ "regionUrl": "<REGION_URL>",
+ "limit": 10
+}
+```
+
+This reveals: does the code being changed have known production issues? Does this change fix or risk introducing them?
+
+### 5. Research Current Best Practices (for non-trivial patterns)
+
+If the code uses a pattern you want to verify:
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<framework> <pattern> best practice <current year>",
+ "limit": 5,
+ "sources": [{ "type": "web" }]
+}
+```
+
+---
+
+## Review Process  [HIGH freedom]
+
+### Phase 1: High-Level Assessment
+
+Before line-by-line review:
+- What is the purpose of this change?
+- Does the approach make sense architecturally?
+- Are there simpler alternatives?
+- Does this introduce new dependencies? Are they justified?
+
+### Phase 2: Detailed Review Checklist
+
+#### Correctness
+- [ ] Logic is correct for all expected inputs
+- [ ] The change does what the PR / task says — a missing requirement, half-implemented path, or silently narrowed scope is a blocking finding
+- [ ] Edge cases handled (null, empty, overflow, concurrent access)
+- [ ] No obvious bugs (off-by-one, wrong operator, missing await)
+- [ ] Error handling is full and appropriate
+- [ ] Async code handles race conditions and cleanup (AbortController, etc.)
+
+#### Security
+- [ ] No SQL injection vectors (raw queries with user input)
+- [ ] No XSS vulnerabilities (dangerouslySetInnerHTML, innerHTML)
+- [ ] No hardcoded secrets or credentials
+- [ ] Input validation present on all user-facing endpoints
+- [ ] Auth/authz properly checked (not just at UI level)
+- [ ] No sensitive data in logs or error messages
+
+#### Performance
+- [ ] No N+1 queries (batching, eager loading)
+- [ ] No unnecessary loops or repeated computations
+- [ ] Appropriate data structures (Map vs Object, Set vs Array)
+- [ ] No memory leaks (event listeners cleaned up, subscriptions unsubscribed)
+- [ ] React: no unnecessary re-renders (memo, useMemo, useCallback where appropriate)
+- [ ] Database: queries use indexes, avoid full table scans
+
+#### Readability
+- [ ] Clear, descriptive names (functions, variables, types)
+- [ ] Functions appropriately sized (single responsibility)
+- [ ] Comments explain "why" not "what" (non-obvious constraints only)
+- [ ] Consistent with project's existing style
+
+#### Maintainability
+- [ ] DRY — no duplicated logic that should be shared
+- [ ] Single responsibility — each function/component does one thing
+- [ ] No magic numbers or strings (use constants or union types)
+- [ ] Types are specific (no `any`, no overly broad unions)
+- [ ] Dependencies are appropriate and minimal
+
+#### Testing
+- [ ] Tests cover the change (happy path + edge cases)
+- [ ] Tests are independent and deterministic
+- [ ] No flaky tests introduced (timeouts, race conditions)
+- [ ] Test names describe the expected behavior
+
+#### Duplicate Prevention
+- [ ] No duplicate components (checked `src/components/`)
+- [ ] No duplicate services or hooks
+- [ ] Extends rather than duplicates existing patterns
+- [ ] Shared logic extracted to utility/hook when used 2+ times
+
+---
+
+## Feedback Format
+
+Use severity levels:
+
+```markdown
+### Critical (must fix before merge)
+**[File:Line]** — [Description]
+Why: [Impact if not fixed]
+Fix: [Specific suggestion]
+
+### Suggestion (recommended improvement)
+**[File:Line]** — [Description]
+Why: [Benefit of the change]
+Alternative: [How to improve]
+
+### Nitpick (optional, non-blocking)
+**[File:Line]** — [Description]
+
+### Praise (good patterns to reinforce)
+**[File:Line]** — [What's done well and why]
+```
+
+---
+
+## Blocking vs Non-Blocking
+
+### Blocking (must fix)
+- Security vulnerabilities
+- Data corruption risks
+- Breaking existing functionality
+- Missing critical error handling
+- Performance regressions (measurable)
+- Type safety violations (`any`, unchecked casts)
+
+### Non-Blocking (suggestions)
+- Better naming or organization
+- Missing tests for edge cases
+- Documentation gaps
+- Minor performance improvements
+- Style preferences not covered by linter
+
+---
+
+## Common Patterns to Flag
+
+### TypeScript/JavaScript
+```typescript
+// BLOCK: any types
+const data: any = response;
+
+// BLOCK: unhandled promises
+fetchData(); // missing await or .catch()
+
+// BLOCK: implicit type coercion in conditions
+if (value) // when value could be 0 or ""
+
+// SUGGEST: magic strings
+if (status === 'active') // use a constant or union type
+```
+
+### React
+```tsx
+// BLOCK: missing key in lists
+{items.map(item => <Item {...item} />)}
+
+// BLOCK: stale closure in useEffect
+useEffect(() => {
+ setInterval(() => console.log(count), 1000); // captures stale count
+}, []);
+
+// SUGGEST: inline object creation in props
+<Component style={{ margin: 10 }} /> // new object each render
+```
+
+### Database
+```sql
+-- BLOCK: SQL injection vector
+WHERE name = '${userInput}'
+
+-- SUGGEST: missing index
+SELECT * FROM orders WHERE user_id = ? -- is user_id indexed?
+
+-- SUGGEST: SELECT *
+SELECT * FROM users -- select only needed columns
+```
+
+---
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **Evidenced** — `File:Line` from the diff, not "this could be better"
+2. **Reproducible** — read the full file, not only the hunk
+3. **Severity justified** — blocking = security / data-loss / break / missing critical handling
+4. **Right owner** — repo-wide smells → `audit-code-quality`; bulk transform → `audit-codemod-safety`
+5. **No-false-safety** — linter-covered style is not blocking
+
+## Review Response Template
+
+```markdown
+## Code Review: [PR Title / File]
+
+### Summary
+[1-2 sentence overall assessment — is this ready to merge?]
+
+### Critical (blocking)
+[List any must-fix findings]
+
+### Suggestions (recommended)
+[List recommended improvements]
+
+### Praise
+[Highlight good practices — reinforces positive patterns]
+
+### Questions
+[Clarifying questions about intent or design decisions]
+
+### Research Notes
+[If patterns were verified via Firecrawl/Context7, note what was confirmed]
+```
+
+---
+
+## What counts as a finding
+
+Blocking findings are correctness bugs, security holes, data-loss paths, and
+gaps between what the change claims and what it does; suggestions and nits
+follow the Feedback Format above. Each finding names the line, the
+consequence, and a fix. Style that the linter or the codebase's own
+conventions already cover is not a finding at any tier. Read the surrounding
+code before judging a hunk, and where intent is unclear, ask in the Questions
+section rather than assume.