waitsec 0.4.5 → 0.5.2

package/skills/waitsec-pagemaker/references/landing-page.md

@@ -0,0 +1,220 @@
+# Landing Page Blueprint (waitsec-pagemaker)
+
+Use this guide when creating a marketing page, product launch screen, or SaaS homepage. It ensures your page converts well on both small phones and wide desktop screens without typical AI clutter.
+
+---
+
+## Complete Page Anatomy & Responsive Flow
+
+### 1. Header & Navigation Bar
+* **Desktop (1024px+):** Horizontal layout. Logo on the left, 3 to 4 clear links in the center, and 1 high-contrast Action Button on the right.
+* **Mobile (<768px):** Clean bar with Logo on the left and a 44px by 44px hamburger menu icon or a single direct CTA button on the right. Slide-out drawer or full-screen overlay for mobile links with zero layout shift.
+
+### 2. Hero Section
+* **Desktop:** Clean centered layout or 2-column split (headline and CTA on the left, interactive product preview or screenshot on the right).
+* **Mobile:** Stacks vertically. Headline first, short subtitle second, primary CTA button third, and product preview underneath. Never push the CTA below the fold on phones.
+
+### 3. Problem & Solution Contrast
+* **Desktop:** 2-column comparison card (Current Painful Way on the left vs Your Product Solution on the right).
+* **Mobile:** Stacks into two vertical cards. Show the Pain Point card first, followed immediately by the Solution card.
+
+### 4. Core Features Grid
+* **Desktop:** 3-column grid (`lg:grid-cols-3 gap-8`). Equal card heights with consistent padding.
+* **Tablet:** 2-column grid (`md:grid-cols-2 gap-6`).
+* **Mobile:** 1-column stack (`grid-cols-1 gap-4`). Each card takes full width so text is easy to read.
+
+### 5. Social Proof & Verifiable Metrics
+* **Desktop:** Clean horizontal row of partner logos, GitHub star count, or verified customer quotes.
+* **Mobile:** 2-column logo grid or vertically stacked quote cards. Never use auto-sliding carousels that users cannot pause with a thumb.
+
+### 6. Pricing Tiers
+* **Desktop:** 3-column side-by-side cards. The recommended plan is slightly highlighted with a subtle border.
+* **Mobile:** Stacks vertically. Place the Recommended Plan at the very top so mobile users see the best value first without scrolling through basic tiers.
+
+### 7. Frequently Asked Questions (FAQ) & Footer
+* **Desktop & Mobile:** Simple vertical accordions (`<details>` and `<summary>`). Clicking opens the answer in place without jumping the page.
+* **Footer:** Clean multi-column layout on desktop, neatly stacked links on mobile with copyright, privacy, and social icons.
+
+---
+
+## Detailed Pitfalls & The 5-Point Rule
+
+### 1. The Multi-CTA Confusion Trap
+
+* **The Bad Habit:** Putting three different buttons in the hero section: "Start Free Trial", "Book a Demo", and "Read Whitepaper", all with bright background colors.
+* **The Problem:** The visitor has no idea which button is the primary action. On mobile, three stacked buttons take up half the screen before any explanation of the product.
+* **Why It Fails:** When people are given too many competing choices, they freeze and click nothing. Conversion rates drop sharply.
+* **Clean Fix:** Choose exactly 1 primary action button with your main brand color. If you need a second link, make it a plain text link or an outline button:
+  ```html
+  <div class="flex flex-col sm:flex-row items-center gap-3">
+    <a href="/signup" class="w-full sm:w-auto px-6 py-3 bg-neutral-900 text-white font-medium rounded-lg text-center">
+      Start Free Trial
+    </a>
+    <a href="#demo" class="w-full sm:w-auto px-6 py-3 text-neutral-600 hover:text-neutral-900 font-medium text-center">
+      View Live Demo &rarr;
+    </a>
+  </div>
+  ```
+* **The Waitsec Way:** Every marketing page has one main job. Make the single most important action obvious in less than 3 seconds.
+
+### 2. The Stretched Desktop Comparison Table
+
+* **The Bad Habit:** Building a wide 4-column comparison table comparing features against competitors, and letting it shrink directly into a mobile phone view.
+* **The Problem:** The columns squish down to 60px wide, table headers overlap, and checkmark icons clip outside cell borders.
+* **Why It Fails:** Users cannot read which feature belongs to which plan. Trying to pinch-to-zoom on a phone breaks page navigation.
+* **Clean Fix:** On desktop, use a clean responsive table. On mobile screens below 768px, hide the wide table and show stacked feature cards for each plan instead:
+  ```html
+  <!-- Desktop Table View -->
+  <div class="hidden md:block overflow-x-auto">
+    <table class="w-full text-left border-collapse">...</table>
+  </div>
+
+  <!-- Mobile Stacked Card View -->
+  <div class="block md:hidden space-y-4">
+    <div class="p-5 border border-neutral-200 rounded-xl">...</div>
+  </div>
+  ```
+* **The Waitsec Way:** Never force desktop tables into narrow phone viewports. Transform tables into vertical cards when the screen gets tight.
+
+### 3. Copy-Paste Feature Cards
+
+* **The Bad Habit:** Generating 6 identical cards, each with the exact same layout: a tiny blue icon, a vague headline like "Blazing Fast", and two lines of generic text.
+* **The Problem:** The features section looks like a placeholder template. High-value features and minor features look completely identical.
+* **Why It Fails:** Visitors scan pages quickly. When all cards look the same, visitors skip the entire section without reading.
+* **Clean Fix:** Give primary features more visual weight. Use a bento-grid style: 1 large card with an actual UI preview for your flagship feature, and smaller cards for supporting features:
+  ```html
+  <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
+    <!-- Flagship Feature (spans 2 columns on desktop) -->
+    <div class="md:col-span-2 p-6 bg-neutral-50 rounded-2xl border border-neutral-200">
+      <h3 class="text-xl font-semibold">Real-Time Sync Engine</h3>
+      <p class="text-neutral-600 mt-2">Syncs data across tabs in under 50ms.</p>
+      <!-- Real preview box -->
+      <div class="mt-4 bg-white p-4 rounded-xl border border-neutral-200 font-mono text-xs">...</div>
+    </div>
+
+    <!-- Secondary Feature -->
+    <div class="p-6 bg-neutral-50 rounded-2xl border border-neutral-200">
+      <h3 class="text-lg font-semibold">Offline Ready</h3>
+      <p class="text-neutral-600 mt-2">Queues changes until your connection returns.</p>
+    </div>
+  </div>
+  ```
+* **The Waitsec Way:** Design follows content importance. Give your biggest product advantage the biggest visual real estate.
+
+### 4. The 4-Column Pricing Overflow on Mobile
+
+* **The Bad Habit:** Putting 3 or 4 pricing plans in a rigid grid that stays horizontal on small screens, causing the page to stretch sideways.
+* **The Problem:** The mobile screen wobbles left and right, and the primary "Buy Now" buttons get clipped out of view.
+* **Why It Fails:** Buying should be effortless. If a customer cannot see the price and the checkout button on their phone, they will leave immediately.
+* **Clean Fix:** Stack pricing tiers vertically on mobile (`grid-cols-1`), switch to 2 columns on tablet (`md:grid-cols-2`), and 3 columns on desktop (`lg:grid-cols-3`). Always pin the Recommended plan at the top of the mobile stack:
+  ```html
+  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 max-w-5xl mx-auto">
+    <!-- Highlighted Plan: ordered first on mobile with order-1 -->
+    <div class="order-1 lg:order-2 p-6 border-2 border-neutral-900 rounded-2xl bg-white shadow-sm">
+      <span class="text-xs font-bold uppercase tracking-wider text-neutral-500">Most Popular</span>
+      <h3 class="text-2xl font-bold mt-1">Pro Team</h3>
+      <div class="text-4xl font-extrabold mt-3">$29<span class="text-sm font-normal text-neutral-500">/mo</span></div>
+      <a href="/checkout" class="block w-full py-3 mt-6 text-center bg-neutral-900 text-white font-medium rounded-lg">Get Started</a>
+    </div>
+
+    <!-- Basic Plan -->
+    <div class="order-2 lg:order-1 p-6 border border-neutral-200 rounded-2xl bg-white">...</div>
+
+    <!-- Enterprise Plan -->
+    <div class="order-3 lg:order-3 p-6 border border-neutral-200 rounded-2xl bg-white">...</div>
+  </div>
+  ```
+* **The Waitsec Way:** Make the purchase path obvious and thumb-friendly. Zero horizontal scrolling on checkout sections.
+
+### 5. The Jittery Full-Height Hero on Mobile
+
+* **The Bad Habit:** Forcing the hero section to `height: 100vh` on mobile phones.
+* **The Problem:** As the user scrolls down, the mobile browser URL bar shrinks or disappears. This triggers a sudden recalculation of `100vh`, making the hero jump up and down.
+* **Why It Fails:** Visual jumping disorients users and makes the website feel cheap and buggy.
+* **Clean Fix:** Use natural vertical padding (`py-16` or `py-20`), or use dynamic viewport units (`min-h-[100dvh]`):
+  ```html
+  <section class="min-h-[85vh] flex items-center justify-center py-16 px-4">
+    <div class="max-w-4xl mx-auto text-center">
+      <h1 class="text-3xl sm:text-5xl font-bold tracking-tight text-neutral-900">...</h1>
+    </div>
+  </section>
+  ```
+* **The Waitsec Way:** Respect the physical mechanics of phone browsers. Let content breathe naturally instead of locking screen height.
+
+---
+
+## SEO, GEO & Structured Data (Landing Page)
+
+State what the product is and who it is for within the first two sentences of the hero. Answer engines quote those lines, so make them complete and direct.
+
+- Title: product name plus one clear benefit, about 50 to 60 characters.
+- Meta description: what the product does and who it is for, about 140 to 160 characters.
+- One `<h1>` that carries the core value proposition in plain words.
+- Server-render the hero headline, subheadline, and primary CTA.
+- Add an FAQ block with question-shaped `<h3>` headings. Start each answer with a direct one-sentence response.
+- Keep the Open Graph image at 1200x630 and use an absolute URL.
+
+### JSON-LD for a Landing Page
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "Organization",
+      "@id": "https://example.com/#organization",
+      "name": "Example Inc",
+      "url": "https://example.com",
+      "logo": "https://example.com/images/logo.png"
+    },
+    {
+      "@type": "WebSite",
+      "@id": "https://example.com/#website",
+      "url": "https://example.com",
+      "name": "Example",
+      "publisher": { "@id": "https://example.com/#organization" }
+    },
+    {
+      "@type": "SoftwareApplication",
+      "name": "Example App",
+      "applicationCategory": "BusinessApplication",
+      "operatingSystem": "Web",
+      "url": "https://example.com",
+      "offers": {
+        "@type": "Offer",
+        "price": "0",
+        "priceCurrency": "USD"
+      }
+    },
+    {
+      "@type": "FAQPage",
+      "mainEntity": [
+        {
+          "@type": "Question",
+          "name": "Is there a free plan?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "Yes. The free plan covers one project with no time limit."
+          }
+        }
+      ]
+    }
+  ]
+}
+</script>
+```
+
+Include the `FAQPage` block only when the FAQ is actually visible on the page. Use `Product` instead of `SoftwareApplication` for a physical or ecommerce product.
+
+---
+
+## Pre-Flight Checklist for Landing Pages
+
+- [ ] Does the hero section have exactly 1 high-contrast primary CTA button?
+- [ ] Do all pricing and comparison tables stack into vertical cards on screens narrower than 768px?
+- [ ] Are feature cards structured with varied visual weight (bento style) rather than copy-paste clones?
+- [ ] Is there zero horizontal page wobble when testing at 320px width?
+- [ ] Are all headlines scaled down comfortably on mobile to avoid breaking words into multiple lines?
+- [ ] Is there one H1, a unique title, a meta description, and an absolute Open Graph image?
+- [ ] Is the JSON-LD valid, type-appropriate, and free of validator errors?

package/skills/waitsec-quality/SKILL.md

@@ -5,7 +5,7 @@ description: "Quality and safety guardrails for AI coding agents. Enforces deep
 
 # waitsec-quality: Systemic Quality & Safety Guardrails
 
-You operate under the **waitsec-quality** engineering discipline. This skill extends `waitsec-core` with strict operational boundaries governing systemic security, testing integrity, and data schema migrations.
+You operate under the **waitsec-quality** engineering discipline. This skill extends `waitsec` with strict operational boundaries governing systemic security, testing integrity, and data schema migrations.
 
 ---
 
@@ -21,22 +21,101 @@ Activate this skill whenever:
 
 ---
 
-## Core Guardrails
+## Part 1: Security & Access Boundaries
 
-### 1. Security Auditing & Access Boundaries
-- **Ownership & IDOR:** Validate tenant and user ownership on every database read, update, and delete operation. Never trust client-supplied entity IDs without verifying permissions.
-- **Sensitive Data Exposure:** Never return raw password hashes, internal server stack traces, or private keys in API responses. Use explicit serialization filters.
-- **Mass Assignment:** Whitelist fillable attributes explicitly on ORM models or request validators. Reject raw wildcard inserts.
+### 1. Trusting Client-Supplied IDs (IDOR)
 
-### 2. Testing Discipline
-- **Assertion Reality:** Every test must assert concrete side-effects or state changes. Trivial assertions (`assert true`, `assert response is not null`) are prohibited.
-- **Mocking Boundaries:** Test actual business logic and database queries where feasible. Never mock the system under test to force an artificial passing run.
-- **Regression Tests:** When fixing an existing bug, write a failing reproduction test before applying the fix.
+* **The Bad Habit:** Fetching a record straight from a request ID, like `Order::find($id)`, without checking who owns it.
+* **The Problem:** Any logged-in user can change the ID in the URL and read or edit someone else's record.
+* **Why It Fails:** This is a direct data breach. One guessed number exposes private orders, messages, or invoices.
+* **Clean Fix:** Scope every read, update, and delete to the authenticated user or tenant:
+  ```php
+  // Bad
+  $order = Order::find($id);
 
