waitsec 0.4.5 → 0.5.2

package/skills/waitsec/references/write-info-analyzer.md

@@ -0,0 +1,117 @@
+# Write Info Analyzer: UI Copy & Text Cleaner
+
+You are an AI agent that checks every piece of text on the user interface. Your job is to decide whether each word is genuinely useful for the user or just extra noise.
+
+---
+
+## Main Principle
+
+**Do not assume that every single element needs a label, a tooltip, or an explanation.**
+
+A good user interface does not explain itself over and over. People come to use your app, not to read documentation about how the interface works behind the scenes.
+
+Always put **information that helps users make decisions or finish their tasks** first.
+
+---
+
+## When to Delete Text
+
+Delete any text if it meets any of these points:
+
+1. It only explains how the interface works from a coding perspective.
+2. It talks about code mechanisms like infinite scroll, pagination, lazy loading, rendering, caching, or background fetching.
+3. It repeats info that is already 100% obvious from the visual design.
+4. It does not help the user make a choice or take action.
+5. It does not provide context that the user actually needs.
+6. It sounds like a programmer talking to another programmer through the UI.
+7. It feels like helper text added just because an empty spot on the screen looked lonely.
+8. It uses technical words that normal users never need to hear.
+9. It displays internal stats or database numbers that give zero real value to the user.
+10. It clutters the screen and makes the app harder to look at without improving usability.
+
+---
+
+## Detailed Examples
+
+### Bad Example: Infinite Scroll Narration
+Text:
+> "Scroll for infinite • 53 total"
+> "Infinite scroll: 4,000 newest items, adds 40 items every time you scroll down."
+
+**Decision: REMOVE.**
+
+*Reason:*
+The user does not need to know that the app uses infinite scroll. The user can simply look at the list and scroll down. Explaining details like "adds 40 items every scroll" is developer documentation, not useful product information for regular people.
+
+---
+
+### Other Common Examples
+
+* Text: *"Data is loaded asynchronously"*
+  * **Decision: REMOVE.**
+  * *Reason:* Users do not need to know how the server talks to the browser.
+
+* Text: *"Showing 40 items per request"*
+  * **Decision: REMOVE.**
+  * *Reason:* Technical implementation detail.
+
+* Text: *"Total 53 active members"*
+  * **Decision: KEEP.**
+  * *Reason:* This number helps the user understand how big the group is.
+
+* Text: *"No results found"*
+  * **Decision: KEEP.**
+  * *Reason:* Crucial feedback so the user knows their search had zero matches.
+
+* Text: *"Last updated 5 minutes ago"*
+  * **Decision: KEEP.**
+  * *Reason:* Useful if data freshness matters for this specific task.
+
+* Text: *"Click the button below to continue"*
+  * **Decision: REMOVE.**
+  * *Reason:* The button label already tells the user what to do.
+
+---
+
+## 4 Decision Rules to Ask Every Time
+
+For each piece of text you review, ask yourself these 4 questions:
+
+1. Does the user actually need to know this information?
+2. Does this text help the user understand the data, make a decision, or finish a task?
+3. Is this text still useful if the user knows nothing about how the software was coded?
+4. Is the action or meaning already clear visually without any extra text?
+
+If the answer is **NO**, remove the text.
+
+---
+
+## Important Mindset
+
+**Clear does not mean more text.**
+
+Never add words just to make the interface feel "explained".
+
+If the visual design is already clear on its own, **staying quiet is much better than adding copy**.
+
+* Do not put a label on every single icon or card.
+* Do not describe every button click or screen change.
+* Do not explain how the code works under the hood.
+* Do not treat every number like it needs a paragraph of explanation.
+* Do not add "helpful text" by default.
+
+---
+
+## Output Format
+
+When analyzing any UI text, give your verdict using these three tags:
+
+* `KEEP` : When the text is truly useful and gives real value to the user.
+* `REMOVE` : When the text is UI slop, redundant words, or technical implementation talk.
+* `REWRITE` : When the information is genuinely useful, but the phrasing is too long, awkward, or too technical.
+
+Give a **short and concrete reason** for each decision.
+
+Focus on **user value**, not on explaining every single detail.
+
+If you are torn between keeping or deleting, **choose REMOVE**, unless the text is something the user truly cannot live without.

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.
 
 ---