waitsec 0.5.0 → 0.5.2

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "waitsec",
   "displayName": "waitsec",
   "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "author": {
     "name": "fastroware"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waitsec",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
   "main": "rules/waitsec.md",
   "bin": {

package/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "waitsec",
   "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
-  "version": "0.5.0"
+  "version": "0.5.2"
 }

package/skills/waitsec/references/anti-overengineering.md

@@ -11,20 +11,27 @@ Do not turn a simple 10-line requirement into a 12-file enterprise architecture.
 
 ---
 
-## Anti-Patterns (The Tells)
+## Detailed Pitfalls & The 5-Point Rule
 
 ### 1. Architecture Theater
-- **Tell:** For a simple database query or form submission, the agent creates an Interface, a Repository class, a Data Transfer Object (DTO), an Event class, an Event Listener, and a Service Layer class across 6 different directories.
-- **Why:** The AI is showing off patterns it learned from enterprise codebases, adding cognitive overhead and boilerplate with zero practical benefit.
-- **Fix:** Write the logic directly in the existing controller or domain handler using standard framework idioms. Introduce layers only when concrete business complexity demands it.
+
+* **The Bad Habit:** For a simple database query or form submission, the agent creates an Interface, a Repository class, a Data Transfer Object (DTO), an Event class, an Event Listener, and a Service Layer class across 6 different directories.
+* **The Problem:** Six new files and several layers of indirection now wrap logic that could live in one method.
+* **Why It Fails:** Every extra layer must be read, wired, and maintained. The real behavior is buried under boilerplate, so reviews and bug hunts take longer.
+* **Clean Fix:** Write the logic directly in the existing controller or domain handler using standard framework idioms. Introduce a layer only when concrete business complexity demands it.
+* **The Waitsec Way:** Build for today's requirement. Complexity must be earned by a real problem, not added as decoration.
 
 ### 2. Speculative Future-Proofing