-### 3. Data & Migration Integrity
-- **Rollback Safety:** Every database migration must include a working, tested down/rollback method.
-- **Zero Destructive Shortcuts:** Never drop tables or columns on production schemas without an explicit multi-step deprecation plan.
-- **Constraint Discipline:** Enforce foreign keys and uniqueness constraints at the database engine level, not solely in application memory.
+  // Good
+  $order = auth()->user()->orders()->findOrFail($id);
+  ```
+* **The Waitsec Way:** Never trust an ID that came from the client. Verify ownership on every data access.
+
+### 2. Leaking Sensitive Data in Responses
+
+* **The Bad Habit:** Returning the whole model, including password hashes, internal flags, or stack traces.
+* **The Problem:** The API response exposes fields the user should never see.
+* **Why It Fails:** Leaked hashes and internal details hand attackers the first step of a break-in.
+* **Clean Fix:** Return explicit, whitelisted fields only. Use serialization filters or resource classes.
+* **The Waitsec Way:** Send the minimum the client needs. Everything else stays server-side.
+
+### 3. Mass Assignment
+
+* **The Bad Habit:** Passing the whole request payload into `create()` or `update()`.
+* **The Problem:** A crafted request can set fields the form never exposed, such as `isAdmin` or `price`.
+* **Why It Fails:** Attackers change roles and prices with a single extra parameter, and the database accepts it.
+* **Clean Fix:** Whitelist fillable attributes and pass only validated data:
+  ```php
+  // Forbidden
+  User::create($request->all());
+
+  // Required
+  User::create($request->validated());
+  ```
+* **The Waitsec Way:** Accept only the fields you meant to accept. Never forward raw input to the database.
+
+---
+
+## Part 2: Testing Discipline
+
+### 4. Trivial Assertions
+
+* **The Bad Habit:** Writing tests that assert `true`, assert the response is not null, or call an endpoint without checking the result.
+* **The Problem:** The suite is green while the feature is broken.
+* **Why It Fails:** A passing test that proves nothing gives false confidence. Bugs reach production behind a fake safety net.
+* **Clean Fix:** Assert a concrete outcome: the row was created, the balance changed, the status code is 403, or the field equals the expected value.
+* **The Waitsec Way:** A test must prove a behavior. If it cannot fail, it is not a test.
+
+### 5. Mocking the System Under Test
+
+* **The Bad Habit:** Mocking the very class or query the test is supposed to verify.
+* **The Problem:** The test only confirms that the mock returned what the mock was told to return.
+* **Why It Fails:** Real bugs live in the code that got mocked away. The suite passes and the feature still fails.
+* **Clean Fix:** Test real business logic and database behavior where feasible. Mock only true external boundaries.
+* **The Waitsec Way:** Test the real thing. Put mocks at the edges, never over the subject.
+
+### 6. Fixing Without a Reproduction Test
+
+* **The Bad Habit:** Fixing a reported bug immediately and moving on, with no test that captures the failure.
+* **The Problem:** Nothing stops the same bug from returning in the next refactor.
+* **Why It Fails:** Without a failing reproduction first, you cannot even prove the fix addresses the reported case.
+* **Clean Fix:** Write a failing test that reproduces the bug, then fix until it passes, then keep the test.
+* **The Waitsec Way:** A bug fix ships with proof. The reproduction test is that proof.
+
+---
+
+## Part 3: Data & Migration Integrity
+
+### 7. One-Way Migrations
+
+* **The Bad Habit:** Writing an `up()` migration with no working `down()` rollback.
+* **The Problem:** A bad deploy cannot be reversed cleanly.
+* **Why It Fails:** When the migration corrupts or blocks data, the team is stuck with a manual, risky recovery under pressure.
+* **Clean Fix:** Every migration gets a tested rollback that restores the previous schema state.
+* **The Waitsec Way:** A migration is a two-way door. If you cannot safely go back, you cannot safely go forward.
+
+### 8. Destructive Schema Shortcuts
+
+* **The Bad Habit:** Dropping a column or table in one migration to "clean up".
+* **The Problem:** Live data disappears the moment the migration runs, with no recovery path.
+* **Why It Fails:** Production data loss is permanent and often unrecoverable. One migration erases history.
+* **Clean Fix:** Deprecate in steps: stop writing, keep reading, back up, wait, then drop in a later release.
+* **The Waitsec Way:** Remove data only when you are certain nothing needs it. Prefer deprecation over destruction.
+
+### 9. Application-Only Constraints
+
+* **The Bad Habit:** Enforcing uniqueness or relationships only in application code.
+* **The Problem:** Race conditions and direct database writes slip past the checks.
+* **Why It Fails:** Duplicate or orphaned rows appear even though the app "always checks". Data integrity decays over time.
+* **Clean Fix:** Enforce foreign keys, unique indexes, and not-null rules at the database engine level.
+* **The Waitsec Way:** The database is the last line of defense. Let it enforce the invariants.
 
 ---
 

package/skills/waitsec-ui/SKILL.md

@@ -20,22 +20,80 @@ Activate this skill whenever:
 
 ---
 
-## Core Guardrails
-
-### 1. Anti-Slop Visuals & CSS
-- **No Cliché AI Aesthetics:** Reject gratuitous purple/indigo gradients, multi-layered floating drop-shadows, and slow decorative hover animations.
-- **Functional Decoration:** Every border, shadow, and background variation must serve visual hierarchy. If removing an effect does not hurt usability, remove it.
-- **System Design Consistency:** Use existing project design tokens, spacing scales, and colors rather than arbitrary hex values or arbitrary CSS classes.
-
-### 2. Responsive Discipline
-- **Mobile-First Layouts:** Ensure every layout flexes cleanly down to small screens (320px).
-- **No Fixed Widths:** Never set fixed pixel widths (`width: 600px`) on main layout containers. Use fluid widths, `max-width`, and relative units (`rem`, `%`).
-- **No Horizontal Overflow:** Prevent content from clipping or causing horizontal page scrolls on mobile viewports.
-
-### 3. Anti-Slop UI Copy (Implementation Silence)
-- **User Value Over Mechanism:** Never explain technical implementations to the user (e.g. "Data loaded via asynchronous API", "Infinite scroll - 40 items per request"). Users need product information, not architecture docs.
-- **Decision Clarity:** Only display copy, badges, or helper text if they help the user understand data or complete an action.
-- **Visual Self-Explanation:** If an action or button is self-evident, do not attach redundant instructions ("Click here to submit").
+## Part 1: Visual Restraint
+
+### 1. Generic AI Aesthetics
+
+* **The Bad Habit:** Reaching for purple-to-indigo gradients, layered drop shadows, and slow hover animations on every surface.
+* **The Problem:** The interface looks like every other generated template, and depth cues appear on elements that have no reason to float or move.
+* **Why It Fails:** Users recognize the generic look instantly and trust the product less. Decorative motion also distracts from the actual task.
+* **Clean Fix:** Use solid neutral surfaces and pick one deliberate accent color for the primary action. Add shadow or motion only when it signals real elevation or state.
+* **The Waitsec Way:** Restraint reads as confidence. If an effect does not help the user, remove it.
+
+### 2. Decoration That Does Not Earn Its Place
+
+* **The Bad Habit:** Adding borders, shadows, glows, and background patterns to fill empty space.
+* **The Problem:** The page is visually busy and the important element no longer stands out.
+* **Why It Fails:** When everything is decorated, nothing has hierarchy. Users do not know where to look first.
+* **Clean Fix:** Remove an effect and check whether usability drops. If it does not, leave it removed.
+* **The Waitsec Way:** Every visual choice must carry meaning. Decoration is not a substitute for hierarchy.
+
+### 3. Arbitrary Values Instead of Design Tokens
+
+* **The Bad Habit:** Typing random hex colors, odd spacing numbers, and one-off font sizes into components.
+* **The Problem:** The same "gray" appears in five slightly different shades, and spacing drifts from screen to screen.
+* **Why It Fails:** The interface feels inconsistent, and future changes require hunting every stray value.
+* **Clean Fix:** Use the existing design tokens, spacing scale, and theme colors. Add a token only when the system genuinely lacks one.
+* **The Waitsec Way:** Follow the system in place. Consistency comes from reuse, not from fresh choices.
+
+---
+
+## Part 2: Responsive Discipline
+
+### 4. Fixed Widths and Horizontal Overflow
+
+* **The Bad Habit:** Setting fixed pixel widths on main containers, tables, or code blocks.
+* **The Problem:** On a narrow phone the page wobbles sideways and content disappears past the edge of the screen.
+* **Why It Fails:** Horizontal scrolling on a vertical page breaks reading and navigation. Users lose their place and leave.
+* **Clean Fix:** Use fluid widths with a max width (`w-full max-w-5xl mx-auto px-4`) and wrap tables or code blocks in `overflow-x-auto`.
+* **The Waitsec Way:** The layout must fit the screen it is on. Zero horizontal page scrolling on mobile.
+
+### 5. Desktop Assumed as the Default
+
+* **The Bad Habit:** Building the wide desktop layout first and patching mobile with a media query at the very end.
+* **The Problem:** The mobile view inherits desktop rules and glitches: oversized type, cramped cards, and broken spacing.
+* **Why It Fails:** A last-minute patch fixes only the bug you happened to notice. Real visitors hit all the rest.
+* **Clean Fix:** Start with the mobile layout, then add widths and columns as the screen grows.
+* **The Waitsec Way:** Mobile is the base, not an afterthought. Design from the small screen up.
+
+---
+
+## Part 3: Anti-Slop UI Copy (Implementation Silence)
+
+### 6. Implementation Leaks in Copy
+
+* **The Bad Habit:** Writing user-facing text about the code, such as "Data loaded via asynchronous API" or "Infinite scroll, 40 items per request".
+* **The Problem:** The interface explains its own technical internals to the user.
+* **Why It Fails:** Users want to finish a task, not read architecture notes. The text adds noise and reveals nothing useful.
+* **Clean Fix:** Delete implementation talk. Keep only what helps the user understand the data or complete an action.
+* **The Waitsec Way:** The UI serves the user, not the developer. Hide the mechanism, show the meaning.
+* *Deep Dive & Triage:* Read [`skills/waitsec/references/write-info-analyzer.md`](../waitsec/references/write-info-analyzer.md).
+
+### 7. Redundant Instructional Copy
+
+* **The Bad Habit:** Adding "Click here to submit" under a clear "Submit" button.
+* **The Problem:** The screen repeats what the control already says.
+* **Why It Fails:** Extra text slows scanning without adding information. It makes a clean interface feel cluttered and unsure.
+* **Clean Fix:** Let the label and visual design carry the instruction. Delete the helper sentence.
+* **The Waitsec Way:** If the interface is already clear, stay quiet. Clear does not mean more text.
+
+### 8. Labels That Do Not Help a Decision
+
+* **The Bad Habit:** Labeling every icon, card, and number with explanatory text "so the screen does not look empty".
+* **The Problem:** The page fills with words that do not help the user choose or act.
+* **Why It Fails:** Visual noise makes the real information harder to find, and users skim past everything.
+* **Clean Fix:** Keep text only when it changes a decision or explains the data. Remove labels that merely restate what is already visible.
+* **The Waitsec Way:** Show information that helps. Delete decoration made of words.
 
 ---
 

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

@@ -1,67 +0,0 @@
----
-name: ask-first
-description: Pause before coding when requirements are unclear. Ask clarifying questions instead of guessing or inventing requirements.
----
-
-# Ask First: Confirm Before You Code
-
-Most AI coding disasters happen not because the AI cannot code, but because it codes before knowing what the user actually needs.
-
-When requirements are ambiguous, do not invent answers. Stop, pause, and clarify.
-
----
-
-## Anti-Patterns (The Tells)
-
-### 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.
-
-### 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.
-
-### 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.
-
-### 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.
-
----
-
-## Decision Matrix: When to Ask vs When to Default
-
-| Situation | Action | Rationale |
-| :--- | :--- | :--- |
-| Missing storage location, file size limit, or format | **ASK** | Materially changes packages, disk, and schema. |
-| Missing permission/role requirements for a sensitive action | **ASK** | Critical security and authorization impact. |
-| Multiple valid architectures (e.g. queue worker vs synchronous) | **ASK** | Affects hosting environment and dependencies. |
-| Choosing variable names or internal helper method names | **DEFAULT** | Follow existing codebase conventions silently. |
-| Choosing standard HTTP status codes (200, 201, 404, 422) | **DEFAULT** | Follow standard REST / web specifications. |
-| Choosing standard validation error messages | **DEFAULT** | Use clear, standard phrasing. |
-
----
-
-## How to Ask Effectively
-
-When asking questions:
-1. **Limit to 1 to 3 questions maximum.** Never send a wall of text.
-2. **Provide concrete choices (A / B).** Give clear recommendations (e.g. *"Option A: Local storage (simpler for now) vs Option B: S3 bucket"*).
-3. **State the trade-off briefly.** Explain in one sentence why the choice matters.
-4. **Wait for the answer.** Do not generate speculative files while waiting.
-
----
-
-## Checklist
-
-Before writing code for any new feature, verify:
-- [ ] Are all critical requirements and constraints known?
-- [ ] Did I avoid inventing product or business logic out of thin air?
-- [ ] If questions are needed, are they capped at 1-3 with clear options?
-- [ ] Did I avoid asking trivial questions about things the codebase already answers?

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

@@ -1,54 +0,0 @@
----
-name: debug-first
-description: Inspect error logs, stack traces, and root causes before guessing or modifying code.
----
-
-# Debug First: Inspect Evidence Before Touching Code
-
-Never guess the cause of an error when real technical evidence is available. Do not spray random code changes across multiple files hoping the bug disappears.
-
----
-
-## Anti-Patterns (The Tells)
-
-### 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.
-
-### 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.
-
-### 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.
-
-### 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 5-Step Root Cause Sequence
-
-Follow this disciplined sequence whenever debugging:
-
-1. **Read the Full Stack Trace:** Locate the exact file path and line number where the execution failed. Do not stop at the first line of the error message.
-2. **Inspect the Execution Context:** Read the failing function, check the inputs passed to it, and determine the exact condition that caused the crash.
-3. **Reproduce or Verify the Root Cause:** Confirm why the condition occurred (e.g. database query returned empty array, missing environment variable, incorrect type casting).
-4. **Apply One Targeted Fix:** Make the smallest possible fix that resolves the root cause.
-5. **Verify the Fix:** Run the test suite, command, or request again to verify that the error is resolved and no regressions were introduced.
-
----
-
-## Checklist
-
-Before declaring a bug fixed:
-- [ ] Did I locate the exact line and file of the failure from the stack trace?
-- [ ] Did I fix the root cause rather than merely masking the symptom?
-- [ ] Did I avoid wrapping the code in silent, empty try/catch blocks?
-- [ ] Did I verify the fix by re-running the failing test or reproduction command?

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

@@ -1,51 +0,0 @@
----
-name: small-diff
-description: Keep edits surgical and proportional. Only modify the exact lines and files necessary to fulfill the prompt.
----
-
-# Small Diff: Surgical and Proportional Changes
-
-Do not turn a one-line bug fix into a 15-file git diff. Keep your changes laser-focused on the exact problem requested.
-
----
-
-## Anti-Patterns (The Tells)
-
-### 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.
-
-### 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.
-
-### 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.
-
-### 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 Scope Guardrail
-
-Before saving any file change, ask:
-1. **Is this edit strictly required to solve the prompt?** If no, delete the edit.
-2. **Does this edit touch unrelated functions, styles, or configuration?** If yes, revert it.
-3. **Does the git diff contain unnecessary whitespace or formatting churn?** If yes, clean up the diff.
-
----
-
-## Checklist
-
-Before submitting code changes:
-- [ ] Are all modified files directly related to the user's prompt?
-- [ ] Did I avoid global reformatting or unnecessary whitespace churn?
-- [ ] Did I preserve the project's existing quote styles, indentations, and naming conventions?
-- [ ] Did I leave working, unrelated code completely untouched?