project-audit

gistfile1.txt

# Skill: RTK Project Audit

## Purpose

Run a non-invasive audit of this Next.js / TypeScript repository using only
commands that exist in the current `rtk` CLI.

Use this audit to identify architecture risks, type-safety debt, maintainability
hotspots, test coverage gaps, and infrastructure issues without making code
changes.

## Rules

- Run every shell command through `rtk`.
- Do not use raw shell commands unless wrapped with `rtk proxy`.
- Prefer commands that exit successfully and produce evidence.
- Treat failing validation commands as project findings, not as audit-command
  failures.
- Do not modify `src/` during an audit.
- Do not modify `skills/` unless the user explicitly asks.

## Command Set

These commands are verified against the current `rtk` command list:

```bash
rtk --version
rtk --help
rtk read package.json
rtk read tsconfig.json
rtk read eslint.config.mjs
rtk deps
rtk git status
rtk proxy find src -maxdepth 2 -type d
rtk proxy -- rg --files src
rtk proxy -- rg --files src -g '*.ts' -g '*.tsx'
rtk proxy -- rg --files src -g '*test.ts' -g '*test.tsx' -g '*spec.ts' -g '*spec.tsx'
rtk proxy -- rg -n "from ['\"](\\.\\./){2,}" src
rtk proxy -- rg -n "from ['\"]@/features|from ['\"]@/app|from ['\"]@/store" src/shared
rtk proxy -- rg -n "no-explicit-any|\\sas any\\b|: any\\b|@ts-ignore|@ts-expect-error" src
rtk proxy -- rg -n "console\\." src
rtk proxy -- rg -n "'use client'" src/app src/features src/shared
rtk proxy -- rg -n "process\\.env|NEXT_PUBLIC|AWS|KEYCLOAK|STRIPE|SENTRY" src
rtk proxy -- rg -n "\"use server\"|'use server'" src
rtk proxy -- rg -n "createContext" src
rtk proxy -- rg -n "use[A-Z][a-zA-Z]+\\(" src
rtk proxy -- rg -n "next-auth|clerk|auth\\(" src package.json
rtk proxy find src -type f -name '*.tsx' -exec wc -l '{}' +
rtk git log --stat -20
rtk git log --name-only --pretty=format:
rtk tsc --noEmit
rtk test
```

Avoid these commands in this repository unless they are fixed first:

```bash
rtk gain
rtk diff
rtk audit
rtk map
rtk size
rtk files
rtk largest
rtk architecture
rtk routes
rtk client
rtk server
rtk hooks
rtk context
rtk stack
rtk types
rtk any
rtk ignores
rtk assertions
rtk strict
rtk dup
rtk graph
rtk cycles
rtk dead
rtk unused-deps
rtk unused-exports
rtk hotspots
rtk churn
rtk ownership
rtk history
rtk middleware
rtk api
rtk actions
rtk infra
rtk ci
rtk observability
rtk build
rtk bundle
rtk tests
rtk risk
rtk health
rtk report
```

Extended commands from the original audit prompt are allowed. Run them through
`rtk proxy npx`, `rtk npm`, or `rtk next`. Treat non-zero exits as audit
findings when they come from project state, and request approval when they need
network access to download an `npx` package:

```bash
rtk proxy npx jscpd src
rtk proxy npx madge src --extensions ts,tsx --circular
rtk proxy npx madge src --extensions ts,tsx --image /tmp/iclients-dependency-graph.svg
rtk proxy npx ts-prune
rtk proxy npx depcheck
rtk npm run build
rtk proxy env ANALYZE=true npm run build
```

## Audit Workflow

### 1. Repository Shape

Run:

```bash
rtk proxy find src -maxdepth 2 -type d
rtk proxy -- rg --files src
```

Report:

- App Router structure
- FSD-like layers
- route groups
- API routes
- shared modules
- test locations

### 2. Config And Stack

Run:

```bash
rtk read package.json
rtk read tsconfig.json
rtk read eslint.config.mjs
rtk deps
```

Report:

- framework versions
- state libraries
- validation libraries
- test stack
- strict TypeScript settings
- lint rules that affect architecture or safety

### 3. Type Safety

Run:

```bash
rtk proxy -- rg -n "no-explicit-any|\\sas any\\b|: any\\b|@ts-ignore|@ts-expect-error" src
rtk tsc --noEmit
```

Report:

- explicit `any`
- `as any`
- suppressed TypeScript errors
- TypeScript compile status
- highest-risk files

### 4. Architecture Boundaries

Run:

```bash
rtk proxy -- rg -n "from ['\"](\\.\\./){2,}" src
rtk proxy -- rg -n "from ['\"]@/features|from ['\"]@/app|from ['\"]@/store" src/shared
```

Report:

- deep relative imports
- upward imports from `shared`
- likely FSD boundary violations
- places that should move constants/types down to `shared`

### 5. Client/Server Shape

Run:

```bash
rtk proxy -- rg -n "'use client'" src/app src/features src/shared
rtk proxy -- rg -n "\"use server\"|'use server'" src
rtk proxy -- rg -n "createContext" src
rtk proxy -- rg -n "use[A-Z][a-zA-Z]+\\(" src
rtk proxy -- rg -n "process\\.env|NEXT_PUBLIC|AWS|KEYCLOAK|STRIPE|SENTRY" src
rtk proxy -- rg -n "next-auth|clerk|auth\\(" src package.json
```

Report:

- client component count hotspots
- server actions
- React contexts
- hook-heavy areas
- server-only env usage
- public env usage
- authentication usage
- sensitive integration areas

### 6. Size Hotspots

Run:

```bash
rtk proxy find src -type f -name '*.tsx' -exec wc -l '{}' +
```

Report:

- components over 200 lines
- components over 500 lines
- likely extraction targets

### 7. Git Archaeology

Run:

```bash
rtk git log --stat -20
rtk git log --name-only --pretty=format:
```

Report:

- recently changed files
- high-churn areas
- large changed files that overlap size hotspots

### 8. Tests

Run:

```bash
rtk proxy -- rg --files src -g '*test.ts' -g '*test.tsx' -g '*spec.ts' -g '*spec.tsx'
rtk test
```

Report:

- unit/component/e2e test distribution
- high-risk features without tests
- test command status

### 9. Console And Runtime Noise

Run:

```bash
rtk proxy -- rg -n "console\\." src
```

Report:

- debug logs
- production logging in client code
- places that should use `logger`, `notification`, or structured error handling

## Report Format

Use this structure:

```text
Status
- Commands run
- Commands passed
- Commands failed

Repository Summary
- Stack
- Architecture
- Test stack

Findings
- High
- Medium
- Low

Validation
- TypeScript
- Tests
- Lint, if run

Recommendations
- Immediate
- Short-term
- Later
```

Keep findings concrete: include file paths, command evidence, and whether the
recommendation is breaking or non-breaking.

## Coverage Against Original Prompt

Covered with verified RTK commands:

- structure: `tree`, `fd` -> `rtk proxy find`, `rtk proxy -- rg --files`
- size: `find ... wc`, largest files -> `rtk proxy find ... -exec wc -l`
- package inspection: `jq package.json` -> `rtk read package.json`, `rtk deps`
- client/server/context/hooks/env/auth discovery -> `rtk proxy -- rg`
- type safety: `rg any`, `rg as any`, suppressions, `npx tsc` -> `rtk proxy -- rg`,
  `rtk tsc --noEmit`
- git archaeology: `git log` -> `rtk git log`
- tests: `npm test` style check -> `rtk test`
- infrastructure file review -> `rtk read` for specific files when present

Covered by the extended audit:

- duplicate code with `jscpd`
- dependency graph with `madge`
- dead code with `ts-prune`
- unused dependencies with `depcheck`
- build and bundle analyze

Note: these commands may download packages, create generated artifacts, or fail
because of project/runtime configuration. `madge --image` also requires Graphviz
(`gvpr`) in `PATH`; if Graphviz is missing, record that as an environment
finding and keep `madge --circular` as the dependency-cycle check.