Expand stack checklists and add consistency check step

- Add Step 1.5 (Consistency Check) to SKILL.md: check existing
  conventions before flagging violations
- Add API validation instruction referencing context7 docs
- Add inertia.md and pest.md as new stack files
- Expand laravel.md with caching, HTTP client, queues, events,
  validation, collections, and advanced query patterns
- Expand tailwind.md with v3/v4 version detection, structured
  sections, and common pitfalls
- Expand vue.md with common pitfalls, Inertia.js section,
  and improved formatting

Author: Felipe Reis

SKILL.md

@@ -70,6 +70,8 @@ Before reviewing anything, identify the project's stack by inspecting the follow
 
 Based on what you find, load and apply **only** the stack and pattern files that match this project. Do not evaluate or report on technologies not present.
 
+> **API Validation:** Before flagging a misuse of a library API, validate the syntax and best practice against live docs using `mcp__plugin_context7_context7__query-docs` for the version detected in `package.json` or `composer.json`. Avoids false positives from outdated training data.
+
 **Stack files to load if relevant:**
 
 Read these files using the path relative to this skill file's directory. If a file cannot be read, continue with the generic rules above.
@@ -92,6 +94,8 @@ Read these files using the path relative to this skill file's directory. If a fi
 - `./stacks/docker.md`
 - `./stacks/terraform.md`
 - `./stacks/kafka.md`
+- `./stacks/inertia.md`
+- `./stacks/pest.md`
 
 **Pattern files to load if relevant:**
 
@@ -105,6 +109,16 @@ Read these files using the path relative to this skill file's directory. If a fi
 
 ---
 
+## Step 1.5 — Consistency Check
+
+Before flagging any pattern violation, check what the codebase already does. Laravel, Vue, and similar frameworks offer multiple valid approaches — the best choice is the one already established in the project, even if another would be theoretically better. **Inconsistency is worse than a suboptimal pattern.**
+
+- Check sibling controllers, services, components, or tests for established conventions
+- If the project already uses a non-standard pattern consistently, follow it — report it as a **Suggestion** at most, not a blocker
+- These checklist rules are defaults for when no pattern exists yet, not overrides of working conventions
+
+---
+
 ## 1. Security
 
 - **Injection vulnerabilities**: SQL injection, command injection, XSS, LDAP injection

stacks/inertia.md