-- **Tell:** Writing code with plugin architectures, abstract factories, or strategy patterns for hypothetical requirements that may never exist ("in case we switch database engines later").
-- **Why:** YAGNI (You Aren't Gonna Need It). Speculative architecture is technical debt written before the feature is even used.
-- **Fix:** Build for the current requirement. Refactor when the second concrete use case arrives, not before.
+
+* **The Bad Habit:** Writing plugin architectures, abstract factories, or strategy patterns for requirements that may never exist ("in case we switch database engines later").
+* **The Problem:** The code carries branches and abstractions that are never actually exercised.
+* **Why It Fails:** YAGNI (You Aren't Gonna Need It). Speculative architecture is technical debt written before the feature is even used.
+* **Clean Fix:** Build for the current requirement. Refactor when the second concrete use case arrives, not before.
+* **The Waitsec Way:** Solve the problem in front of you. Let real needs pull the design forward.
 
 ### 3. Empty Wrapper Abstractions
-- **Tell:** Creating helper functions or classes that merely pass arguments straight through to an underlying library method with no added logic:
+
+* **The Bad Habit:** Creating helper functions or classes that only pass arguments straight through to an underlying library method with no added logic:
   ```php
   class StringHelper {
       public static function toLower($str) {
@@ -32,13 +39,18 @@ Do not turn a simple 10-line requirement into a 12-file enterprise architecture.
       }
   }
   ```
-- **Why:** It adds an extra layer of indirection to read and maintain for zero added value.
-- **Fix:** Call the native or framework method directly.
+* **The Problem:** Every caller now travels through an extra layer that adds nothing.
+* **Why It Fails:** Readers have to open the wrapper to learn it does nothing. The indirection costs time and invites more pointless wrappers.
+* **Clean Fix:** Call the native or framework method directly.
+* **The Waitsec Way:** A function must add behavior or clarify intent. If it does neither, delete it.
 
 ### 4. Dependency Addiction
-- **Tell:** Pulling in a third-party npm package, composer package, or Python module to solve a trivial problem that can be handled in 3 lines of native code (e.g. date formatting or string padding).
-- **Why:** Every third-party dependency introduces supply-chain security risks, version conflicts, and maintenance burden.
-- **Fix:** Use native language and framework utilities first.
+
+* **The Bad Habit:** Pulling in a third-party npm package, composer package, or Python module to solve a trivial problem that can be handled in 3 lines of native code (e.g. date formatting or string padding).
+* **The Problem:** A new dependency appears in the manifest for work the standard library already does.
+* **Why It Fails:** Every third-party dependency introduces supply-chain security risks, version conflicts, and maintenance burden for the whole team.
+* **Clean Fix:** Use native language and framework utilities first. Add a package only when it solves genuinely complex work.
+* **The Waitsec Way:** Every dependency is a long-term promise. Make it only when it clearly pays off.
 
 ---
 
@@ -101,7 +113,7 @@ The following security practices are **mandatory in all generated code**:
 
 ### Task: "Add an endpoint to cancel an order"
 
-❌ **Bad (Overengineered):**
+**Bad (Overengineered):**
 - `CancelOrderCommand.php`
 - `CancelOrderCommandHandler.php`
 - `OrderRepositoryInterface.php`
@@ -110,7 +122,7 @@ The following security practices are **mandatory in all generated code**:
 - `OrderCancellationDTO.php`
 - Total: 6 files, 150 lines of boilerplate, yet forgot to check if the order belongs to the logged-in user!
 
-✅ **Good (Lean & Secure):**
+**Good (Lean & Secure):**
 - `OrderController.php` (checks `$this->authorize('cancel', $order)`, updates status, dispatches existing notification).
 - Total: 1 file, 15 lines of clear, secure, readable code.
 

package/skills/waitsec/references/ask-first.md

@@ -11,27 +11,39 @@ When requirements are ambiguous, do not invent answers. Stop, pause, and clarify
 
 ---
 
-## Anti-Patterns (The Tells)
+## Detailed Pitfalls & The 5-Point Rule
 
 ### 1. Premature Scaffolding
-- **Tell:** User says "add photo upload", and the agent immediately writes database migrations, thumbnail background jobs, AWS S3 storage adapters, and cleanup cron tasks without asking a single question.
-- **Why:** The user might only have wanted a temporary avatar upload saved to local disk. Generating infrastructure based on unconfirmed assumptions wastes tokens and creates code the user has to delete.
-- **Fix:** Stop before writing code. Identify what is missing (storage target, max size, accepted formats, single vs multiple) and confirm the essentials.
+
+* **The Bad Habit:** The user says "add photo upload", and the agent immediately writes database migrations, thumbnail background jobs, cloud storage adapters, and cleanup cron tasks without asking a single question.
+* **The Problem:** The agent produces infrastructure the user never confirmed. The feature might only need to save one avatar to local disk.
+* **Why It Fails:** The user has to review and delete code they never asked for. Tokens are wasted, and the bloated diff hides the real feature.
+* **Clean Fix:** Stop before writing code. List what is genuinely missing (storage target, max size, allowed formats, one file or many) and confirm the essentials first.
+* **The Waitsec Way:** Confirm the shape of the feature before you build it. A short question costs far less than a wrong implementation.
 
 ### 2. Inventing Business Rules
-- **Tell:** User asks for "a discount calculation on checkout", and the agent invents a 15% VIP tier, coupon expiration policies, and minimum spend rules that were never mentioned.
-- **Why:** AI hallucinates business logic out of habit to make the code look "complete". Invented rules confuse the product requirements.
-- **Fix:** If rules are unspecified, ask the user, or implement only the direct formula requested with a clean placeholder for future rules.
+
+* **The Bad Habit:** The user asks for "a discount calculation on checkout", and the agent invents a 15% VIP tier, coupon expiration rules, and minimum spend limits that were never mentioned.
+* **The Problem:** The code ships with product rules that came from the model, not from the user.
+* **Why It Fails:** Invented rules quietly change how the product behaves. The user then has to hunt through the diff to find decisions they never approved.
+* **Clean Fix:** If a rule is unspecified, ask. If you cannot ask, implement only the exact formula requested and leave one clear placeholder for future rules.
+* **The Waitsec Way:** You are not the product owner. Never fill a business gap with a guess.
 
 ### 3. Destructive Replacement
-- **Tell:** User asks to "improve the navigation bar", and the agent completely deletes the existing navbar component and replaces it with a completely different framework or design.
-- **Why:** The agent assumes replacement is always preferred over enhancement.
-- **Fix:** Clarify whether the existing implementation should be modified in place or replaced from scratch.
+
+* **The Bad Habit:** The user asks to "improve the navigation bar", and the agent deletes the existing component and rebuilds it with a different framework or design.
+* **The Problem:** Working, tested code is thrown away and replaced by an unrequested rewrite.
+* **Why It Fails:** Edge cases and accessibility details handled by the original are lost. The user asked for an improvement and got unpredictable regressions instead.
+* **Clean Fix:** Clarify whether the current implementation should be edited in place or replaced from scratch. Default to editing in place.
+* **The Waitsec Way:** Improve what already exists before replacing it. Respect the code the team already trusts.
 
 ### 4. Trivia Interrogation (The Opposite Extreme)
-- **Tell:** The agent stops and bombards the user with 10 pedantic questions about internal variable names, CSS class naming conventions, or folder structures that have obvious conventions.
-- **Why:** Over-asking frustrates the user and defeats the purpose of an autonomous coding assistant.
-- **Fix:** Ask only questions that materially change the architecture or user-facing behavior. Use sensible defaults for everything else.
+
+* **The Bad Habit:** The agent stops and fires 10 pedantic questions about internal variable names, CSS class names, or folder structure.
+* **The Problem:** The user is blocked on decisions that have obvious conventions and almost no consequence.
+* **Why It Fails:** Over-asking frustrates the user and removes the value of an autonomous assistant. The work stalls on details.
+* **Clean Fix:** Ask only what changes the architecture or user-facing behavior. Use sensible defaults for everything else, and state the defaults you chose.
+* **The Waitsec Way:** Ask about decisions that are expensive to reverse, not about details you can settle with existing conventions.
 
 ---
 

package/skills/waitsec/references/debug-first.md

@@ -9,27 +9,39 @@ Never guess the cause of an error when real technical evidence is available. Do
 
 ---
 
-## Anti-Patterns (The Tells)
+## Detailed Pitfalls & The 5-Point Rule
 
 ### 1. The Shotgun Guess
-- **Tell:** A test fails or a crash occurs, and the agent immediately edits three different files, tweaking logic in random places without identifying why execution failed.
-- **Why:** The AI acts on statistical intuition rather than empirical debugging, often introducing new bugs while failing to fix the original one.
-- **Fix:** Never touch a single line of code until you have identified the exact file, line number, and runtime state that triggered the failure.
+
+* **The Bad Habit:** A test fails or a crash occurs, and the agent immediately edits three different files, tweaking logic in random places without identifying why execution failed.
+* **The Problem:** Changes land in files that may have nothing to do with the failure, and the original bug remains.
+* **Why It Fails:** The AI acts on statistical intuition rather than empirical debugging, often introducing new bugs while failing to fix the original one.
+* **Clean Fix:** Never touch a single line of code until you have identified the exact file, line number, and runtime state that triggered the failure.
+* **The Waitsec Way:** Read the evidence first. A fix without a cause is just another guess.
 
 ### 2. Silent Error Swallowing
-- **Tell:** When an exception is thrown, the agent wraps the crashing block in a generic `try/catch` and leaves the catch block empty, or returns an empty fallback (`return null;`) just to stop the crash from bubbling up.
-- **Why:** Silencing errors masks underlying data corruption and turns a loud, easily fixable bug into a silent, catastrophic production failure.
-- **Fix:** Fix the root cause so the operation succeeds safely. If catching an exception is truly necessary, log the error with full diagnostic context and handle the failure gracefully.
+
+* **The Bad Habit:** When an exception is thrown, the agent wraps the crashing block in a generic `try/catch` and leaves the catch block empty, or returns an empty fallback (`return null;`) just to stop the crash from bubbling up.
+* **The Problem:** The crash disappears, but the broken state that caused it stays in place.
+* **Why It Fails:** Silencing errors masks underlying data corruption and turns a loud, easily fixable bug into a silent, catastrophic production failure.
+* **Clean Fix:** Fix the root cause so the operation succeeds safely. If catching an exception is truly necessary, log the error with full diagnostic context and handle the failure gracefully.
+* **The Waitsec Way:** Never hide an error to make the output look clean. Silence is not a fix.
 
 ### 3. Surface Symptom Patching
-- **Tell:** Seeing `TypeError: Cannot read property 'id' of undefined`, the agent adds optional chaining (`user?.id`) or a null check (`if (!user) return;`), without checking *why* `user` was undefined in the first place.
-- **Why:** Masking a missing variable upstream causes corrupted state downstream.
-- **Fix:** Trace the data flow backwards. Find where `user` was loaded, why it failed to resolve, and fix the source query or relationship.
+
+* **The Bad Habit:** Seeing `TypeError: Cannot read property 'id' of undefined`, the agent adds optional chaining (`user?.id`) or a null check (`if (!user) return;`), without checking *why* `user` was undefined in the first place.
+* **The Problem:** The symptom is masked and the missing value flows deeper into the system.
+* **Why It Fails:** Masking a missing variable upstream causes corrupted state downstream, where the real damage is harder to trace.
+* **Clean Fix:** Trace the data flow backwards. Find where `user` was loaded, why it failed to resolve, and fix the source query or relationship.
+* **The Waitsec Way:** Fix the source, not the symptom. Chase the cause one step up the chain.
 
 ### 4. Hallucinating Missing Dependencies
-- **Tell:** An import fails or a class is not found (often due to a typo or incorrect namespace), and the agent immediately attempts to run `npm install <random-package>` or `composer require`.
-- **Why:** The agent assumes missing functionality means missing packages, cluttering the project with unneeded external dependencies.
-- **Fix:** Check for typos, path mismatches, autoloading issues, or missing exports first.
+
+* **The Bad Habit:** An import fails or a class is not found (often due to a typo or incorrect namespace), and the agent immediately attempts to run `npm install <random-package>` or `composer require`.
+* **The Problem:** The project gains a new dependency to solve what was really a typo or a path mistake.
+* **Why It Fails:** The agent assumes missing functionality means missing packages, cluttering the project with unneeded external dependencies.
+* **Clean Fix:** Check for typos, path mismatches, autoloading issues, or missing exports first.
+* **The Waitsec Way:** Confirm the cause before adding weight. Most "missing" things are already there, just named wrong.
 
 ---
 

package/skills/waitsec/references/small-diff.md

@@ -9,27 +9,39 @@ Do not turn a one-line bug fix into a 15-file git diff. Keep your changes laser-
 
 ---
 
-## Anti-Patterns (The Tells)
+## Detailed Pitfalls & The 5-Point Rule
 
 ### 1. Collateral Reformatting
-- **Tell:** Fixing a bug on line 42, but running an aggressive formatter that reformats 300 lines of whitespace, indentation, quote styles, or trailing commas across the entire file.
-- **Why:** Pollutes git history, makes `git blame` useless, and introduces merge conflicts for teammates working on the same branch.
-- **Fix:** Format only the lines you touched. Leave existing indentation and formatting untouched.
+
+* **The Bad Habit:** Fixing a bug on line 42, but running an aggressive formatter that reformats 300 lines of whitespace, indentation, quote styles, or trailing commas across the entire file.
+* **The Problem:** The real fix is now buried inside a wall of unrelated formatting changes.
+* **Why It Fails:** It pollutes git history, makes `git blame` useless, and creates merge conflicts for teammates working on the same branch.
+* **Clean Fix:** Format only the lines you touched. Leave existing indentation and formatting untouched.
+* **The Waitsec Way:** A diff should show the solution, not a style argument. Touch only what the task requires.
 
 ### 2. Gratuitous Renaming & Style Imposition
-- **Tell:** Changing working code to suit personal style preferences (e.g. converting traditional functions to arrow functions, switching `let` to `const` on unrelated variables, renaming helper methods) in sections unrelated to the prompt.
-- **Why:** Every modified line carries the risk of unintended regression and distraction during code review.
-- **Fix:** Keep your hands off working code outside the prompt scope. Respect the prevailing style of the file.
+
+* **The Bad Habit:** Changing working code to suit personal style preferences (e.g. converting traditional functions to arrow functions, switching `let` to `const` on unrelated variables, renaming helper methods) in sections unrelated to the prompt.
+* **The Problem:** The diff fills with cosmetic edits that have nothing to do with the request.
+* **Why It Fails:** Every modified line carries the risk of unintended regression and distracts the reviewer from the actual change.
+* **Clean Fix:** Keep your hands off working code outside the prompt scope. Respect the prevailing style of the file.
+* **The Waitsec Way:** Match the file you are editing, not the style in your head. Consistency beats personal preference.
 
 ### 3. File Scope Creep
-- **Tell:** Asked to change the label of a button, the agent touches the button component, the router, the global theme CSS, and updates `package.json` dependencies.
-- **Why:** The AI over-reaches, treating every task as an invitation to overhaul the project.
-- **Fix:** Modify only the files strictly required to implement the request. If touching a secondary file seems necessary, verify whether a simpler solution exists that avoids it.
+
+* **The Bad Habit:** Asked to change the label of a button, the agent touches the button component, the router, the global theme CSS, and updates `package.json` dependencies.
+* **The Problem:** Four files changed for a one-word edit.
+* **Why It Fails:** The AI over-reaches, treating every task as an invitation to overhaul the project. This hides the real change and multiplies the chance of breakage.
+* **Clean Fix:** Modify only the files strictly required to implement the request. If touching a secondary file seems necessary, verify whether a simpler solution exists that avoids it.
+* **The Waitsec Way:** Stay inside the blast radius of the prompt. Small changes stay easy to review and easy to revert.
 
 ### 4. Wholesale File Rewriting
-- **Tell:** Replacing a 400-line file with a newly generated version when only 5 lines needed an update, accidentally stripping out edge-case logic or comments that existed in the original.
-- **Why:** Generative models love generating whole files from scratch rather than performing surgical edits.
-- **Fix:** Use targeted diffs or line-level edits. Always inspect the original file to ensure existing functionality is preserved.
+
+* **The Bad Habit:** Replacing a 400-line file with a newly generated version when only 5 lines needed an update, accidentally stripping out edge-case logic or comments that existed in the original.
+* **The Problem:** The new file looks clean but silently drops behavior the original had.
+* **Why It Fails:** Generative models love generating whole files from scratch rather than performing surgical edits. That habit erases years of accumulated fixes.
+* **Clean Fix:** Use targeted diffs or line-level edits. Always inspect the original file to ensure existing functionality is preserved.
+* **The Waitsec Way:** Edit the file you have, do not replace it. The original carries context that a fresh generation cannot.
 
 ---
 

package/skills/waitsec/references/verify-first.md

@@ -11,27 +11,39 @@ Never say "I'm done" or "The bug is fixed" without concrete technical proof. Alw
 
 ---
 
-## Anti-Patterns (The Tells)
+## Detailed Pitfalls & The 5-Point Rule
 
 ### 1. The Premature Victory Lap
-- **Tell:** The agent modifies code, never runs a test or build command, and immediately announces: *"I have fixed the issue and implemented all requirements!"*
-- **Why:** The AI relies on statistical confidence instead of empirical execution. In reality, a missing semicolon, wrong import, or syntax error often lurks on the first line.
-- **Fix:** Run the relevant test suite, build command, or reproduction script before writing your closing message.
+
+* **The Bad Habit:** The agent modifies code, never runs a test or build command, and immediately announces: *"I have fixed the issue and implemented all requirements!"*
+* **The Problem:** The claim of success has no command output behind it.
+* **Why It Fails:** The AI relies on statistical confidence instead of empirical execution. In reality, a missing semicolon, wrong import, or syntax error often lurks on the first line.
+* **Clean Fix:** Run the relevant test suite, build command, or reproduction script before writing your closing message.
+* **The Waitsec Way:** Done means proven. Confidence is not evidence.
 
 ### 2. Regression Blindness
-- **Tell:** Fixing a bug in component A, but accidentally breaking components B and C because shared state, schema, or props were modified without running the full test suite.
-- **Why:** The AI focuses narrowly on the prompt and ignores downstream dependencies.
-- **Fix:** If the project has automated tests (`npm test`, `pytest`, `php artisan test`, `go test`), run them to ensure no regressions were introduced.
+
+* **The Bad Habit:** Fixing a bug in component A, but accidentally breaking components B and C because shared state, schema, or props were modified without running the full test suite.
+* **The Problem:** The targeted fix silently damages neighboring features.
+* **Why It Fails:** The AI focuses narrowly on the prompt and ignores downstream dependencies, so the team discovers the breakage in production.
+* **Clean Fix:** If the project has automated tests (`npm test`, `pytest`, `php artisan test`, `go test`), run them to ensure no regressions were introduced.
+* **The Waitsec Way:** A local fix is only safe when the whole system still works. Check the neighbors.
 
 ### 3. Phantom Verification
-- **Tell:** The agent claims *"I tested the login endpoint and it returned status 200"* when no terminal command, curl request, or test runner was actually executed in the environment.
-- **Why:** Generative models hallucinate successful outcomes based on expectation.
-- **Fix:** Real verification produces real output. If execution tools are available, run the command and inspect the actual stdout/stderr. If tools are unavailable, instruct the user on the exact command to run.
+
+* **The Bad Habit:** The agent claims *"I tested the login endpoint and it returned status 200"* when no terminal command, curl request, or test runner was actually executed in the environment.
+* **The Problem:** The stated result is invented, not observed.
+* **Why It Fails:** Generative models hallucinate successful outcomes based on expectation. The user trusts a report that never happened.
+* **Clean Fix:** Real verification produces real output. If execution tools are available, run the command and inspect the actual stdout/stderr. If tools are unavailable, instruct the user on the exact command to run.
+* **The Waitsec Way:** Report only what you actually ran. If you did not run it, say so.
 
 ### 4. Happy-Path Myopia
-- **Tell:** Testing only the success state (e.g. valid login) while completely ignoring error states (wrong password, empty inputs, network failure, unauthorized access).
-- **Why:** AI naturally gravitates toward the ideal flow.
-- **Fix:** Verify both the happy path and at least one failure/edge case before declaring completion.
+
+* **The Bad Habit:** Testing only the success state (e.g. valid login) while completely ignoring error states (wrong password, empty inputs, network failure, unauthorized access).
+* **The Problem:** The feature looks complete until a real user triggers a failure case.
+* **Why It Fails:** AI naturally gravitates toward the ideal flow, so the failure branches ship untested and break at the worst time.
+* **Clean Fix:** Verify both the happy path and at least one failure/edge case before declaring completion.
+* **The Waitsec Way:** The edges are where software breaks. Verify the failure path, not just the demo path.
 
 ---
 

package/skills/waitsec-code/SKILL.md

@@ -21,21 +21,96 @@ Activate this skill whenever:
 
 ---
 
-## Core Guardrails
+## Part 1: Comments and Noise
 
-### 1. Anti-Comment Pollution
-- **Explain Why, Never What:** Do not write comments that narrate what the next line of code does (`// Loop through users`, `// Return response`). Code should read like plain English.
-- **Self-Documenting Code:** If a code block needs explanation, extract it into a descriptively named helper function or variable instead of writing explanatory comments.
-- **Zero Dead Code:** Remove commented-out code blocks immediately. Version control handles history.
+### 1. Narration Comments
 
-### 2. Clean Code & Simplicity
-- **Single Responsibility:** Functions must do one thing well. Break functions exceeding 30-40 lines into focused, composable helpers.
-- **Flatten Nesting:** Use early returns (guard clauses) to avoid deeply nested `if/else` statements. Keep cyclomatic complexity low.
-- **Intent-Revealing Naming:** Use domain-accurate, pronounceable names. Avoid vague acronyms, generic names (`data`, `info`, `temp`), or type suffixes in identifiers.
+* **The Bad Habit:** Adding comments that narrate the next line of code (`// Loop through users`, `// Return response`).
+* **The Problem:** The code says the same thing twice: once in the comment, once in the line below.
+* **Why It Fails:** Comments rot. When the logic changes, the narration stays stale and misleads the next reader, and it pads every diff with noise.
+* **Clean Fix:** Delete the narration. If a block genuinely needs explaining, extract it into a well-named function or variable:
+  ```js
+  // Bad: the comment repeats the code
+  // Calculate total with tax
+  const t = price + price * 0.1;
 
-### 3. Dependency Hygiene
-- **Native-First:** Use built-in standard library utilities (native `fetch`, standard date methods, built-in string functions) before reaching for external packages.
-- **Audit Footprint:** Before suggesting a new dependency, verify that the package is actively maintained, light, and solves a genuinely complex problem.
+  // Good: the name explains it
+  const totalWithTax = price + price * taxRate;
+  ```
+* **The Waitsec Way:** Code should read like plain English. Explain why when it is not obvious, never what the line already says.
+
+### 2. Dead Commented-Out Code
+
+* **The Bad Habit:** Leaving old code commented out "just in case", or commenting a block out instead of deleting it.
+* **The Problem:** The file carries ghost code that no compiler or test touches.
+* **Why It Fails:** Readers cannot tell whether the block is a plan, a workaround, or garbage. It hides the real change and grows the diff.
+* **Clean Fix:** Delete it. Version control keeps the history, and the file stays honest.
+* **The Waitsec Way:** The current file should describe the current system only. The past belongs to git.
+
+---
+
+## Part 2: Structure and Size
+
+### 3. Functions That Do Too Much
+
+* **The Bad Habit:** Writing one long function that validates input, queries the database, maps a response, and sends an email.
+* **The Problem:** The function grows past 30 to 40 lines and now has several reasons to change.
+* **Why It Fails:** Tests need to set up all of those jobs at once, and a fix for one job risks breaking the others.
+* **Clean Fix:** Split by responsibility: validate in one place, query in another, respond in another. Keep each function focused on one thing.
+* **The Waitsec Way:** One function, one job. Small pieces are easier to test, reuse, and trust.
+
+### 4. Deeply Nested Conditionals
+
+* **The Bad Habit:** Nesting `if/else` blocks five levels deep until the happy path sits in the middle.
+* **The Problem:** The reader must hold every condition in their head at the same time.
+* **Why It Fails:** Deep nesting hides edge cases and makes the exit conditions hard to see. Bugs love that.
+* **Clean Fix:** Use guard clauses and early returns to handle invalid cases first, then leave the main path flat:
+  ```js
+  // Bad: nested
+  if (user) {
+    if (user.active) {
+      if (user.role === 'admin') {
+        return doWork(user);
+      }
+    }
+  }
+  return null;
+
+  // Good: flat
+  if (!user) return null;
+  if (!user.active) return null;
+  if (user.role !== 'admin') return null;
+  return doWork(user);
+  ```
+* **The Waitsec Way:** Handle what is wrong up front. Keep the main path at the top level.
+
+---
+
+## Part 3: Naming
+
+### 5. Vague Names
+
+* **The Bad Habit:** Naming things `data`, `info`, `temp`, `handleStuff`, or `process2`.
+* **The Problem:** The name tells the reader nothing about what the value holds or does.
+* **Why It Fails:** Every reader has to trace the value back to its source to understand it, which slows the whole team.
+* **Clean Fix:** Use domain names that reveal intent (`activeOrders`, `invoiceTotal`, `retryCount`). Rename when the purpose becomes clear.
+* **The Waitsec Way:** Names are documentation. A precise name removes the need for a comment.
+
+---
+
+## Part 4: Dependencies
+
+### 6. A Dependency for a Three-Line Problem
+
+* **The Bad Habit:** Installing a package to format a date, pad a string, or check an email.
+* **The Problem:** The manifest grows for work the standard library already does.
+* **Why It Fails:** Each dependency adds supply-chain risk, version conflicts, and updates you must track for the life of the project.
+* **Clean Fix:** Use built-in utilities first. Add a package only when it solves something genuinely complex:
+  ```js
+  // Instead of a date library
+  const formatted = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' }).format(new Date());
+  ```
+* **The Waitsec Way:** Native first. A dependency is a long-term commitment, not a shortcut.
 
 ---