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

package/build/Assets/Blueprints/skills/int-code-slop-review/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: int-code-slop-review
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.0.0
+---
+
+# Code-Slop Review
+
+Review a specific code change for avoidable complexity that makes the implementation harder to understand, change, or trust. This is a focused maintainability review, not a general correctness or style review.
+
+## How to Audit
+
+Run through this skill's rules as a checklist against the changed files (PR diff) or full repo.
+
+### Audit Step 1: Determine Scope
+
+- If a PR diff is provided: audit only files changed in the diff
+- If files are named: audit those
+- If no scope: audit the whole repo, prioritized by recently-touched files (most likely AI output)
+
+### Audit Step 2: Detect Stack
+
+| Signal                                      | Stack                     |
+| ------------------------------------------- | ------------------------- |
+| `composer.json` + `artisan`                 | PHP / Laravel             |
+| `package.json` (with TypeScript/React deps) | Node / TypeScript / React |
+| Both present                                | Laravel + Inertia + React |
+
+### Audit Step 3: Run the Slop Checklist
+
+For each item below, output:
+
+- **CLEAN** — pattern not present (brief confirmation)
+- **SUSPICIOUS** — present in small amounts; flag and discuss
+- **INFLATED** — present extensively; verbose-but-functional; remediation recommended
+- **CRITICAL** — extensive AI-fingerprint presence; full review needed before merge
+
+#### Comments
+
+- [ ] No comments that just narrate the code (`// create user` above `User::create(...)`)
+- [ ] No empty docblocks (`/** Get user */` above `getUser()`)
+- [ ] No placeholder comments left in (`// TODO: implement`, `// your code here`, `// implementation`)
+- [ ] No closing-brace labels (`} // end function`, `} // end if block`)
+
+#### Naming
+
+- [ ] No generic placeholder names (`data`, `result`, `info`, `temp`, `helper`)
+- [ ] No over-descriptive run-on names (`theUserWhoIsCurrentlyLoggedIn`)
+- [ ] No suffix abuse (`*Helper` / `*Manager` / `*Util` / `*Wrapper` overused without justification)
+- [ ] No type-in-name patterns (`userObject`, `resultArray`, `stringData`)
+
+#### Over-engineering
+
+- [ ] No interfaces with exactly one implementation (and no plan for a second)
+- [ ] No single-method classes that should be top-level functions
+- [ ] No wrapper functions called once that just delegate
+- [ ] No new dependency added when an existing one does the same job
+
+#### Defensive overdose
+
+- [ ] No generic `catch (e) { console.error(...) }` blocks around code that can't throw
+- [ ] No null checks for impossible nulls (after non-null assertions / type-guaranteed values)
+- [ ] Real defensive concerns (timeouts on external calls, rate limits) ARE present
+
+#### Test slop
+
+- [ ] No tests that mock every dependency with no real behavioural assertion
+- [ ] No "doesn't throw" tests that just call and check for exceptions
+- [ ] No tests that mirror the implementation's logic (re-encoding rather than verifying)
+- [ ] No snapshot tests standing in for behavioural assertions
+
+#### Style fingerprints
+
+- [ ] Some formatting drift exists (no codebase looks like every file ran through the most aggressive linter)
+- [ ] No `as any` / `@ts-ignore` / `@ts-expect-error` sprinkled where inference is hard
+- [ ] Repo has some `// HACK:` / `// XXX:` / 2am comments somewhere — codebases without scars are suspect
+- [ ] No debug artifacts (`console.log`, `var_dump`, `dd()`, `dump()`) left in production code
+- [ ] No `if (x) return true; else return false` / redundant type annotations on obvious literals
+
+### Audit Step 4: Build the Slop Ledger
+
+End the audit with a verdict table:
+
+```
+## Code Slop Ledger
+
+| File | Verdict | Top findings | Suggested action |
+|------|---------|--------------|------------------|
+| app/Services/UserExportService.php | INFLATED | 12 narration comments; 3 closing-brace labels; `*Helper` overuse | Strip comments; rename Helper → split into functions |
+| resources/js/Pages/Orders/Show.tsx | CRITICAL | 4 `as any`; mock-everything tests; useless wrapper; impossible null checks | Rewrite section; remove tests; revisit type model |
+| app/Models/Order.php | CLEAN | — | — |
+
+## Summary
+- CLEAN: X files
+- SUSPICIOUS: Y files
+- INFLATED: Z files (top priority: …)
+- CRITICAL: N files (rewrite before merge)
+```
+
+## When to Apply
+
+Reference this skill when:
+
+- Reviewing an AI-assisted PR before merge
+- Auditing a repo that has accepted heavy AI-assisted contributions
+- Onboarding a codebase and assessing whether it reads as human-maintained
+- Hardening a team's code-review checklist against AI slop
+- After a "vibe coding" sprint, before declaring features done
+- Setting up CI gates for AI-output quality
+
+## Step 1: Detect Project Stack
+
+Most rules are stack-agnostic in concept, but examples and detection commands differ between PHP and TypeScript.
+
+| Signal          | Stack             | Tooling                                                    |
+| --------------- | ----------------- | ---------------------------------------------------------- |
+| `composer.json` | PHP / Laravel     | `mago lint`, `mago analyze`, `phpcs`, `phpmd`, manual grep |
+| `package.json`  | Node / TS / React | `oxlint`, `tsc --noEmit`, `knip`, manual grep              |
+
+## Rule Categories by Priority
+
+| Priority | Category           | Impact   | Prefix       |
+| -------- | ------------------ | -------- | ------------ |
+| 1        | Comments           | CRITICAL | `comments-`  |
+| 2        | Naming             | CRITICAL | `naming-`    |
+| 3        | Over-engineering   | HIGH     | `over-eng-`  |
+| 4        | Defensive overdose | HIGH     | `defensive-` |
+| 5        | Test slop          | HIGH     | `test-`      |
+| 6        | Style fingerprints | MEDIUM   | `style-`     |
+
+## Quick Reference
+
+### 1. Comments (CRITICAL)
+
+- `comments-narration` — Comments that just restate the code on the next line
+- `comments-empty-docblocks` — Generic `/** Get the user */` over a typed `getUser()` signature
+- `comments-placeholder` — `// TODO: implement`, `// your code here`, `// implementation`, `// helper function`
+- `comments-closing-brace-labels` — `} // end function` / `} // end if block`
+
+### 2. Naming (CRITICAL)
+
+- `naming-generic-placeholders` — `data`, `result`, `info`, `temp`, `helper`, `value`
+- `naming-over-descriptive` — `theUserWhoIsCurrentlyLoggedIn`, `calculateTotalAmountFromItemsList`
+- `naming-suffix-abuse` — `*Helper` / `*Manager` / `*Util` / `*Wrapper` / `*Processor` overused
+- `naming-type-in-name` — `userObject`, `resultArray`, `stringData`, `listOfItems`
+
+### 3. Over-engineering (HIGH)
+
+- `over-eng-premature-interface` — Interface with exactly one implementation and no second on the roadmap
+- `over-eng-single-method-class` — Classes that exist solely to wrap one function
+- `over-eng-useless-wrapper` — Wrapper called from exactly one place, just delegating
+- `over-eng-dependency-creep` — New library when an existing dep already does the job
+
+### 4. Defensive overdose (HIGH)
+
+- `defensive-generic-catch` — `try { ... } catch (e) { console.error("error") }` everywhere
+- `defensive-impossible-null` — Null checks after non-null assertions / type-guaranteed values
+- `defensive-missing-real` — Defensive in the wrong places; missing timeouts/rate-limits where it matters
+
+### 5. Test slop (HIGH)
+
+- `test-mock-everything` — Mock for every dep; the test re-encodes the implementation, not the behaviour
+- `test-doesnt-throw` — Tests that just call the function and assert no exception
+- `test-mirror-implementation` — Tests whose logic mirrors the production code being tested
+- `test-snapshot-abuse` — Snapshot tests replacing behavioural assertions
+
+### 6. Style fingerprints (MEDIUM)
+
+- `style-hyper-consistent` — No formatting drift anywhere; every file looks linter-perfect
+- `style-as-any-escape` — `as any` / `@ts-ignore` / `@ts-expect-error` sprinkled where types are hard
+- `style-no-hack-scars` — Codebase has zero `// HACK:` / `// XXX:` markers; no "geology"
+- `style-debug-artifacts` — `console.log`, `var_dump`, `dd()`, `dump()` left in production paths
+- `style-trivial-boilerplate` — `if (x) return true; else return false;`, redundant TS type annotations on obvious literals
+
+## Essential Patterns
+
+### The "would this pass code review?" filter
+
+For each code chunk, ask:
+
+1. **Could I cut a third of these comments and the code would be clearer?** → likely comment slop
+2. **Do the variable names tell me what they hold, or just what type they are?** → likely naming slop
+3. **Could this class be a function?** → likely over-engineering
+4. **Does this catch block actually handle anything, or just log?** → likely defensive overdose
+5. **Does this test fail if I break the function?** → if no, test slop
+6. **Are there any `// HACK:` / `// XXX:` markers in the diff?** → if no, suspicious for AI
+
+### Verdict bands (matched to AI-SLOP-Detector's scoring)
+
+| Verdict        | Meaning               | Action                       |
+| -------------- | --------------------- | ---------------------------- |
+| **CLEAN**      | < 5% of lines flagged | Ship                         |
+| **SUSPICIOUS** | 5–15% flagged         | Review changes one more time |
+| **INFLATED**   | 15–30% flagged        | Strip slop, split commits    |
+| **CRITICAL**   | > 30% flagged         | Rewrite section before merge |
+
+## How to Use
+
+Read individual rule files for detailed conventions and examples:
+
+- [comments-closing-brace-labels.md](rules/comments-closing-brace-labels.md)
+- [comments-empty-docblocks.md](rules/comments-empty-docblocks.md)
+- [comments-narration.md](rules/comments-narration.md)
+- [comments-placeholder.md](rules/comments-placeholder.md)
+- [defensive-generic-catch.md](rules/defensive-generic-catch.md)
+- [defensive-impossible-null.md](rules/defensive-impossible-null.md)
+- [defensive-missing-real.md](rules/defensive-missing-real.md)
+- [naming-generic-placeholders.md](rules/naming-generic-placeholders.md)
+- [naming-over-descriptive.md](rules/naming-over-descriptive.md)
+- [naming-suffix-abuse.md](rules/naming-suffix-abuse.md)
+- [naming-type-in-name.md](rules/naming-type-in-name.md)
+- [over-eng-dependency-creep.md](rules/over-eng-dependency-creep.md)
+- [over-eng-premature-interface.md](rules/over-eng-premature-interface.md)
+- [over-eng-single-method-class.md](rules/over-eng-single-method-class.md)
+- [over-eng-useless-wrapper.md](rules/over-eng-useless-wrapper.md)
+- [style-as-any-escape.md](rules/style-as-any-escape.md)
+- [style-debug-artifacts.md](rules/style-debug-artifacts.md)
+- [style-hyper-consistent.md](rules/style-hyper-consistent.md)
+- [style-no-hack-scars.md](rules/style-no-hack-scars.md)
+- [style-trivial-boilerplate.md](rules/style-trivial-boilerplate.md)
+- [test-doesnt-throw.md](rules/test-doesnt-throw.md)
+- [test-mirror-implementation.md](rules/test-mirror-implementation.md)
+- [test-mock-everything.md](rules/test-mock-everything.md)
+- [test-snapshot-abuse.md](rules/test-snapshot-abuse.md)
+
+Each rule file contains:
+
+- YAML frontmatter (title, impact, tags)
+- Brief explanation of why the pattern is AI-fingerprint
+- "Incorrect" example showing the slop
+- "Correct" example showing the human-equivalent
+- Detection guidance (grep / oxlint / mago / heuristic)
+- Reference link
+
+Supporting references: [section definitions](rules/_sections.md) and [rule template](rules/_template.md).

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/_sections.md