@@ -0,0 +1,64 @@
+# Inertia.js — Code Review Checklist
+
+> Load when project uses Inertia.js (check `package.json` for `@inertiajs/vue3` or `@inertiajs/react`).
+> Detect Inertia version — v1 and v2 have different APIs (deferred props, `<Form>` component, `usePoll`, `WhenVisible` are v2+).
+
+## Navigation
+
+- **`<Link>` over `<a>`**: all internal navigation uses Inertia `<Link>`; `<a>` breaks SPA behavior and causes full page reload
+- **Method on `<Link>`**: non-GET navigations use `method="post"` + `as="button"`; not a plain anchor
+- **Prefetching**: `prefetch` added on `<Link>` for critical navigation paths
+- **Programmatic navigation**: `router.visit()` used; `window.location` bypasses Inertia lifecycle
+- **Preserve state**: `preserveState: true` passed to `router.visit()` when scroll position or form state must survive navigation
+
+## Page Components
+
+- **Single root element**: Vue page components have exactly one root element; Inertia mounts to the first root
+- **Props typed**: `defineProps()` types match the data shape returned by the controller
+- **No direct API calls**: data flows via Inertia props from the server; no `fetch()` / `axios` calls in page components unless absolutely necessary and documented
+
+## Forms
+
+- **`<Form>` vs `useForm` consistency**: one approach used consistently (Consistency Check applies); `<Form>` for simple cases, `useForm` for programmatic control
+- **Submit prevention**: native `<form>` uses `@submit.prevent`
+- **Loading state**: `processing` shown during submission; submit button disabled while processing
+- **Error display**: per-field errors shown via `errors.field`; `hasErrors` used for global error banner
+- **Reset on success**: `reset-on-success` / `setDefaultsOnSuccess` on `<Form>` where appropriate
+- **Password reset**: `form.reset('password')` on success for password fields
+
+## Deferred Props (v2+)
+
+- **Loading skeleton**: every deferred prop has a visible loading state — skeleton, spinner, or placeholder; no blank UI while loading
+- **`undefined` guard**: deferred prop checked before accessing sub-properties (`prop?.value`, not `prop.value`)
+- **Fallback matches layout**: skeleton dimensions approximate the final content to prevent layout shift
+
+## Polling (v2+)
+
+- **`usePoll` over `setInterval`**: `usePoll` handles unmount cleanup and tab-inactive throttling; manual `setInterval` does not
+- **Partial reloads**: `only: ['propName']` passed to avoid reloading unused props on every poll tick
+- **`keepAlive`**: `keepAlive: true` set intentionally only when background-tab polling is required; default false preserved
+- **`autoStart: false`**: manual polling wired to UI controls via returned `start()` / `stop()`
+
+## Infinite Scroll / WhenVisible (v2+)
+
+- **`<WhenVisible>` over scroll listeners**: used for infinite pagination; `data` and `params` set correctly
+- **Fallback slot**: `<template #fallback>` has a loading indicator; not empty
+- **Next page guard**: `WhenVisible` rendered only when `next_page_url` (or equivalent) is non-null
+
+## Server-Side Patterns
+
+- **`Inertia::render()`**: controller returns `Inertia::render('Page/Name', [...props])` — not a JSON response
+- **Shared data**: global props (auth user, flash messages) shared via `Inertia::share()` in middleware, not duplicated per controller
+- **Deferred props**: `Inertia::defer(fn)` used for props that are expensive to compute and not needed for first paint
+- **Lazy props**: `Inertia::lazy(fn)` (v1) / `Inertia::defer(fn)` (v2) used appropriately per installed version
+
+## Common Pitfalls
+
+- `<a href>` instead of `<Link>` — full page reload, breaks SPA
+- No loading state on deferred props — blank or broken UI during load
+- Deferred prop accessed without `undefined` guard — runtime error before data arrives
+- `window.location` for navigation — bypasses Inertia lifecycle, no progress bar
+- `setInterval` instead of `usePoll` — no cleanup on unmount
+- `<Form>` component used in projects with Inertia v1 — component does not exist in v1
+- `fetch()` / `axios` calls in page components — bypasses Inertia's request lifecycle, breaks shared middleware logic
+- Missing `preserveState` on visit when scroll position matters

stacks/laravel.md

@@ -1,45 +1,133 @@
 # Laravel — Code Review Checklist
 
+> Check sibling files for existing patterns before flagging any violation (see Consistency Check step).
+
 ## Eloquent & Database
+
 - **Eloquent best practices**: use scopes, accessors, mutators; avoid raw queries unless necessary
 - **Model casting**: casts defined for dates, enums, booleans, and serialized objects via the `casts()` method
 - **Chunking large datasets**: `chunk()`, `cursor()`, or `lazy()` used when processing large volumes of records to avoid memory exhaustion
 - **Aggregate helpers**: `withCount()`, `withSum()`, `withAvg()` used instead of loading collections just to aggregate
 - **preventLazyLoading**: `Model::preventLazyLoading()` enabled in development to catch N+1 at dev time
 - **Soft deletes**: `withTrashed()` / `onlyTrashed()` used intentionally; deleted records not accidentally leaked in queries
