opencode-skills-collection 3.1.23 → 4.0.1

package/bundled-skills/clean-code-guard/references/naming-and-functions.md

@@ -0,0 +1,187 @@
+# Naming and Functions — Clean Code Chapters 2 and 3
+
+Source: Robert C. Martin, *Clean Code*. Sample chapters online at the Pearson PDF; chapter summaries at Vivek Khatri's Ch. 2 notes and Herberto Graça's Ch. 3 summary.
+
+## Contents
+
+- Meaningful names
+  - N1. Intention-revealing
+  - N2. No disinformation, no encodings
+  - N3. Meaningful distinctions
+  - N4. Searchable, pronounceable
+  - N5. Class names are nouns, method names are verbs
+  - N6. Banned generic names
+- Functions
+  - F1. Small. Then smaller.
+  - F2. Do one thing
+  - F3. One level of abstraction per function
+  - F4. Step-down rule
+  - F5. Few arguments
+  - F6. No flag arguments
+  - F7. No output arguments / Command-Query Separation
+  - F8. No side effects in queries
+  - F9. Prefer exceptions to return codes
+  - F10. Duplication is the root evil
+- Self-check for naming and functions
+
+## Meaningful names
+
+### N1. Intention-revealing
+
+A name should tell you *why it exists, what it does, and how it's used*. If you need a comment to explain a name, the name is wrong.
+
+**Bad:**
+```text
+d  // elapsed time in days
+ts = []
+fn(xs)
+```
+
+**Good:**
+```text
+elapsedDays
+timestamps
+filterOverdueInvoices(invoices)
+```
+
+### N2. No disinformation, no encodings
+
+No Hungarian notation (`strName`, `iCount`). No interface-prefix `I` (`IUserService`). No member prefix `m_`. No "List" suffix unless the type is actually a list (`accountList` for a `set` is disinformation).
+
+**Bad:** `strFirstName`, `IUserRepo`, `m_count`, `userArray` (when it is not an array).
+
+**Good:** `first_name`, `UserRepo`, `count`, `users_by_id`.
+
+### N3. Meaningful distinctions
+
+Do not differentiate names by adding noise words. `ProductInfo`, `ProductData`, `Product` — what's the difference? Same with `getActiveAccount` vs. `getActiveAccountInfo`. If the distinction is real, name the distinction.
+
+### N4. Searchable, pronounceable
+
+Single-letter names are acceptable inside short loop scope (`for i in range(...)`). Anywhere else they hurt grep. `MAX_RETRIES` is searchable; `7` is not.
+
+If you can't read the name aloud in a code review, it's a bad name. `genymdhms` is a real-world example from the book — `generation_timestamp` is the fix.
+
+### N5. Class names are nouns, method names are verbs
+
+`User`, `Invoice`, `Account` — classes are things. `saveInvoice`, `computeTotal`, `notifyUser` — methods are actions. A class named `ProcessInvoice` and a method named `Invoice` are both wrong.
+
+### N6. Banned generic names
+
+Without a qualifier, these names always violate intention-revealing:
+
+- `data`, `data2`, `data_final`
+- `result`, `result_final`
+- `item`, `value`, `temp`, `obj`, `info`
+- `helper`, `manager`, `utils`, `common`
+- `handle_*`, `process_*`, `do_*` (when `*` is also generic)
+
+Qualified versions are fine: `raw_csv_bytes`, `parsed_invoice`, `dedup_by_email`.
+
+---
+
+## Functions
+
+### F1. Small. Then smaller.
+
+Target ≤20 lines. Uncle Bob's harder pass says 2–4 lines is the goal. If a function does not fit on a screen, it does too much. Extract.
+
+### F2. Do one thing
+
+A function does one thing when you cannot extract another function from it with a name that is not a restatement of its body. If `compute_invoice` contains a 10-line block that you could meaningfully call `apply_discount`, the original was doing more than one thing.
+
+### F3. One level of abstraction per function
+
+Mixing levels is the most common subtle defect. Do not put an HTTP call, a SQL query, a regex parse, and a business rule in the same function — those are four levels.
+
+**Bad:**
+```text
+renderUserReport(userId):
+  connection = openDatabaseConnection()
+  row = queryUserRow(connection, userId)
+  displayName = row.firstName + " " + row.lastName
+  markup = "<h1>" + displayName + "</h1>"
+  return markup
+```
+Four levels: connection, query, formatting, presentation.
+
+**Good:**
+```text
+renderUserReport(userId):
+  user = userRepository.findById(userId)
+  return userReportView.render(user)
+```
+
+### F4. Step-down rule
+
+Read a file top-to-bottom; each function is followed by functions one level of abstraction below. Callers above callees. Confirmed by Uncle Bob himself on X.
+
+### F5. Few arguments
+
+Zero is best. One is fine. Two is OK. Three "should be avoided." Four or more "requires very special justification" — usually means you should pass a config object.
+
+At five parameters, stop and extract a request/config object: record, struct, DTO, or equivalent.
+
+### F6. No flag arguments
+
+A boolean parameter that switches behavior is always wrong. Split into two functions.
+
+**Bad:**
+```text
+render(invoice, asHtml):
+  if asHtml:
+    ...
+  else:
+    ...
+```
+
+**Good:**
+```text
+renderInvoiceHtml(invoice)
+renderInvoicePdf(invoice)
+```
+
+The same applies to `mode="x"` string enums when the mode changes behavior. If `mode` parameterizes data (locale, currency), it's fine. If it parameterizes *which function runs*, split.
+
+### F7. No output arguments / Command-Query Separation
+
+A function either returns a value (query) or has a side effect (command). Never both.
+
+**Bad:**
+```text
+save(record) -> boolean
+// Returns true if saved, false if record was not found.
+```
+What does the bool mean? Success? Found-ness? The caller can't tell.
+
+**Good:**
+```text
+save(record)
+recordExists(recordId) -> boolean
+```
+
+### F8. No side effects in queries
+
+A getter-style, finder-style, or predicate-style function must not mutate state. If it caches, log the cache write at debug level; do not change observable behavior.
+
+### F9. Prefer exceptions to return codes
+
+`if save(x):` is a code smell. Either save succeeds (returns nothing) or it raises (`InvoiceSaveError`). Return codes proliferate up the call stack and get forgotten; exceptions can't be ignored silently.
+
+### F10. Duplication is the root evil
+
+If two functions share a non-trivial block, extract it. But — see [dry-kiss-yagni.md](dry-kiss-yagni.md) for when this is wrong (Sandi Metz's "wrong abstraction" caveat).
+
+---
+
+## Self-check for naming and functions
+
+Before you ship code:
+
+1. Do all names answer "what does this represent" without a comment?
+2. Are functions ≤20 lines?
+3. Are functions doing one thing? (Can you extract another function with a non-restating name? If yes, you're doing more than one.)
+4. Are mixed abstraction levels eliminated?
+5. Are there any functions with >4 parameters? Extract a config object.
+6. Are there boolean flag arguments? Split.
+7. Do any functions both return a value *and* mutate state in a way callers depend on? Split.

package/bundled-skills/clean-code-guard/references/review-checklist.md

@@ -0,0 +1,150 @@
+# Review-Mode Checklist
+
+When the user asks you to **review, audit, critique, or rate code** (rather than write it), follow this structured walk-through. Do not edit the code unless asked. Produce a findings report.
+
+## Contents
+
+- Output format
+- Pre-flight: is this a refactor or a rewrite?
+- Walk order
+  - Section A: naming and functions
+  - Section B: comments and formatting
+  - Section C: SOLID
+  - Section D: DRY, KISS, YAGNI
+  - Section E: AI failure modes
+- What to do with each finding
+- When the review is contested
+- What this review does not do
+
+## Output format
+
+Use this template exactly. The headings make findings easy to triage.
+
+```
+# Code review: <file or scope>
+
+## Summary
+<2–3 sentence verdict: ship / needs work / rewrite>
+Counts: <N> critical, <M> important, <K> nits  (must equal the findings listed below)
+
+## Critical findings
+<must-fix before merge; omit this heading if none>
+- `<file>:<line>` — <tag>: <what's wrong> [`<quoted code or behavior>`]. Fix: <concrete change>.
+  <continuation line only when the fix is code-sized>
+
+## Important findings
+<should fix but not blocking; omit if none>
+- ...
+
+## Nits
+<style, naming, minor structure; max 3, each with a fix; omit if none>
+- ...
+
+## What's good
+<0–3 genuine, specific positives; omit on a clean review — do not manufacture praise>
+
+## Coverage
+One line per section: the findings it produced, or `clean` (walked it, found nothing). A blank section is an unbacked claim, not a pass — fill it before delivering.
+- Section A (naming & functions): <findings, or `clean`>
+- Section B (comments & formatting): <findings, or `clean`>
+- Section C (SOLID): <findings, or `clean`>
+- Section D (DRY/KISS/YAGNI): <findings, or `clean`>
+- Section E (AI failure modes): <findings, or `clean`>
+```
+
+Severity:
+- **Critical** — security, correctness, data loss, swallowed exceptions, hardcoded "success" returns.
+- **Important** — design defects with maintenance cost: SOLID violations, premature abstractions, parameter explosion, generic naming.
+- **Nit** — style, single-letter names outside loops, missing docstring contracts on public APIs.
+
+Every finding carries its quoted code or observed behavior and a named fix — that is what lets the author contest it; with no quote or no fix it is not a finding, so drop it. Report only counted findings: never an estimated quality score, "X% cleaner," or a maintainability index — no baseline exists, so the number would be invented.
+
+## Pre-flight: is this a refactor or a rewrite?
+
+Before walking the sections, classify the review:
+
+- **Refactor review:** the user wants the code to be cleaner, not different. **Observable behavior must not change** — same inputs, same outputs, same exceptions, same side effects. If you'd suggest a change that alters behavior, mark it as a *separate finding* labelled "Behavior change — confirm with author" and do not bundle it with refactor recommendations. Refactoring is *"a change made to the internal structure of software... without changing its observable behavior"* (Fowler, *Refactoring*).
+- **Code-review for correctness:** the user wants you to find bugs. Behavior changes are in scope. Flag them at Critical severity if they affect the contract.
+
+If you can't tell which one the user wants, ask before writing the review.
+
+## Walk order
+
+### Section A — naming and functions
+
+Pull [naming-and-functions.md](naming-and-functions.md) if you need source citations.
+
+1. Scan all identifiers. Flag generic ones: `data`, `result`, `item`, `temp`, `value`, `obj`, `info`, `helper`, `manager`, `utils`, `handle_*`, `process_*`, `do_*` without qualifier.
+2. For each function: lines ≤20? params ≤4? one thing? one level of abstraction? Flag violations.
+3. Flag boolean flag arguments.
+4. Flag functions that both return value *and* mutate observable state ambiguously (CQS violation).
+5. Flag getter-style or predicate-style functions that mutate.
+
+### Section B — comments and formatting
+
+Pull [comments-and-formatting.md](comments-and-formatting.md) if needed.
+
+1. Flag every comment that paraphrases the code below it.
+2. Flag commented-out code blocks.
+3. Flag step-number, "First...", or "Then..." scaffolding comments.
+4. Flag docstrings that restate the signature with no contract.
+5. Flag style inconsistencies with the surrounding file (casing, quoting, import order).
+
+### Section C — SOLID
+
+Pull [solid.md](solid.md) if needed.
+
+1. (SRP) Any class with methods serving two unrelated stakeholder groups?
+2. (OCP) Conditional or switch dispatch on a type tag that grew with the codebase?
+3. (LSP) Any subclass with an unimplemented/unsupported-operation failure, strengthened preconditions, or weakened postconditions?
+4. (ISP) Any interface where the concrete client uses only a subset of methods?
+5. (DIP) High-level module importing a concrete from a low-level module? Abstractions living in the same package as the concrete?
+
+### Section D — DRY, KISS, YAGNI
+
+Pull [dry-kiss-yagni.md](dry-kiss-yagni.md) if needed.
+
+1. (DRY) ≥5-line duplicated blocks. Confirm it's knowledge duplication before recommending extraction.
+2. (DRY-Metz) Wrong abstractions: per-caller branches and special-case flags accumulating in a shared function.
+3. (KISS) Any function with cyclomatic >10 or nesting >5? (Estimate from branches and loops; you don't need exact metrics.)
+4. (YAGNI) Optional parameters never called, config flags with one path, abstractions with one implementation, wrappers around libraries that "make them swappable."
+
+### Section E — AI failure modes (highest leverage)
+
+Pull [ai-failure-modes.md](ai-failure-modes.md) for every check here.
+
+1. Any catch-all error handler that swallows without recovery? Critical.
+2. Any defensive guards for types/values the system already excludes — *inside* a trust boundary? (Validation of external or untrusted input at the boundary is not a defensive guard; do not flag it.)
+3. Any premature abstraction — interface or factory with one implementation?
+4. Any comment pollution — line-by-line restating, step-number scaffolding, or documentation comments that paraphrase signatures?
+5. Any duplication of logic that already exists in a helper in the same repo?
+6. Any imports or library methods you should verify exist in the installed version?
+7. Any generic naming (cross-check with Section A).
+8. Any long function mixing concerns (cross-check with Section A).
+9. Any 5+ parameter functions without a config object (cross-check with Section A).
+10. Any inconsistency with surrounding file style (cross-check with Section B).
+11. Any dead code, unused imports, unreachable branches, half-implementations?
+12. **Any hardcoded "success" returns, mock fixtures, fake values in production code?** Critical.
+13. Any code that looks copy-pasted from a similar function (off-by-one, wrong null semantic)?
+14. Any speculative configurability — flags, env vars, optional params without callers?
+15. **Any "simplification" that deleted boundary validation, or a cleanup path (`finally`/`close`/`defer`/context-manager) the contract relied on?** That's a behavior change, not cleanup. Critical.
+
+## What to do with each finding
+
+A finding must name its fix — a code change OR a specific structural action. "Nameable" is the bar, not "codeable." No named fix means it stays vague unease, not a finding — drop it.
+
+- ❌ "This error handling could perhaps be more specific." (no named replacement — drop it)
+- ✅ "`L42 except Exception` swallows the DB error → catch `OperationalError`, let the rest propagate."
+- ✅ "`L88–140 processOrder` mixes validation, pricing, persistence → extract `validate()` and `price()`."
+
+For each finding: quote the offending code (file + line), name the principle or AI failure mode in `references/`, give the fix (code if small, a named structural action if not), and assign severity (Critical / Important / Nit).
+
+## When the review is contested
+
+If the user pushes back on a finding, cite the source from the relevant `references/` file. The rules trace to primary sources (Uncle Bob, Fowler, Hunt & Thomas, McCabe, Metz) and published 2024–2026 research on LLM code generation. If the user has a context-specific reason to override, record it as an inline comment that names **the principle, the reason, and a revisit trigger** — e.g. `// clean-code exception: 4-arg ceiling — config DTO, all fields required at construction; revisit when an optional field appears.` (the prefix is illustrative, not a required tag). On a later pass a well-formed marker downgrades the finding to *Documented exception* — don't re-flag it; a marker with **no revisit trigger is itself a finding**, since an exception with no exit is just deferred debt. Name the principle, not a rule number — a number is meaningless to a future reader.
+
+## What this review does not do
+
+- Run linters or formatters. That's tooling.
+- Execute the code or run tests. Add a finding instead: *"No tests for the new `charge` path — recommend adding."*
+- Enforce language-specific style (Black, Prettier, PHPCS). Defer to the project's style tooling unless the user explicitly asks.

package/bundled-skills/clean-code-guard/references/solid.md

@@ -0,0 +1,280 @@
+# SOLID — the five principles
+
+Source: Robert C. Martin. The five principles were collected on Uncle Bob's "Principles of OOD" page on objectmentor.com (mirrored at butunclebob.com) and updated on blog.cleancoder.com. Original papers from *C++ Report* circa 1995–1996.
+
+## Contents
+
+- S: Single Responsibility Principle
+- O: Open/Closed Principle
+- L: Liskov Substitution Principle
+- I: Interface Segregation Principle
+- D: Dependency Inversion Principle
+- How AI-generated code typically breaks SOLID
+- Self-check for SOLID
+
+---
+
+## S — Single Responsibility Principle
+
+**Definition (Martin 2014, hardened from the original).** *"A module should be responsible to one, and only one, actor."*
+
+Older form: "A class should have only one reason to change."
+
+Source: blog.cleancoder.com — SRP, 2014.
+
+### Why
+
+The axis is *people*. Different stakeholders (Accounting, HR, DBA) want different things from the same class. When their needs change, they edit the same file, conflict, and break each other.
+
+### Smells to flag
+
+- One class contains methods touching unrelated subsystems (persistence + presentation + business rules).
+- Methods on the class serve disjoint stakeholder groups.
+- Git history shows two distinct clusters of co-changing methods inside one class.
+
+### Common misinterpretation
+
+*"A class should do one thing."* No. SRP is about **cohesion around an actor**, not method count. A 12-method `InvoiceRepository` answerable only to the data-access layer satisfies SRP. A 3-method class with one HTTP call, one Jinja render, and one DB write does not.
+
+### Bad
+
+```text
+EmployeeReport
+  calculatePay()    // Accounting
+  reportHours()     // HR
+  save()            // Data storage owner
+```
+
+### Good
+
+```text
+PayCalculator       // Accounting
+HoursReporter       // HR
+EmployeeRepository  // Data storage owner
+```
+
+---
+
+## O — Open/Closed Principle
+
+**Definition.** *"Software entities (classes, modules, functions) should be open for extension, but closed for modification."*
+
+Originally Bertrand Meyer (1988, *Object-Oriented Software Construction*); Martin refocused it on polymorphic abstraction rather than implementation inheritance.
+
+Source: blog.cleancoder.com — OCP, 2014; Martin's 1996 paper PDF (Duke mirror).
+
+### Why
+
+Protect stable high-level policy from churn in low-level variants. New behavior should arrive as new code, not edits to working code.
+
+### Smells to flag
+
+- Branch dispatching on a type tag or runtime type check — every new type requires editing the same function.
+- Adding a feature requires modifying N existing files instead of adding one.
+- `match`/`enum` switches that cross module boundaries (policy reaching into details).
+
+### Common misinterpretation
+
+*"Never modify code."* The principle is that *modules containing high-level policy* should not be modified to accommodate new variants. Leaf code changes freely.
+
+### Bad
+
+```text
+export(record, kind):
+  if kind == "pdf":  return toPdf(record)
+  if kind == "csv":  return toCsv(record)
+  if kind == "json": return toJson(record)
+  // adding "xml" requires editing this function
+```
+
+### Good
+
+```text
+exporters = {
+  "pdf":  toPdf,
+  "csv":  toCsv,
+  "json": toJson,
+}
+
+export(record, kind):
+  return exporters[kind](record)
+// adding "xml" is one line in the table
+```
+
+---
+
+## L — Liskov Substitution Principle
+
+**Definition (Liskov & Wing, 1994).** *"If for each object o1 of type S there is an object o2 of type T such that for all programs P defined in terms of T, the behavior of P is unchanged when o1 is substituted for o2, then S is a subtype of T."*
+
+Source: Martin's LSP paper PDF (LaBRI mirror).
+
+### Why
+
+Substitutability. Callers written against a base type must continue to work when handed a subtype — otherwise polymorphism leaks abstraction.
+
+### Smells to flag
+
+- A subclass overrides a method to signal "not implemented" or "unsupported operation."
+- A subclass **strengthens preconditions** (rejects inputs the parent accepts).
+- A subclass **weakens postconditions** (returns something the parent guarantees against).
+- Callers perform runtime subtype checks to decide whether to call a method.
+
+### Common misinterpretation
+
+*"Subclasses must have the same methods."* That's signature compatibility, which is just type-checking. LSP is **behavioral**:
+- Preconditions can only **weaken** in the subtype.
+- Postconditions and invariants can only **strengthen**.
+- Parameter types are contravariant; return types covariant.
+
+### The Rectangle/Square classic
+
+```text
+Rectangle
+  setWidth(width)
+  setHeight(height)
+  area()
+
+Square extends Rectangle
+  setWidth(width):
+    this.width = width
+    this.height = width   // invariant: width == height
+  setHeight(height):
+    this.width = height   // invariant: width == height
+    this.height = height
+```
+A caller holding a `Rectangle` reference does `r.set_width(5); r.set_height(4); assert r.area() == 20`. With a `Square`, the assertion fails — LSP violated.
+
+The fix is *not* to fix the methods. The fix is that `Square is-not-a Rectangle` in the behavioral sense. Compose, don't inherit.
+
+---
+
+## I — Interface Segregation Principle
+
+**Definition.** *"Clients should not be forced to depend on methods they do not use."* Equivalently: many client-specific interfaces beat one general-purpose interface.
+
+Source: Martin's 1996 ISP paper, catalogued at butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod.
+
+### Why
+
+Fat interfaces create transitive coupling. Clients are dragged into recompiles and test-fixtures for methods they never call.
+
+### Smells to flag
+
+- A `Service` / `Manager` / `Repository` interface with 10+ methods, where any given caller uses one or two.
+- Implementations that stub half the methods with no-op bodies, null/empty placeholders, or unimplemented failures (usually co-occurs with an LSP violation).
+- One mock object reconfigured differently across tests because the interface is too broad.
+
+### Common misinterpretation
+
+*"Make interfaces small."* As a count rule, no. ISP is **client-centric** — segregation is driven by *the set of methods a particular client uses*, not by an arbitrary method-count ceiling. Two clients with identical method needs can share one interface even if it has 20 methods.
+
+### Bad
+
+```text
+UserService
+  create(...)
+  read(...)
+  update(...)
+  delete(...)
+  email(...)
+  notify(...)
+  audit(...)
+  export(...)
+```
+The audit logger only needs `audit`. It now depends transitively on the email and export subsystems.
+
+### Good
+
+```text
+UserAuditor
+  audit(...)
+
+UserNotifier
+  notify(...)
+```
+
+Implementations can satisfy multiple protocols. Callers depend only on what they use.
+
+---
+
+## D — Dependency Inversion Principle
+
+**Definition (verbatim, two clauses).**
+*(a) High-level modules should not depend on low-level modules. Both should depend on abstractions.*
+*(b) Abstractions should not depend on details. Details should depend on abstractions.*
+
+Source: Martin's 1996 *C++ Report* paper, archived at Wayback / objectmentor.com.
+
+### Why
+
+Control the direction of the import graph. Policy must not transitively `import` mechanism, or policy becomes un-reusable and untestable.
+
+### Smells to flag
+
+- A high-level module imports a concrete low-level client inside business logic.
+- A constructor that `new`/instantiates concrete collaborators instead of accepting them as parameters.
+- Abstractions defined in the *low-level* package (the interface lives next to its database or service implementation) — ownership reversed. The interface should live in the **client's** package.
+- Function signatures typed against concrete classes instead of interfaces, protocols, or abstract contracts.
+
+### Common misinterpretation
+
+*"DIP means use a DI container."* No. DIP is about **the direction of source-code dependencies**. You can satisfy DIP with plain constructor injection and no framework; you can violate DIP while using Spring.
+
+### Bad
+
+```text
+// billing/charge — high-level policy
+import SqlUserRepository  // concrete import
+
+chargeUser(userId, amount):
+  repository = new SqlUserRepository()  // concrete instantiation
+  user = repository.get(userId)
+  ...
+```
+
+### Good
+
+```text
+// billing/user-repository — abstraction lives WITH the client (billing)
+UserRepository
+  get(userId) -> User
+
+// billing/charge
+chargeUser(userId, amount, repository: UserRepository):
+  user = repository.get(userId)
+  ...
+
+// sql/user-repository — detail depends on the abstraction
+SqlUserRepository satisfies UserRepository
+  get(userId) -> User
+```
+
+The import arrows go: `sql → billing` (detail → abstraction). They do not go `billing → sql`.
+
+---
+
+## How AI-generated code typically breaks SOLID
+
+Mapped to the principle each breaks:
+
+1. **God-module** from "do everything in one file" prompts — SRP + DIP + usually OCP.
+2. **Type-tag dispatch chains** (`if kind == "pdf": ...`) — OCP.
+3. **Unsupported-operation stubs in subclasses** when asked to "implement only the methods we need" — LSP + ISP.
+4. **Concrete SDK/client imports at module load time** — DIP, hard to test without patching the runtime.
+5. **Mega-`Service` interfaces** with create/read/update/delete/email/notify/audit/export — ISP, usually SRP too.
+6. **Silent precondition strengthening on override** — defensive-looking, breaks LSP because callers holding the base type now crash on previously-valid inputs.
+7. **Invariant-breaking "convenience" subclasses** (e.g., `ReadOnlyList(list)` overriding `append` to no-op) — LSP.
+8. **Inverted ownership of abstractions** — putting the interface/protocol/abstract contract in the same file as the concrete implementation. Cosmetic DIP fix, real dependency graph unchanged.
+
+---
+
+## Self-check for SOLID
+
+Before you ship code:
+
+1. (SRP) Does any class in the diff answer to more than one stakeholder group?
+2. (OCP) Does any change require a type-tag branch added to an existing function? Could it be data-driven (registry/strategy) instead?
+3. (LSP) Does any new subclass signal "not implemented", tighten preconditions, or weaken postconditions?
+4. (ISP) Does any interface have a method your concrete client doesn't use?
+5. (DIP) Does the high-level package import the low-level concrete? Where do new abstractions live — with the client or with the implementation?

package/bundled-skills/clean-code-guard/references/sources.md

@@ -0,0 +1,47 @@
+# Sources
+
+Central bibliography for `clean-code-guard`. Other reference files use source
+names instead of inline URLs so rule guidance stays readable.
+
+## Contents
+
+- Classic clean code and design references
+- LLM code-generation research and field reports
+- Metrics and verification references
+
+## Classic Clean Code And Design
+
+- **Clean Code sample chapters**: https://ptgmedia.pearsoncmg.com/images/9780132350884/samplepages/9780132350884.pdf
+- **Command Query Separation, Fowler**: https://martinfowler.com/bliki/CommandQuerySeparation.html
+- **Refactoring, Fowler**: https://martinfowler.com/books/refactoring.html
+- **YAGNI, Fowler**: https://martinfowler.com/bliki/Yagni.html
+- **DRY, The Pragmatic Programmer excerpt**: https://media.pragprog.com/titles/tpp20/dry.pdf
+- **The Wrong Abstraction, Sandi Metz**: https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction
+- **SOLID principles, Uncle Bob archive**: http://butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod
+- **SRP, Uncle Bob**: https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html
+- **OCP, Uncle Bob**: https://blog.cleancoder.com/uncle-bob/2014/05/12/TheOpenClosedPrinciple.html
+- **LSP, Liskov/Wing paper mirror**: https://www.labri.fr/perso/clement/enseignements/ao/LSP.pdf
+- **DIP, Object Mentor archive**: https://web.archive.org/web/20150924054349/http://www.objectmentor.com/resources/articles/Principles_and_Patterns.pdf
+
+## LLM Code-Generation Research And Field Reports
+
+- **GitClear AI code quality 2025**: https://www.gitclear.com/ai_assistant_code_quality_2025_research
+- **Package Hallucinations, Spracklen et al., USENIX Security 2025**: https://www.usenix.org/system/files/conference/usenixsecurity25/sec25cycle1-prepub-742-spracklen.pdf
+- **AI-Generated Code Considered Harmful**: https://arxiv.org/abs/2409.19182
+- **A Deep Dive Into LLM Code Generation Mistakes**: https://arxiv.org/abs/2411.01414
+- **Patterns for Reducing Friction in AI-Assisted Development, Fowler**: https://martinfowler.com/articles/reduce-friction-ai/
+- **Claude Code issue 6984, mock data generation bias**: https://github.com/anthropics/claude-code/issues/6984
+- **Karpathy on exception suppression**: https://x.com/karpathy/status/1976077806443569355
+- **Code Needs Comments**: https://arxiv.org/html/2402.13013v1
+- **Evaluating the Code Quality of AI-Assisted Code Generation Tools (Copilot, CodeWhisperer, ChatGPT)**: https://arxiv.org/abs/2304.10778
+- **On Mitigating Code LLM Hallucinations with API Documentation**: https://arxiv.org/abs/2407.09726
+- **LLM Hallucinations in Practical Code Generation (taxonomy)**: https://arxiv.org/abs/2409.20550
+- **When Names Disappear: Revealing What LLMs Actually Understand About Code**: https://arxiv.org/abs/2510.03178
+- **Neural Variable Name Repair**: https://arxiv.org/abs/2512.01141
+- **Vibe Coding in Practice**: https://arxiv.org/abs/2512.11922
+
+## Metrics And Verification
+
+- **McCabe NIST 235r**: https://www.mccabe.com/pdf/mccabe-nist235r.pdf
+- **Cognitive Complexity, SonarSource**: https://www.sonarsource.com/docs/CognitiveComplexity.pdf
+- **ReSharper cyclomatic complexity threshold guidance**: https://github.com/JetBrains/resharper-cyclomatic-complexity/blob/master/docs/ThresholdGuidance.md