@@ -0,0 +1,36 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Comments (comments)
+
+**Impact:** CRITICAL
+**Description:** The single loudest AI tell. Models love to narrate the next line in the comment above it, write empty docblocks that restate the function signature, and leave placeholder comments like `// TODO: implement` long after the code shipped. Cleaning these out is the fastest path to "this looks human-written".
+
+## 2. Naming (naming)
+
+**Impact:** CRITICAL
+**Description:** AI-generated code swings between two opposite failure modes — generic placeholders (`data`, `result`, `info`) and over-descriptive run-ons (`theUserWhoIsCurrentlyLoggedIn`) — often in the same file. A human teammate converges on a register. Suffix abuse (`*Helper`, `*Manager`, `*Util`) and type-in-name patterns (`userObject`, `resultArray`) round out the family.
+
+## 3. Over-engineering (over-eng)
+
+**Impact:** HIGH
+**Description:** Adding layers nobody asked for. Premature interfaces with one implementation, single-method classes that should be functions, wrappers called from one place, and pulling in a new dependency when an existing one does the job. AI defaults to "enterprise-grade" because its training distribution is enterprise-grade.
+
+## 4. Defensive overdose (defensive)
+
+**Impact:** HIGH
+**Description:** Try/catch wrapped around code that can't throw. Null checks after a non-null assertion. `if (array && array.length > 0)` three times in the same function. Meanwhile real defenses (timeouts on external calls, rate limits, circuit breakers) are missing. AI is defensive in the wrong places.
+
+## 5. Test slop (test)
+
+**Impact:** HIGH
+**Description:** Tests that mock everything and assert nothing. Tests that mirror the implementation's logic — they pass because they re-encode the same code, not because they verify Behavior. "Doesn't throw" assertions that don't check anything meaningful. Snapshot abuse instead of behavioral assertions.
+
+## 6. Style fingerprints (style)
+
+**Impact:** MEDIUM
+**Description:** The small tells: hyper-consistent formatting (no human drift), `as any` / `@ts-ignore` sprinkled where types are hard, _absence_ of `// HACK:` / `// XXX:` scars (real codebases have geology), stray `console.log` / `dd()` debug artifacts, and trivial boilerplate like `if (x) return true; else return false`.

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/_template.md