+- **Select only needed columns**: `SELECT *` avoided; specify columns explicitly in complex queries
+- **`whereBelongsTo()`**: used for cleaner relationship queries instead of manual `where('model_id', $model->id)`
+- **`whereIn + pluck`**: preferred over `whereHas()` for better index usage when filtering by related model IDs
+
+## Advanced Query Patterns
+
+- **`addSelect()` subqueries**: used over eager-loading entire has-many relations just to get a single aggregate value
+- **Dynamic relationships via subquery**: subquery FK + `belongsTo` used to avoid N+1 when accessing a single "latest" or "first" related record
+- **Conditional aggregates**: `CASE WHEN` in `selectRaw()` used instead of multiple count queries
+- **`setRelation()`**: used to prevent circular N+1 when manually constructing relationships
+- **Compound indexes**: match `orderBy` column order; correlated subqueries in `orderBy` for has-many sorting (avoid joins that multiply rows)
+
+## Caching
+
+- **`Cache::remember()`**: used over manual get/put pairs
+- **`Cache::flexible()`**: used for stale-while-revalidate on high-traffic data that can serve slightly stale content
+- **`Cache::memo()` / `once()`**: avoid redundant cache hits within a single request; `once()` for per-object memoization
+- **Cache tags**: used to invalidate groups of related cache entries atomically
+- **`Cache::add()`**: used for atomic conditional writes (set if not exists)
+- **`Cache::lock()`**: used for race conditions; `lockForUpdate()` for DB-level locking
+- **Failover stores**: `Cache::store()` with fallback configured in production
+
+## HTTP Client
+
+- **Explicit timeouts**: every outbound HTTP call has `timeout()` and `connectTimeout()`; no fire-and-forget calls without timeouts
+- **Retry with backoff**: `retry()` with exponential delays for external APIs; non-retriable errors (4xx) not retried
+- **Status check**: `throw()` or explicit status check after every response; no silent failures
+- **`Http::pool()`**: used for concurrent independent HTTP requests instead of sequential calls
+- **Testing**: `Http::fake()` + `Http::preventStrayRequests()` in all tests touching HTTP calls
+
+## Queues & Jobs
+
+- **`retry_after` > `timeout`**: `retry_after` in queue config must exceed the job's `$timeout`; prevents duplicate processing
+- **Exponential backoff**: `backoff()` returns `[1, 5, 10]` or similar; not relying on uniform retries
+- **`ShouldBeUnique`**: implemented on jobs that must not run concurrently; `WithoutOverlapping::untilProcessing()` for overlap prevention
+- **`failed()` always present**: every job implements `failed(Throwable $e)`; failures not silently discarded
+- **`retryUntil()` + `$tries = 0`**: when using `retryUntil()`, set `$tries = 0` to avoid early bail-out
+- **`RateLimited` middleware**: used for jobs calling external APIs; `Bus::batch()` for related parallel jobs
+- **`Bus::chain()`**: used correctly for sequential job dependencies
+
+## Events & Notifications
+
+- **`ShouldDispatchAfterCommit`**: events dispatching side effects (emails, notifications, external calls) use this to prevent firing before the DB transaction commits
+- **Event discovery**: manual registration avoided; `event:cache` run in production
+- **`ShouldQueue`**: notifications and mailables are queued; synchronous sending only for critical flows
+- **`assertQueued()`**: used in tests for queued mailables/notifications, not `assertSent()`
 
 ## Controllers & Actions
-- **Form Requests**: validation logic lives in Form Request classes, not controllers; `authorize()` method implemented correctly — not returning `true` by default on all protected requests
-- **Single Action Controllers**: `__invoke` controllers used for simple, single-purpose actions instead of generic multi-method controllers
-- **Action classes**: reusable business logic that doesn't belong to a Service extracted to invokable Action classes
+
+- **Form Requests**: validation in Form Request classes; `authorize()` not returning `true` by default on all protected requests
+- **Single Action Controllers**: `__invoke` controllers for simple single-purpose actions
+- **Action classes**: invokable Actions for reusable business logic that doesn't belong to a Service
+- **Controller methods**: under 10 lines; complex logic extracted to services or actions
 
 ## Collections & Helpers
-- **Collection pipelines**: `map`, `filter`, `reduce`, `groupBy`, etc. used instead of manual loops where clearer
-- **Laravel helpers**: `Str::` and `Arr::` helpers used instead of raw PHP functions when they offer more clarity or safety
 
-## Queues & Jobs
-- **Unique jobs**: `ShouldBeUnique` implemented on jobs that must not be enqueued more than once simultaneously
-- **Job batching & chaining**: `Bus::chain()` / `Bus::batch()` used correctly when jobs have sequential or parallel dependencies
-- **Job configuration**: `$tries`, `$timeout`, and `backoff()` defined explicitly; not relying solely on global defaults
+- **Collection pipelines**: `map`, `filter`, `reduce`, `groupBy` used over manual loops
+- **`cursor()` vs `lazy()`**: `cursor()` for memory-efficient iteration without relationships; `lazy()` when relationship loading needed; `lazyById()` when updating records while iterating
+- **`toQuery()`**: converts a collection back to a query builder for bulk operations (update/delete) without loading models
+- **Laravel helpers**: `Str::` and `Arr::` over raw PHP functions; `Str::of()`, `$request->string()` for fluent string operations
 
 ## Security & Auth
