@use-the-fork/spindle 0.0.0-stage → 0.0.1

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/naming-generic-placeholders.md

@@ -0,0 +1,120 @@
+---
+title: Generic Placeholder Names
+impact: CRITICAL
+impactDescription: "Reduces every variable to 'a thing' — kills the most powerful form of self-documentation"
+tags: naming, generic-names, ai-fingerprint
+---
+
+## Generic Placeholder Names
+
+**Impact: CRITICAL (Reduces every variable to 'a thing' — kills the most powerful form of self-documentation)**
+
+`data`, `result`, `info`, `temp`, `value`, `item`, `helper`, `manager`, `utils` — these are the names a model picks when it doesn't know what the value represents in the domain. They pass linters, type checks, every metric. They cost the reader real attention to track ("which `data` is this?").
+
+Names are the cheapest, highest-leverage form of self-documentation in any codebase. A model that names every intermediate variable `data` or `result` is signalling it didn't think about the domain.
+
+## Incorrect
+
+```php
+// ❌ Every variable is generic
+
+public function exportUsers(): Collection
+{
+    $data = User::all();
+
+    $result = [];
+    foreach ($data as $item) {
+        $info = [
+            'name' => $item->name,
+            'email' => $item->email,
+        ];
+        $result[] = $info;
+    }
+
+    return collect($result);
+}
+```
+
+```typescript
+// ❌ Same pattern
+async function fetchOrders(userId: string) {
+  const data = await api.getOrders(userId);
+  const result = data.map((item) => {
+    const info = {
+      id: item.id,
+      total: item.total,
+    };
+    return info;
+  });
+  return result;
+}
+```
+
+**Why it's slop:**
+
+- Every variable is "a thing"; reader has no anchor to the domain
+- `$item` inside a loop over `$data` is doubly opaque — what kind of item? what kind of data?
+- A reader hitting line 50 of this file can't tell what `$result` holds without tracing the whole function
+- A human author who lived with this code would use domain words
+
+## Correct
+
+```php
+// ✅ Names tell you what the values are in the domain
+
+public function exportUsers(): Collection
+{
+    return User::all()
+        ->map(fn (User $user) => [
+            'name'  => $user->name,
+            'email' => $user->email,
+        ]);
+}
+```
+
+```typescript
+// ✅ Domain words everywhere
+async function fetchOrders(userId: string): Promise<OrderSummary[]> {
+  const orders = await api.getOrders(userId);
+  return orders.map((order) => ({
+    id: order.id,
+    total: order.total,
+  }));
+}
+```
+
+**Why it reads human:**
+
+- A reader on any line knows the domain object in scope
+- Domain names compose — `orders.map(order => …)` reads as a sentence
+- The original `$data → $item → $info → $result` chain collapses into one expression because the names made the intermediate variables unnecessary
+
+## When generic names ARE OK
+
+A handful of names are conventional, short-scope, and fine:
+
+- **`i`, `j`, `k`** — loop indices in a 3-line `for`
+- **`x`, `y`, `z`** — math/geometry (coordinates)
+- **`_`** — explicit "ignored value"
+- **`acc`** — accumulator in a `reduce` callback
+- **`prev`, `next`** — in middleware / chained handlers where they're language conventions
+- **`req`, `res`** — Express handlers (don't fight a framework convention)
+
+If the value flows through 5+ lines or escapes the immediate function, use a domain name.
+
+## Detection
+
+```bash
+# Bare local-variable declarations using generic names (PHP)
+grep -rEn '\$(data|result|info|temp|item|helper|value)\b' --include='*.php' app/ | wc -l
+
+# TS/JS — generic const/let
+grep -rEn '\b(const|let)\s+(data|result|info|temp|helper|value|item)\b' --include='*.ts' --include='*.tsx' --include='*.js' src/ | wc -l
+
+# Density signal: files with > 10 generic-name hits
+# (in a 200-line file, 10+ generic names is suspicious)
+```
+
+There's no fully automatic detector — judgment is required. The signal is **density**: a few are fine, a thicket is a slop fingerprint.
+
+Reference: [Clean Code (Robert C. Martin) — Chapter 2: Meaningful Names](https://www.oreilly.com/library/view/clean-code/9780136083238/) · Internal: [`naming-over-descriptive`](naming-over-descriptive.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/naming-over-descriptive.md

@@ -0,0 +1,108 @@
+---
+title: Over-Descriptive Run-On Names
+impact: HIGH
+impactDescription: "Inflated identifiers that read like English instead of code"
+tags: naming, verbose, ai-fingerprint
+---
+
+## Over-Descriptive Run-On Names
+
+**Impact: HIGH (Inflated identifiers that read like English instead of code)**
+
+The opposite failure mode of generic names: instead of `user`, the AI produces `theUserWhoIsCurrentlyLoggedIn`. Instead of `total`, `calculateTotalAmountFromItemsList`. The identifier becomes a sentence. Real engineers know that _context_ (function scope, parameter types, surrounding code) carries half the meaning — you don't need to encode all of it in every variable name.
+
+A name should be **as long as needed and no longer**. Once context establishes "we're inside `processOrder`", calling the order variable `order` is fine. Calling it `theOrderThatIsCurrentlyBeingProcessed` is slop.
+
+## Incorrect
+
+```php
+// ❌ Identifiers read as English
+
+public function processOrderForCheckout(
+    OrderThatIsCurrentlyBeingProcessed $theOrderToProcess
+): ProcessingResultObjectContainingStatus {
+    $theCurrentlyLoggedInUserWhoIsCheckingOut = $theOrderToProcess->getUserWhoPlacedTheOrder();
+    $theTotalAmountThatNeedsToBeCharged = $this->calculateTotalAmountFromItemsListInTheOrder($theOrderToProcess);
+
+    return new ProcessingResultObjectContainingStatus(
+        status: 'success',
+        amountThatWasCharged: $theTotalAmountThatNeedsToBeCharged,
+    );
+}
+```
+
+```typescript
+// ❌ Same in TS
+async function fetchTheUserDataObjectForTheUserWithTheGivenId(
+  theIdOfTheUserToFetch: string,
+): Promise<TheUserDataResponseObject> {
+  const theResponseFromTheAPI = await api.getUser(theIdOfTheUserToFetch);
+  return theResponseFromTheAPI;
+}
+```
+
+**Why it's slop:**
+
+- Function signatures span multiple lines because identifiers eat the line budget
+- Reader has to scan past redundant words ("theOrderToProcess" — yes, it's the parameter, of course we're processing it)
+- "The" prefix is meaningless — what else would it be?
+- Inflates token count without conveying anything new
+
+## Correct
+
+```php
+// ✅ Tight; context carries the obvious
+
+public function checkout(Order $order): ProcessingResult
+{
+    $user = $order->user;
+    $total = $this->totalFor($order);
+
+    return new ProcessingResult(status: 'success', charged: $total);
+}
+```
+
+```typescript
+// ✅ Tight TS
+async function fetchUser(id: string): Promise<User> {
+  return api.getUser(id);
+}
+```
+
+**Why it reads human:**
+
+- The function is named `checkout`; obviously the parameter is the order being checked out — no need to spell that out
+- Function fits on one line; reader takes it in at a glance
+- Domain words (`Order`, `User`, `ProcessingResult`) replace English sentences
+
+## Guidelines
+
+| Scope                    | Reasonable length                                                   |
+| ------------------------ | ------------------------------------------------------------------- |
+| Loop index               | 1 char (`i`)                                                        |
+| Block-local (< 10 lines) | 1 word (`user`, `total`)                                            |
+| Function-local           | 1–2 words (`pricedItems`, `taxedTotal`)                             |
+| Public API parameter     | 2–3 words when domain requires (`stripeChargeId`, `webhookPayload`) |
+| Constants / config keys  | Domain-precise (`MAX_STRIPE_AMOUNT_CENTS`) — those CAN be long      |
+| Class names              | 1–3 words (`OrderService`, `RefundCalculator`)                      |
+
+The rule of thumb: **if you can drop a word and meaning survives, drop it.**
+
+## Detection
+
+```bash
+# Identifiers with 4+ camelCase words (heuristic; tune to taste).
+# Note: grep -E (ERE) does NOT support (?:...) non-capturing groups; use a capturing group.
+grep -rEn '[a-z]+([A-Z][a-z]+){3,}' --include='*.ts' --include='*.tsx' --include='*.js' src/ \
+  | head -30
+
+# PHP equivalent (variables / method names)
+grep -rEn '\$[a-z][a-zA-Z]{20,}' --include='*.php' app/ | head -30
+grep -rEn 'function [a-z][a-zA-Z]{30,}\(' --include='*.php' app/ | head -30
+
+# Names starting with "the" — a strong AI tell
+grep -rEnH '\b(theUser|theOrder|theData|theResult|theItem|theCurrent)' \
+  --include='*.php' --include='*.ts' --include='*.tsx' app/ src/
+```
+
+Reference: [Clean Code — Chapter 2](https://www.oreilly.com/library/view/clean-code/9780136083238/) · Internal: [`naming-generic-placeholders`](naming-generic-placeholders.md) (the opposite failure mode)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/naming-suffix-abuse.md

@@ -0,0 +1,167 @@
+---
+title: Suffix Abuse — *Helper, *Manager, *Util, *Wrapper, *Processor
+impact: HIGH
+impactDescription: "Catch-all suffixes signal undecided design and pad code with empty abstractions"
+tags: naming, suffixes, ai-fingerprint, abstractions
+---
+
+## Suffix Abuse — *Helper,*Manager,*Util,*Wrapper,*Processor
+
+**Impact: HIGH (Catch-all suffixes signal undecided design and pad code with empty abstractions)**
+
+`UserHelper`, `OrderManager`, `DataUtil`, `RequestWrapper`, `PaymentProcessor` — these suffixes are the AI's go-to when it doesn't know what to call something. The suffix is non-information: every class is in some sense a "manager" or "helper" or "util". The name describes the noun-form of "code I had to put somewhere".
+
+When a model generates these, it's because:
+
+- The "Helper" class is doing things that belong on the model
+- The "Manager" is a procedural blob masquerading as a class
+- The "Util" is a kitchen sink that should be split or absorbed into domain types
+
+Real domain code uses domain names: `Pricing`, `RefundPolicy`, `WebhookVerifier` — not `PricingHelper`, `RefundManager`, `WebhookProcessor`.
+
+## Incorrect
+
+```php
+// ❌ Suffix abuse — every concern wrapped in *Helper or *Manager
+
+class UserHelper
+{
+    public function formatName(User $user): string {
+        return $user->firstName . ' ' . $user->lastName;
+    }
+}
+
+class OrderManager
+{
+    public function processOrder(Order $order): void {
+        // ...
+    }
+}
+
+class PaymentProcessor
+{
+    public function processPayment(Order $order, string $token): Charge {
+        // ...
+    }
+}
+
+class DataUtil
+{
+    public static function arrayToCsv(array $rows): string { /* ... */ }
+    public static function csvToArray(string $csv): array { /* ... */ }
+    public static function snakeToCamel(string $s): string { /* ... */ }
+    public static function camelToSnake(string $s): string { /* ... */ }
+    // …grows forever
+}
+```
+
+```typescript
+// ❌ Same TS pattern
+class StringHelper {
+  static capitalize(s: string): string {
+    /* ... */
+  }
+  static slugify(s: string): string {
+    /* ... */
+  }
+}
+
+class ResponseWrapper {
+  constructor(private res: ApiResponse) {}
+  getData() {
+    return this.res.data;
+  }
+}
+```
+
+**Why it's slop:**
+
+- `UserHelper.formatName(user)` could just be `user.fullName` on the User model
+- `OrderManager.processOrder(order)` is two ways of saying the same thing
+- `DataUtil` is a kitchen sink — every utility ends up here, none have a clear home
+- The suffix doesn't add information; it admits the author didn't decide what the class is
+
+## Correct
+
+```php
+// ✅ Behavior lives on the domain type; helpers split by concern
+
+class User extends Model
+{
+    public function getFullNameAttribute(): string
+    {
+        return "{$this->firstName} {$this->lastName}";
+    }
+}
+
+// Action class — replaces "OrderManager.processOrder"
+final class PlaceOrder
+{
+    public function __invoke(Order $order, PaymentIntent $payment): void { /* ... */ }
+}
+
+// Domain class with a clear single responsibility — replaces "PaymentProcessor"
+final class StripePaymentGateway implements PaymentGateway
+{
+    public function charge(Money $amount, string $token): Charge { /* ... */ }
+}
+
+// CSV becomes its own type — replaces the kitchen-sink DataUtil
+final class CsvExporter
+{
+    public function export(iterable $rows, array $headers): string { /* ... */ }
+}
+```
+
+```typescript
+// ✅ Methods on the domain type, or named domain functions
+class User {
+  get fullName(): string {
+    return `${this.firstName} ${this.lastName}`;
+  }
+}
+
+// Free function — capitalize doesn't need a class wrapper
+export function capitalize(s: string): string {
+  /* ... */
+}
+export function slugify(s: string): string {
+  /* ... */
+}
+```
+
+**Why it reads human:**
+
+- Each class has a specific domain responsibility (CsvExporter exports CSVs; PlaceOrder places orders)
+- Behavior-on-data is on the type that holds the data (`user.fullName`)
+- Free functions stand on their own when there's no state to wrap
+
+## When suffixes ARE okay
+
+A handful of suffixes carry real meaning in their conventions:
+
+- **`*Repository`** — DDD-style data access (specific contract)
+- **`*Service`** — used sparingly for orchestration that doesn't fit on a domain type
+- **`*Controller`** — HTTP entry point (Laravel/Express convention)
+- **`*Middleware`** — request pipeline (Express/Laravel convention)
+- **`*Gateway`** — external integration boundary (Stripe, AWS)
+- **`*Listener`** / `*Observer` — event-handler conventions (Laravel)
+
+`*Helper`, `*Manager`, `*Util`, `*Wrapper`, `*Processor` are the suspect tier.
+
+## Detection
+
+```bash
+# Class declarations with suspect suffixes
+grep -rEn 'class\s+[A-Z][a-zA-Z]*(Helper|Manager|Util|Utils|Wrapper|Processor|Handler)\b' \
+  --include='*.php' --include='*.ts' --include='*.tsx' app/ src/
+
+# Count by suffix to size the problem
+grep -rE 'class\s+[A-Z][a-zA-Z]*' --include='*.php' --include='*.ts' app/ src/ \
+  | grep -oE '(Helper|Manager|Util|Utils|Wrapper|Processor)\b' \
+  | sort | uniq -c | sort -rn
+```
+
+A repo with **5+ `*Helper`** or **3+ `*Manager`** classes is almost certainly leaking domain logic into catch-all classes. Refactor by asking "what would I call this if I couldn't use the suffix?"
+
+Reference: [Clean Code — Chapter 2: Meaningful Names](https://www.oreilly.com/library/view/clean-code/9780136083238/) · Internal: [`over-eng-single-method-class`](over-eng-single-method-class.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/naming-type-in-name.md

@@ -0,0 +1,100 @@
+---
+title: Type Encoded in Variable Names
+impact: MEDIUM
+impactDescription: "Embeds type in the identifier when the type system already does it; ages badly with refactors"
+tags: naming, hungarian, type-in-name, ai-fingerprint
+---
+
+## Type Encoded in Variable Names
+
+**Impact: MEDIUM (Embeds type in the identifier when the type system already does it; ages badly with refactors)**
+
+`userObject`, `resultArray`, `stringData`, `listOfItems`, `userIdString`, `dataMap` — these names encode the _type_ of the value, redundantly with the actual type declaration. Both PHP 8+ and TypeScript have rich type systems that show the type in the signature. The name should encode what the value **means**, not what its shape is.
+
+The pattern is a tell because it suggests the author optimised for "obvious from any one line" rather than "obvious in context". A human author trusts the reader to look at the signature.
+
+## Incorrect
+
+```php
+// ❌ Type-in-name everywhere
+
+public function processItemsList(array $itemsArray, int $userIdInteger): array
+{
+    $resultArray = [];
+    foreach ($itemsArray as $itemObject) {
+        $priceFloat = $itemObject->priceFloat;
+        $resultArray[] = $priceFloat;
+    }
+    return $resultArray;
+}
+```
+
+```typescript
+// ❌ Same in TS
+function getUserDataObject(userIdString: string): UserDataResponseObject {
+  const responseObject = await api.fetch(userIdString);
+  const dataArray = responseObject.dataArray;
+  const userObjectList = dataArray.map((itemObject: UserObject) => itemObject);
+  return userObjectList;
+}
+```
+
+**Why it's slop:**
+
+- The type is declared on the parameter and visible in the signature
+- Renaming `$itemsArray` to a `Collection` requires updating every variable reference
+- The name `$itemObject` is redundant — the static type says it's a `User`
+- Pattern is a clear "tutorial-blog" signature; teammates don't write like this
+
+## Correct
+
+```php
+// ✅ Names encode meaning, not shape
+
+public function totalsFor(array $items, int $userId): array
+{
+    return array_map(fn (Item $item) => $item->price, $items);
+}
+```
+
+```typescript
+// ✅ Domain words, types in the signature
+async function fetchUser(userId: string): Promise<User> {
+  const { data } = await api.fetch(userId);
+  return data;
+}
+```
+
+**Why it reads human:**
+
+- Each name describes the role (`items`, `userId`, `total`) not the shape
+- Type info is in the type system, where refactors update it automatically
+- If `items` becomes a `Collection<Item>`, the variable name still reads correctly
+
+## When type-in-name IS okay
+
+Conventions where the type is part of the meaning:
+
+- **`*Id`** suffix — `userId` (distinguishes from `user` which is the whole object) ✓
+- **`*Count`** suffix — `userCount` ✓
+- **`is*`** / **`has*`** / **`can*`** booleans — `isPaid`, `hasShipping`, `canEdit` ✓
+- **Maps with two-type names** — `usersByEmail` (carries both types in one word) ✓
+- **DTO classes** — `UserResponse`, `OrderPayload` (clarifies "this is the wire form, not the domain model") ✓
+
+The suspect patterns are `*Object`, `*Array`, `*List`, `*Map`, `*String`, `*Integer`, `*Float` on local variables.
+
+## Detection
+
+```bash
+# Suspect type-suffix names on variables (PHP)
+grep -rEn '\$[a-z][a-zA-Z]*?(Object|Array|List|Map|String|Integer|Float|Boolean|Bool)\b' \
+  --include='*.php' app/
+
+# TS / JS
+grep -rEn '\b(const|let)\s+[a-z][a-zA-Z]*?(Object|Array|List|Map|String|Boolean)\b' \
+  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' src/
+```
+
+A few hits are fine (especially in test data setups). **Density across multiple files** is the signal — a project with 30+ `*Array` / `*Object` variables almost certainly came from a model.
+
+Reference: [Clean Code — Chapter 2](https://www.oreilly.com/library/view/clean-code/9780136083238/) · [Joel Spolsky — Making Wrong Code Look Wrong](https://www.joelonsoftware.com/2005/05/11/making-wrong-code-look-wrong/) (the "useful Hungarian" original — different from this rule's anti-pattern) · Internal: [`naming-over-descriptive`](naming-over-descriptive.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/over-eng-dependency-creep.md

@@ -0,0 +1,114 @@
+---
+title: Dependency Creep — New Library When Existing One Suffices
+impact: HIGH
+impactDescription: "Inflates bundle/install size, adds CVE surface, signals model picked training-data favourites"
+tags: over-engineering, dependencies, dependency-creep, ai-fingerprint
+---
+
+## Dependency Creep — New Library When Existing One Suffices
+
+**Impact: HIGH (Inflates bundle/install size, adds CVE surface, signals model picked training-data favourites)**
+
+AI tends to introduce a new dependency whenever a problem matches a library it has seen in training, even when the project already includes a dependency that solves the same problem. Example signals:
+
+- Adding `date-fns` to a project that already uses `dayjs`
+- Adding `axios` to a project that already imports `fetch` everywhere
+- Adding `lodash` to a project that already has `lodash-es` (or uses native ES methods)
+- Adding `uuid` when the project already uses `nanoid`
+- Adding `winston` when the app uses `pino`
+- Adding `joi` / `yup` to a TS project that already uses `zod`
+- Adding `bcrypt` (the npm package) in a Laravel project where `Hash::make` handles it
+- Adding `moment` in a project that just removed `moment` last quarter
+
+Each new dependency:
+
+- Adds to install / bundle size
+- Adds a new CVE surface (every `npm audit` lights up)
+- Forces the team to maintain TWO libraries for the same concern, indefinitely
+- Drifts as the LLM picks whichever was popular in the training-data slice it sampled from
+
+## Incorrect
+
+```json
+// ❌ package.json — two libs doing the same job
+{
+  "dependencies": {
+    "dayjs": "^1.11.10", // already in use
+    "date-fns": "^3.0.0", // ADDED — same purpose
+    "axios": "^1.6.0", // ADDED — but app uses fetch everywhere
+    "lodash": "^4.17.21", // ADDED — lodash-es already present
+    "lodash-es": "^4.17.21"
+  }
+}
+```
+
+```php
+// ❌ composer.json — two HTTP clients
+{
+  "require": {
+    "guzzlehttp/guzzle": "^7.8",
+    "symfony/http-client": "^7.0"          // ADDED — same purpose
+  }
+}
+```
+
+**Why it's slop:**
+
+- Both libraries get pulled into every install
+- New `dayjs` code still gets written alongside the new `date-fns` code — drift forever
+- Two CVE feeds to track
+- Reviewer didn't notice because each PR seems reasonable in isolation
+
+## Correct
+
+```bash
+# ✅ Use the existing dep; reject the PR adding the new one with a note
+
+# Before merging a PR that adds a new dependency, ask:
+#  1. Does an existing dependency in package.json/composer.json already do this?
+#  2. Does a native browser/Node/PHP API already do this?
+#  3. Is the new dep > 50KB gzipped (or > 1MB unpacked) for a single function call?
+#  4. Does it have CVEs / abandoned upstream?
+#
+# If any answer is "yes" or "maybe", reject and use the existing tool.
+```
+
+Common collisions and the canonical choice:
+
+| Concern                   | Pick one                                                                                 |
+| ------------------------- | ---------------------------------------------------------------------------------------- |
+| Date / time               | `dayjs` OR `date-fns` (not both)                                                         |
+| HTTP client               | `fetch` OR `axios` (not both)                                                            |
+| UUID                      | `uuid` OR `nanoid` (not both)                                                            |
+| Schema validation (TS)    | `zod` (preferred) — reject `joi`/`yup`/`ajv` additions                                   |
+| HTTP client (PHP)         | `guzzlehttp/guzzle` (Laravel default) — reject `symfony/http-client` unless project-wide |
+| Logging                   | `monolog` (Laravel default) for PHP; pick one of `pino`/`winston` for Node               |
+| Form validation (Laravel) | Built-in `FormRequest` — reject standalone validation libs                               |
+
+## Detection
+
+```bash
+# Node: dependency-list audit
+node -e "
+const pkg = require('./package.json');
+const all = { ...pkg.dependencies, ...pkg.devDependencies };
+const dupes = [
+  ['dayjs', 'date-fns', 'moment', 'luxon'],
+  ['axios', 'node-fetch', 'got', 'superagent'],
+  ['uuid', 'nanoid', 'cuid'],
+  ['lodash', 'lodash-es', 'ramda'],
+  ['joi', 'yup', 'zod', 'ajv'],
+];
+for (const group of dupes) {
+  const found = group.filter(p => all[p]);
+  if (found.length > 1) console.log('OVERLAP:', found.join(', '));
+}
+"
+
+# PHP: check for HTTP-client overlap
+grep -E '\"(guzzlehttp/guzzle|symfony/http-client|kriswallsmith/buzz)\"' composer.json
+```
+
+When a new dep lands in a PR, the PR author should justify why the existing options don't fit. "AI suggested this" is not a justification.
+
+Reference: [`technical-debt`'s `deps-unused-deps`](../technical-debt/rules/deps-unused-deps.md) (the broader audit) · [BundlePhobia](https://bundlephobia.com/) (size impact for npm packages)