Standalone Mode
If invoked directly (not via the orchestrator), you must first:
- Read
../codeprobe/shared-preamble.md (resolve relative to this SKILL.md's location — the sibling codeprobe skill directory — not the user's project) for the output contract, execution modes, and constraints.
- Load applicable reference files from
../codeprobe/references/ (same resolution) based on the project's tech stack.
- Default to
full mode unless the user specifies otherwise.
Framework-Specific Best Practices
Domain Scope
This sub-skill detects framework-specific anti-patterns and convention violations. Unlike other sub-skills that apply universal principles, this one loads framework-specific reference guides and checks against framework idioms.
Supported frameworks:
- PHP / Laravel — Eloquent ORM, routing, validation, queues, events, configuration
- React / Next.js — Component design, hooks, data fetching, type safety
- Python / Django / FastAPI — PEP conventions, ORM patterns, async handling
Important: If no supported framework is detected at the target path, emit zero findings and return an empty summary with a note: "No supported framework detected — skipping framework-specific checks."
Version Awareness: When checking framework conventions, attempt to determine the framework version:
- Laravel: check
composer.json for laravel/framework version. Laravel 9+ uses attribute-based accessors instead of getXAttribute().
- Next.js: check
next.config.* and package.json for Next.js version. 13+ uses App Router with app/ directory.
- Django: check
requirements.txt or setup.py for Django version.
What It Does NOT Flag
- Issues already covered by other sub-skills even if they appear in framework code. Specifically:
- Security issues in framework code → covered by
codeprobe-security (SEC)
- SOLID violations in framework classes → covered by
codeprobe-solid (SRP/OCP/etc.)
- Performance issues like N+1 queries → covered by
codeprobe-performance (PERF)
- Error handling in framework middleware → covered by
codeprobe-error-handling (ERR)
- This sub-skill focuses exclusively on framework idiom violations — using the framework incorrectly or ignoring its conventions.
- When this sub-skill and another sub-skill flag the same file:line range, the orchestrator's deduplication step (Section 7A) will keep the finding in whichever category is most relevant and mark the framework finding as a duplicate.
- Framework-generated boilerplate files (migration stubs, config defaults, scaffolded controllers).
- Intentional deviations from framework conventions with clear comments explaining the reason.
- Test files — test-specific framework usage has different conventions.
Detection Instructions
PHP / Laravel
| ID Prefix |
Area |
What to Detect |
How to Detect |
Severity |
FWK |
Eloquent |
Raw queries where Eloquent query builder works |
Search for DB::select(), DB::statement(), raw SQL strings in model/service code where Eloquent's query builder (where(), join(), whereHas()) would be cleaner and safer. Exclude complex reporting queries that genuinely need raw SQL. |
Minor |
FWK |
Eloquent |
Missing $casts on model |
Model attributes that should be cast (dates, booleans, arrays, JSON) accessed without $casts definition. Look for manual casting in accessors or repeated (bool), (int), json_decode() on model attributes. |
Minor |
FWK |
Eloquent |
Repeated WHERE conditions without scopes |
Same where() condition chain used in 3+ locations on the same model. Should be extracted into a named scope (scopeActive(), scopePublished()). |
Minor |
FWK |
Routing |
Logic in route closures instead of controllers |
Route definitions in routes/web.php or routes/api.php with closure handlers exceeding 3 lines. Should be moved to controller methods. |
Minor |
FWK |
Routing |
Missing route model binding |
Routes that accept an ID parameter and manually call Model::find($id) or Model::findOrFail($id) instead of using route model binding in the method signature. |
Minor |
FWK |
Validation |
Validation in controller instead of Form Request |
Controller methods with inline validation rules ($request->validate([...]) exceeding 5 rules). Should use a dedicated Form Request class. |
Minor |
FWK |
Queues |
Long-running tasks in request cycle |
Operations likely to take > 5 seconds (sending emails, generating PDFs, calling external APIs, processing uploads) executed synchronously in a controller/request handler. Should be dispatched to a queue. |
Major |
FWK |
Queues |
Queue jobs without retry configuration |
Job classes missing $tries, $timeout, or $backoff properties. Jobs will retry indefinitely on failure without these. |
Minor |
FWK |
Events |
Tight coupling where events would decouple |
After a state change (create, update, delete), a method directly calls 3+ other services. Should dispatch an event and let listeners handle side effects. |
Minor |
FWK |
Config |
env() called outside config files |
Using env() helper directly in service classes, controllers, or blade templates. env() returns null when config is cached. Must be wrapped in a config/ file. |
Major |
React / Next.js
| ID Prefix |
Area |
What to Detect |
How to Detect |
Severity |
FWK |
Components |
Components exceeding 200 LOC |
Single component files with more than 200 lines of code. Should be decomposed into smaller, focused components. |
Minor |
FWK |
Components |
Prop drilling more than 3 levels deep |
Props passed through 3+ intermediate components that don't use them. Should use Context, state management, or composition. Trace prop names through component hierarchy. |
Minor |
FWK |
Hooks |
useEffect with missing or incorrect dependency array |
useEffect hooks where variables used inside the effect are not listed in the dependency array. Also flag useEffect with empty [] that references props/state that can change. |
Major |
FWK |
Hooks |
State updates inside render |
Calling setState/state setter outside of event handlers or effects — directly in the component body during render, causing infinite re-render loops. |
Major |
FWK |
Hooks |
Custom hooks exceeding 50 LOC |
Custom hooks that do too much. Should be composed from smaller hooks. |
Minor |
FWK |
Data Fetching |
Client-side fetch where SSR/SSG is appropriate |
useEffect + fetch() for data that is available at build time or request time. In Next.js, should use getServerSideProps, getStaticProps, or server components. |
Minor |
FWK |
Data Fetching |
Missing error and loading states |
Data fetching without corresponding loading indicator and error handling in the UI. |
Minor |
FWK |
Type Safety |
any type usage in TypeScript |
Explicit any type annotations in .tsx/.ts files. Should use proper types, unknown, or generics. |
Minor |
FWK |
Type Safety |
Missing return types on exported functions |
Exported functions without explicit return type annotations. Rely on inference for internal, but exported API surfaces should be explicitly typed. |
Minor |
Python / Django / FastAPI
| ID Prefix |
Area |
What to Detect |
How to Detect |
Severity |
FWK |
Django |
views.py exceeding 500 LOC |
Single view module with too many views. Should be split into separate view modules or use ViewSets. |
Minor |
FWK |
Django |
Missing model Meta class |
Django models without Meta class for ordering, verbose names, or constraints. |
Minor |
FWK |
Django |
N+1 in templates |
Template tags accessing related objects without select_related()/prefetch_related() in the view. |
Major |
FWK |
FastAPI |
Sync database calls in async views |
Using synchronous ORM calls (Django ORM, SQLAlchemy sync) inside async def view functions. Blocks the event loop. |
Major |
FWK |
Python |
Non-PEP 8 naming |
camelCase for functions/variables (should be snake_case), snake_case for classes (should be PascalCase). |
Minor |
ID Prefix & Fix Prompt Examples
All findings use the FWK- prefix, numbered sequentially: FWK-001, FWK-002, etc.
Fix Prompt Examples
- "Move the validation rules from
OrderController@store (lines 15-30) into a new StoreOrderRequest form request class: run php artisan make:request StoreOrderRequest, move the validation array, and type-hint StoreOrderRequest in the controller method signature."
- "Replace the
env('MAIL_HOST') call at line 12 of app/Services/MailService.php with config('mail.mailers.smtp.host'). The env() function returns null when the config is cached. Move the env lookup to config/mail.php where it belongs."
- "The
ProductList component at src/components/ProductList.tsx (220 LOC) should be decomposed: extract ProductCard (lines 50-90), ProductFilters (lines 100-140), and ProductPagination (lines 160-200) into separate components in the same directory."
- "Add missing dependency
userId to the useEffect dependency array at src/hooks/useProfile.ts:15. The current empty array [] means the effect runs once with the initial userId and never refetches when it changes."
1---2name: codeprobe-framework3description: Detects framework-specific anti-patterns, convention violations, and idiom misuse across PHP/Laravel, React/Next.js, and Python/Django/FastAPI codebases. Loads framework-specific reference guides and checks against framework conventions. Generates severity-scored findings with copy-pasteable fix prompts. Trigger phrases: "framework review", "framework check", "laravel best practices", "react best practices", "framework audit", "framework-specific review".4---56## Standalone Mode78If invoked directly (not via the orchestrator), you must first:91. Read `../codeprobe/shared-preamble.md` (resolve relative to this SKILL.md's location — the sibling `codeprobe` skill directory — not the user's project) for the output contract, execution modes, and constraints.102. Load applicable reference files from `../codeprobe/references/` (same resolution) based on the project's tech stack.113. Default to `full` mode unless the user specifies otherwise.1213# Framework-Specific Best Practices1415## Domain Scope1617This sub-skill detects framework-specific anti-patterns and convention violations. Unlike other sub-skills that apply universal principles, this one loads framework-specific reference guides and checks against framework idioms.1819**Supported frameworks:**20211. **PHP / Laravel** — Eloquent ORM, routing, validation, queues, events, configuration222. **React / Next.js** — Component design, hooks, data fetching, type safety233. **Python / Django / FastAPI** — PEP conventions, ORM patterns, async handling2425**Important:** If no supported framework is detected at the target path, emit zero findings and return an empty summary with a note: "No supported framework detected — skipping framework-specific checks."2627**Version Awareness:** When checking framework conventions, attempt to determine the framework version:2829- **Laravel:** check `composer.json` for `laravel/framework` version. Laravel 9+ uses attribute-based accessors instead of `getXAttribute()`.30- **Next.js:** check `next.config.*` and `package.json` for Next.js version. 13+ uses App Router with `app/` directory.31- **Django:** check `requirements.txt` or `setup.py` for Django version.3233---3435## What It Does NOT Flag3637- **Issues already covered by other sub-skills** even if they appear in framework code. Specifically:38 - Security issues in framework code → covered by `codeprobe-security` (SEC)39 - SOLID violations in framework classes → covered by `codeprobe-solid` (SRP/OCP/etc.)40 - Performance issues like N+1 queries → covered by `codeprobe-performance` (PERF)41 - Error handling in framework middleware → covered by `codeprobe-error-handling` (ERR)42- This sub-skill focuses exclusively on **framework idiom violations** — using the framework incorrectly or ignoring its conventions.43- When this sub-skill and another sub-skill flag the same file:line range, the orchestrator's deduplication step (Section 7A) will keep the finding in whichever category is most relevant and mark the framework finding as a duplicate.44- **Framework-generated boilerplate files** (migration stubs, config defaults, scaffolded controllers).45- **Intentional deviations** from framework conventions with clear comments explaining the reason.46- **Test files** — test-specific framework usage has different conventions.4748---4950## Detection Instructions5152### PHP / Laravel5354| ID Prefix | Area | What to Detect | How to Detect | Severity |55|-----------|------|----------------|---------------|----------|56| `FWK` | Eloquent | Raw queries where Eloquent query builder works | Search for `DB::select()`, `DB::statement()`, raw SQL strings in model/service code where Eloquent's query builder (`where()`, `join()`, `whereHas()`) would be cleaner and safer. Exclude complex reporting queries that genuinely need raw SQL. | Minor |57| `FWK` | Eloquent | Missing `$casts` on model | Model attributes that should be cast (dates, booleans, arrays, JSON) accessed without `$casts` definition. Look for manual casting in accessors or repeated `(bool)`, `(int)`, `json_decode()` on model attributes. | Minor |58| `FWK` | Eloquent | Repeated WHERE conditions without scopes | Same `where()` condition chain used in 3+ locations on the same model. Should be extracted into a named scope (`scopeActive()`, `scopePublished()`). | Minor |59| `FWK` | Routing | Logic in route closures instead of controllers | Route definitions in `routes/web.php` or `routes/api.php` with closure handlers exceeding 3 lines. Should be moved to controller methods. | Minor |60| `FWK` | Routing | Missing route model binding | Routes that accept an ID parameter and manually call `Model::find($id)` or `Model::findOrFail($id)` instead of using route model binding in the method signature. | Minor |61| `FWK` | Validation | Validation in controller instead of Form Request | Controller methods with inline validation rules (`$request->validate([...])` exceeding 5 rules). Should use a dedicated Form Request class. | Minor |62| `FWK` | Queues | Long-running tasks in request cycle | Operations likely to take > 5 seconds (sending emails, generating PDFs, calling external APIs, processing uploads) executed synchronously in a controller/request handler. Should be dispatched to a queue. | Major |63| `FWK` | Queues | Queue jobs without retry configuration | Job classes missing `$tries`, `$timeout`, or `$backoff` properties. Jobs will retry indefinitely on failure without these. | Minor |64| `FWK` | Events | Tight coupling where events would decouple | After a state change (create, update, delete), a method directly calls 3+ other services. Should dispatch an event and let listeners handle side effects. | Minor |65| `FWK` | Config | `env()` called outside config files | Using `env()` helper directly in service classes, controllers, or blade templates. `env()` returns `null` when config is cached. Must be wrapped in a `config/` file. | Major |6667### React / Next.js6869| ID Prefix | Area | What to Detect | How to Detect | Severity |70|-----------|------|----------------|---------------|----------|71| `FWK` | Components | Components exceeding 200 LOC | Single component files with more than 200 lines of code. Should be decomposed into smaller, focused components. | Minor |72| `FWK` | Components | Prop drilling more than 3 levels deep | Props passed through 3+ intermediate components that don't use them. Should use Context, state management, or composition. Trace prop names through component hierarchy. | Minor |73| `FWK` | Hooks | `useEffect` with missing or incorrect dependency array | `useEffect` hooks where variables used inside the effect are not listed in the dependency array. Also flag `useEffect` with empty `[]` that references props/state that can change. | Major |74| `FWK` | Hooks | State updates inside render | Calling `setState`/state setter outside of event handlers or effects — directly in the component body during render, causing infinite re-render loops. | Major |75| `FWK` | Hooks | Custom hooks exceeding 50 LOC | Custom hooks that do too much. Should be composed from smaller hooks. | Minor |76| `FWK` | Data Fetching | Client-side fetch where SSR/SSG is appropriate | `useEffect` + `fetch()` for data that is available at build time or request time. In Next.js, should use `getServerSideProps`, `getStaticProps`, or server components. | Minor |77| `FWK` | Data Fetching | Missing error and loading states | Data fetching without corresponding loading indicator and error handling in the UI. | Minor |78| `FWK` | Type Safety | `any` type usage in TypeScript | Explicit `any` type annotations in `.tsx`/`.ts` files. Should use proper types, `unknown`, or generics. | Minor |79| `FWK` | Type Safety | Missing return types on exported functions | Exported functions without explicit return type annotations. Rely on inference for internal, but exported API surfaces should be explicitly typed. | Minor |8081### Python / Django / FastAPI8283| ID Prefix | Area | What to Detect | How to Detect | Severity |84|-----------|------|----------------|---------------|----------|85| `FWK` | Django | `views.py` exceeding 500 LOC | Single view module with too many views. Should be split into separate view modules or use ViewSets. | Minor |86| `FWK` | Django | Missing model `Meta` class | Django models without `Meta` class for ordering, verbose names, or constraints. | Minor |87| `FWK` | Django | N+1 in templates | Template tags accessing related objects without `select_related()`/`prefetch_related()` in the view. | Major |88| `FWK` | FastAPI | Sync database calls in async views | Using synchronous ORM calls (Django ORM, SQLAlchemy sync) inside `async def` view functions. Blocks the event loop. | Major |89| `FWK` | Python | Non-PEP 8 naming | `camelCase` for functions/variables (should be `snake_case`), `snake_case` for classes (should be `PascalCase`). | Minor |9091---9293## ID Prefix & Fix Prompt Examples9495All findings use the `FWK-` prefix, numbered sequentially: `FWK-001`, `FWK-002`, etc.9697### Fix Prompt Examples9899- "Move the validation rules from `OrderController@store` (lines 15-30) into a new `StoreOrderRequest` form request class: run `php artisan make:request StoreOrderRequest`, move the validation array, and type-hint `StoreOrderRequest` in the controller method signature."100- "Replace the `env('MAIL_HOST')` call at line 12 of `app/Services/MailService.php` with `config('mail.mailers.smtp.host')`. The `env()` function returns `null` when the config is cached. Move the env lookup to `config/mail.php` where it belongs."101- "The `ProductList` component at `src/components/ProductList.tsx` (220 LOC) should be decomposed: extract `ProductCard` (lines 50-90), `ProductFilters` (lines 100-140), and `ProductPagination` (lines 160-200) into separate components in the same directory."102- "Add missing dependency `userId` to the `useEffect` dependency array at `src/hooks/useProfile.ts:15`. The current empty array `[]` means the effect runs once with the initial `userId` and never refetches when it changes."
nishilbhave