-- **Policy enforcement**: `$this->authorize()` or `Gate::authorize()` called in controllers; not relying solely on route middleware
-- **Sanctum token scopes**: API tokens issued with minimal required abilities; abilities checked explicitly in guarded routes
+
+- **Policy enforcement**: `$this->authorize()` or `Gate::authorize()` called in controllers; not relying solely on route middleware for authorization
+- **Sanctum token scopes**: API tokens issued with minimal required abilities; abilities checked explicitly
+- **Mass assignment**: `$fillable` or `$guarded` defined on every model
+- **`$request->validated()`**: only validated data used — never `$request->all()` or `$request->input()` without validation
+
+## Validation & Forms
+
+- **Form Request classes**: `$request->validated()` only — never `$request->all()`
+- **`Rule::when()`**: conditional validation rules; not inline ternaries
+- **Array notation**: `['required', 'email']` for new code; follow existing convention if project uses string pipes
+- **`after()` hook**: used instead of `withValidator()` for post-validation logic
 
 ## Testing
-- **withoutExceptionHandling**: used in tests that need to inspect the real exception, not the formatted error response
-- **Database assertions**: `assertDatabaseHas`, `assertDatabaseMissing`, `assertSoftDeleted` used for persistence assertions
-- **Factory states**: existing factory states reused instead of manually configuring models in every test
+
+- **`LazilyRefreshDatabase`**: preferred over `RefreshDatabase` for speed in large test suites
+- **`assertModelExists()`**: over raw `assertDatabaseHas()` when asserting model persistence
+- **Factory states**: existing states reused; not manually configuring models in every test
+- **Fakes after factories**: `Event::fake()`, `Mail::fake()`, etc. called after factory setup (not before), otherwise factory observers/events may be silenced
+- **`recycle()`**: shares relationship instances across related factories to avoid orphaned records
+- **`withoutExceptionHandling()`**: used in tests that need to inspect the real exception
+- **`Http::fake()` + `preventStrayRequests()`**: always in tests touching external HTTP
 
 ## Routing & Config
-- **Route model binding**: used where appropriate instead of manual `find()` + 404 checks
-- **Config & env**: no `env()` calls outside of config files; all config accessed via `config()`
-- **Named routes**: `route()` helper used with named routes; no hardcoded URL strings
+
+- **Route model binding**: used instead of manual `find()` + 404 checks
+- **Scoped bindings**: `->scopeBindings()` for nested resources
+- **`env()` only in config files**: application code accesses values via `config()` — never `env()` directly
+- **Named routes**: `route()` helper used; no hardcoded URL strings
+- **`App::environment()`**: used for environment checks; not `app()->environment()` string comparison via `env()`
+
+## Migrations
+
+- **`constrained()`**: all foreign keys use `constrained()` for consistent cascades and index creation
+- **One concern per migration**: DDL and DML never mixed in the same migration
+- **Defaults mirrored in model**: column defaults in migration mirrored in `$attributes` array on the model
+- **Reversible `down()`**: `down()` correctly undoes `up()` without data loss; forward-fix migrations for intentionally irreversible changes
+- **Indexes added in migration**: not as an afterthought; never added manually in production without migration
 
 ## Architecture
-- **Service layer**: complex business logic extracted to services, not bloating controllers
-- **API Resources**: responses use API Resources/Transformers for consistent formatting
-- **Blade/views**: no business logic in Blade templates; use view composers or components
-- **Events & Listeners**: side effects (emails, notifications, logs) triggered via events, not inline
-- **Dependency injection**: use constructor injection via the service container; avoid facades in business logic when testability matters
-- **Migrations**: schema changes use migrations; migrations are reversible (`down` method)
+
+- **Service layer**: complex business logic in services; controllers delegate, not implement
+- **API Resources**: responses formatted via `JsonResource`; no raw `$model->toArray()` in controllers
+- **Events & Listeners**: side effects triggered via events; not inline in controllers or services
+- **Dependency injection**: constructor injection; facades avoided in business logic when testability matters
+- **`defer()`**: post-response work deferred; `Context` for request-scoped shared data; `Concurrency::run()` for parallel execution
+- **Blade/views**: no business logic in templates; use view composers or components
+
+## Common Pitfalls
+
+- `env()` called directly in application code instead of `config()`
+- `$request->all()` used instead of `$request->validated()`
+- `authorize()` in Form Request returns `true` unconditionally
+- Job `$timeout` exceeds `retry_after`, causing duplicate processing
+- Events dispatched inside DB transactions without `ShouldDispatchAfterCommit`
+- `Http::fake()` missing in tests → real HTTP calls in CI
+- Fakes set up before factories, silencing model observers
+- `whereHas()` used where `whereIn + pluck()` would use an index
+- `Cache::remember()` without tags when cache invalidation is needed