@@ -0,0 +1,42 @@
+---
+title: Rule Title Here
+impact: CRITICAL|HIGH|MEDIUM
+impactDescription: "Specific consequence — e.g., 'Makes code feel like a tutorial; reduces comprehension speed'"
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+**Impact: LEVEL (impactDescription)**
+
+1-2 sentences explaining why this pattern is an AI fingerprint and why it hurts.
+
+## Incorrect
+
+```language
+// ❌ AI-slop example
+```
+
+**Why it's slop:**
+
+- Reason 1
+- Reason 2
+
+## Correct
+
+```language
+// ✅ Human-equivalent
+```
+
+**Why it reads human:**
+
+- Reason 1
+- Reason 2
+
+## Detection
+
+```bash
+# grep / oxlint / mago invocation
+```
+
+Reference: [Link](url) · Internal: [`related-rule`](related-rule.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/comments-closing-brace-labels.md

@@ -0,0 +1,112 @@
+---
+title: Closing-Brace Labels
+impact: MEDIUM
+impactDescription: "Relic of older training corpora; clear AI fingerprint that modern editors make pointless"
+tags: comments, closing-brace, ai-fingerprint, style
+---
+
+## Closing-Brace Labels
+
+**Impact: MEDIUM (Relic of older training corpora; clear AI fingerprint that modern editors make pointless)**
+
+`} // end function` / `} // end if block` / `} // close foreach` are a strong AI tell. The pattern comes from older C/COBOL/Verilog training data where blocks could span hundreds of lines and editors didn't fold scope. Modern PHP, TypeScript, and any editor with bracket-matching makes the label pure noise.
+
+If your function is so long you need a label on its closing brace, the real fix is to split the function — not annotate the brace.
+
+## Incorrect
+
+```php
+// ❌ Labels on closing braces
+
+class OrderService
+{
+    public function process(Order $order): void
+    {
+        if ($order->isPaid()) {
+            foreach ($order->items as $item) {
+                if ($item->requiresShipping()) {
+                    $this->ship($item);
+                } // end if requiresShipping
+            } // end foreach items
+        } // end if isPaid
+    } // end function process
+} // end class OrderService
+```
+
+```typescript
+// ❌ TS variant
+function processOrder(order: Order): void {
+  if (order.isPaid()) {
+    order.items.forEach((item) => {
+      if (item.requiresShipping()) {
+        ship(item);
+      } // end if requiresShipping
+    }); // end forEach
+  } // end if isPaid
+} // end function processOrder
+```
+
+**Why it's slop:**
+
+- Every modern IDE highlights the matching opener when the cursor is on a brace
+- The labels add bytes for zero information
+- A function that needed labels for clarity is a function that needs to be split
+- Pattern is recognisably training-data noise (PHP-from-2008, Verilog, COBOL)
+
+## Correct
+
+```php
+// ✅ Either small enough not to need labels, OR split for clarity
+
+class OrderService
+{
+    public function process(Order $order): void
+    {
+        if (!$order->isPaid()) {
+            return;
+        }
+        $this->shipEligibleItems($order);
+    }
+
+    private function shipEligibleItems(Order $order): void
+    {
+        foreach ($order->items->filter->requiresShipping() as $item) {
+            $this->ship($item);
+        }
+    }
+}
+```
+
+```typescript
+// ✅ Smaller scopes, no labels needed
+function processOrder(order: Order): void {
+  if (!order.isPaid()) return;
+  shipEligibleItems(order);
+}
+
+function shipEligibleItems(order: Order): void {
+  order.items.filter((i) => i.requiresShipping()).forEach(ship);
+}
+```
+
+**Why it reads human:**
+
+- Short functions; the closing brace is visually close to the opener
+- No annotation noise; editor handles brace matching
+- If a developer felt the need to label, they'd split the function instead
+
+## Detection
+
+```bash
+# Closing brace followed by an "end" / function/class/if/foreach annotation comment
+grep -rEn '^\s*\}\s*(\)\s*)?\s*(//|#).*\b(end|close|finish)\b' \
+  --include='*.php' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
+  app/ src/
+
+# Specific PHP closing-tag labels
+grep -rEn '^\s*\}\s*//.*(end (function|class|if|foreach|for|while|switch))' --include='*.php' app/
+```
+
+A single hit is borderline; **three or more in one file is an unmistakable AI fingerprint.**
+
+Reference: [Code Complete — Chapter 32 on Self-Documenting Code](https://www.microsoftpressstore.com/store/code-complete-9780735619678) · Internal: [`comments-narration`](comments-narration.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/comments-empty-docblocks.md

@@ -0,0 +1,132 @@
+---
+title: Empty Docblocks That Restate the Signature
+impact: HIGH
+impactDescription: "Adds bytes, zero information; suggests the author auto-generated without reading"
+tags: comments, docblocks, jsdoc, phpdoc, ai-fingerprint
+---
+
+## Empty Docblocks That Restate the Signature
+
+**Impact: HIGH (Adds bytes, zero information; suggests the author auto-generated without reading)**
+
+A docblock that adds nothing the signature already says is a tell. `/** Get the user */` above `function getUser(): User` tells the reader nothing the function name and return type don't. Modern PHP and TypeScript both encode types in the signature; redundant docblocks are pure noise.
+
+Useful docblocks document **edge cases, thrown exceptions, side effects, or non-obvious semantics** — not "this method does what its name says".
+
+## Incorrect
+
+```php
+// ❌ Restates the signature; adds nothing
+/**
+ * Get the user by ID.
+ *
+ * @param int $id The user ID
+ * @return User The user
+ */
+public function getUser(int $id): User
+{
+    return User::findOrFail($id);
+}
+
+/**
+ * Adds two numbers together.
+ *
+ * @param int $a First number
+ * @param int $b Second number
+ * @return int The sum
+ */
+public function add(int $a, int $b): int
+{
+    return $a + $b;
+}
+```
+
+```typescript
+// ❌ Same pattern in TS
+/**
+ * Get the user.
+ * @param id - The user ID
+ * @returns The user
+ */
+function getUser(id: string): User {
+  /* ... */
+}
+
+/**
+ * Adds two numbers.
+ * @param a - First number
+ * @param b - Second number
+ * @returns The sum
+ */
+function add(a: number, b: number): number {
+  return a + b;
+}
+```
+
+**Why it's slop:**
+
+- The signature already says all of this — return type, parameter types, what's returned
+- Bytes per useful info: ~zero
+- A human writes a docblock when there's something the signature _can't_ express
+
+## Correct — option 1: no docblock at all
+
+```php
+// ✅ Signature speaks for itself
+public function getUser(int $id): User
+{
+    return User::findOrFail($id);
+}
+
+public function add(int $a, int $b): int
+{
+    return $a + $b;
+}
+```
+
+## Correct — option 2: docblock that earns its place
+
+```php
+// ✅ Docblock documents what the signature CAN'T say
+/**
+ * Get a user, or throw if not found.
+ *
+ * @throws ModelNotFoundException if no user matches $id
+ * @throws AuthorizationException if the current user can't view $id
+ */
+public function getUser(int $id): User
+{
+    Gate::authorize('view', User::class);
+    return User::findOrFail($id);
+}
+```
+
+```typescript
+// ✅ TSDoc that documents real edge cases
+/**
+ * @throws OutOfRangeError if `amount` exceeds the Stripe 999,999.99 cap.
+ * @remarks Rounds to 2 decimal places using banker's rounding.
+ */
+function formatAmountForStripe(amount: number): string {
+  /* ... */
+}
+```
+
+**Why it reads human:**
+
+- The remaining docblocks all carry information the signature can't
+- A reader scanning the file sees docblocks and trusts they're load-bearing
+
+## Detection
+
+```bash
+# Files with @param/@return docblocks
+grep -rln '@param\|@return\|@returns' --include='*.php' app/
+grep -rln '@param\|@returns' --include='*.ts' --include='*.tsx' src/
+```
+
+Mago's `no-empty-comment` detects literally empty comments, and `valid-docblock` checks syntax. Neither establishes whether a non-empty docblock merely restates a signature; use manual review for that distinction.
+
+The most reliable enforcement is a **PR review rule**: "every `@param` / `@return` must add information the signature doesn't already provide. Delete the rest."
+
+Reference: [PHPDoc Tags Reference](https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/) · [TSDoc](https://tsdoc.org/) · [Mago no-empty-comment](https://mago.carthage.software/1.59.0/en/tools/linter/rules/#no-empty-comment) · [Mago valid-docblock](https://mago.carthage.software/1.59.0/en/tools/linter/rules/#valid-docblock) · Internal: [`comments-narration`](comments-narration.md)

package/build/Assets/Blueprints/skills/int-code-slop-review/rules/comments-narration.md

@@ -0,0 +1,118 @@
+---
+title: Narration Comments
+impact: CRITICAL
+impactDescription: "The single loudest AI tell; cuts reading speed and signals the author didn't read what they shipped"
+tags: comments, narration, ai-fingerprint
+---
+
+## Narration Comments
+
+**Impact: CRITICAL (The single loudest AI tell; cuts reading speed and signals the author didn't read what they shipped)**
+
+Models love narrating the next line in a comment above it. The comment adds no information — it just restates the code in English. A reader has to read both, decide they say the same thing, and feel a tiny tax of distrust. Across a 500-line file, the tax compounds into "I have no idea what this codebase is doing."
+
+A useful comment answers **why**, not **what**. If the code itself says _what_, the comment is noise.
+
+## Incorrect
+
+```php
+// ❌ Comments narrate the next line — pure AI fingerprint
+
+public function createUser(array $data): User
+{
+    // Validate the input data
+    $validated = Validator::make($data, [...])->validate();
+
+    // Create a new user with the validated data
+    $user = User::create($validated);
+
+    // Send a welcome email to the user
+    Mail::to($user)->send(new WelcomeEmail($user));
+
+    // Return the newly created user
+    return $user;
+}
+```
+
+```typescript
+// ❌ Same pattern in TS — every line narrated above
+function calculateTotal(items: Item[]): number {
+  // Initialize the total to zero
+  let total = 0;
+
+  // Loop through each item in the items array
+  for (const item of items) {
+    // Add the item's price multiplied by quantity to the total
+    total += item.price * item.quantity;
+  }
+
+  // Return the calculated total
+  return total;
+}
+```
+
+**Why it's slop:**
+
+- Every comment is a literal English translation of the code on the next line
+- A reader's eyes have to traverse twice (comment → code) to learn nothing extra
+- Suggests the author was thinking out loud rather than thinking ahead
+- A human author who knew this code wouldn't bother writing these comments
+
+## Correct
+
+```php
+// ✅ Comments removed (the code says what it does); explain WHY only if non-obvious
+
+public function createUser(array $data): User
+{
+    $validated = Validator::make($data, [...])->validate();
+
+    $user = User::create($validated);
+    Mail::to($user)->send(new WelcomeEmail($user));
+
+    return $user;
+}
+```
+
+```typescript
+// ✅ Total comments removed; if any line needed comment, it'd be a WHY
+function calculateTotal(items: Item[]): number {
+  return items.reduce((sum, i) => sum + i.price * i.quantity, 0);
+}
+```
+
+If a comment IS needed, it explains _why_:
+
+```typescript
+// ✅ Good comment — explains a hidden constraint
+// Note: `total` is in cents (Stripe API uses integer minor units).
+function calculateTotal(items: Item[]): number {
+  // Stripe rejects single charges > 999,999_99 cents (= $999,999.99). Cap to avoid charge failure.
+  const total = items.reduce((sum, i) => sum + i.price * i.quantity, 0);
+  return Math.min(total, 99_999_999); // 999,999.99 expressed in cents
+}
+```
+
+**Why it reads human:**
+
+- Code speaks for itself; reader processes once
+- The one remaining comment carries a _load-bearing_ piece of context (Stripe constraint) you couldn't infer from the code
+- Signals the author understood the code well enough to know what didn't need explaining
+
+## Detection
+
+```bash
+# Heuristic: comments immediately followed by code that uses the comment's keyword
+# (rough but effective — flags lines where the comment is one word-of-code below)
+grep -rEn '^[[:space:]]*//.*' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' src/ | head -50
+grep -rEn '^[[:space:]]*//.*' --include='*.php' app/ | head -50
+
+# Stronger heuristic: comment + next non-blank line share a keyword
+# (run in code review tools or PHPStorm "Comment Density" inspections)
+
+# Review comments with a team-level "comments answer WHY only" checklist.
+```
+
+There is no fully automatic linter for this — it requires a reviewer's judgement. The detection pattern is "does the comment translate, or add context?"
+
+Reference: [Code Complete — Self-Documenting Code](https://www.microsoftpressstore.com/store/code-complete-9780735619678) · Internal: [`comments-empty-docblocks`](comments-empty-docblocks.md)