@rfxlamia/skillkit 1.1.0 → 1.2.0

package/skills/skills/adversarial-review/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: adversarial-review
+description: >
+  Adversarial review protocol for brainstorming, product planning, and technical architecture.
+  Validate ideas against reality, enforce minimum 3 bugs, severity categorization, 3 resolution paths.
+
+  USE WHEN: "adversarial review", "run adversarial protocol", "validate brainstorming",
+  "stress test idea/plan/architecture", or reviewing any planning document.
+
+  CORE PROTOCOL:
+  1. Reality vs Claims — web search min 3x diverse angle, status VALID/PARTIAL/INVALID
+  2. Acceptance Criteria — stress test specific executor capability
+  3. Mandatory Bug Quota — minimum 3 issues, force deeper dig if insufficient
+  4. Interactive Resolution — Critical/High/Medium/Low + options A(auto-fix)/B(action items)/C(deep dive)
+
+  DIFFERENTIATOR: Mandatory bug quota prevents superficial reviews. Three resolution options
+  make findings actionable. Executor stress test differentiates from generic reviews.
+metadata:
+  version: 1.0.0
+  author: V (OpenClaw)
+category: quality
+---
+
+## Section 1: Protocol Overview
+
+Adversarial Review consists of 4 mandatory stages executed sequentially.
+
+```
+Stage 1: Reality vs Claims     → web_search + web_fetch (min 3x diverse)
+Stage 2: Acceptance Criteria  → stress test executor
+Stage 3: Mandatory Bug Quota  → minimum 3 specific issues
+Stage 4: Interactive Resolution → categorization + 3 resolution options
+```
+
+**Core principle:** A good review isn't about throwing criticism, but transforming findings into decisions.
+
+---
+
+## Section 2: Stage 1 — Reality vs Claims
+
+**Objective:** Validate claims and assumptions in the document against real data and libraries.
+
+### Execution Rules
+
+1. Use web_search and web_fetch minimum **3 times** with different angles
+2. Don't just search one topic — diversify: library docs, benchmarks, user pain points, known issues
+3. Mark each claim with status: **VALID** / **PARTIAL** / **INVALID** / **UNVERIFIED**
+4. Include hidden caveats not mentioned in the original document
+
+### Search Angle Guidelines
+
+```
+Angle 1: Library/tech being used → find known limitations, version issues
+Angle 2: User pain point → find real UX research or forum complaints
+Angle 3: Benchmark/performance → find real data, not marketing claims
+Angle 4: Competitor/alternative → find if problem has been solved elsewhere
+Angle 5: Production failure → find post-mortems or known failure modes
+```
+
+### Output Format
+
+```
+**Claim:** "[claim from document]"
+**Status:** VALID / PARTIAL / INVALID / UNVERIFIED
+**Facts:** [data from search]
+**Hidden caveat:** [not mentioned in document]
+```
+
+---
+
+## Section 3: Stage 2 — Acceptance Criteria
+
+**Objective:** Not just whether the idea can be done, but whether this specific executor can do it.
+
+### Questions to Answer
+
+```
+1. Does the chosen tech stack match the executor's skills?
+2. Are there components requiring significant learning curve?
+3. Is the time estimate realistic for this executor (not team)?
+4. Are there external dependencies outside the executor's control?
+5. Is there a proof-of-concept needed before committing to production?
+```
+
+### Output Format
+
+```
+**Component:** [component/bet name]
+**Verdict:** Executable / Partial / Needs PoC first / Beyond capability
+**Reason:** [specific, honest]
+**Recommendation:** [concrete steps if there's a gap]
+```
+
+---
+
+## Section 4: Stage 3 — Mandatory Bug Quota
+
+**Objective:** Force discovery of non-obvious problems. Prevent reviews that are too soft.
+
+### Quota Rule (NON-NEGOTIABLE)
+
+```
+MINIMUM 3 specific issues must be found.
+If < 3 found → SYSTEM MUST SEARCH AGAIN in:
+  - Edge cases: what happens during extreme conditions?
+  - Performance issues: what happens at scale/high load?
+  - Architecture violations: is this design consistent?
+  - Dependency risk: what happens if library changes?
+  - UX failure mode: what happens when user does unexpected things?
+```
+
+### Severity Categories
+
+| Level | Definition | Example |
+|-------|------------|---------|
+| 🔴 Critical | Will kill the product/project if not fixed | Core promise cannot be delivered |
+| 🟠 High | Will cause significant problems in production | Performance degradation, bad UX |
+| 🟡 Medium | Real issue but has workaround | File clutter, minor inconsistency |
+| 🟢 Low | Needs attention but not urgent | Naming convention, minor inefficiency |
+
+### Bug Report Format
+
+```
+### [EMOJI] [LEVEL] #N — [Short Title]
+
+**Problem:** [specific description, not generic]
+**Trigger scenario:** [when this issue occurs]
+**Impact:** [what happens to user/product]
+**Why it's dangerous:** [why this isn't an edge case that can be ignored]
+```
+
+---
+
+## Section 5: Stage 4 — Interactive Resolution
+
+**Objective:** Every finding must have a resolution path, not just criticism.
+
+### Three Resolution Options (Always Provide All Three)
+
+```
+A. Auto-fix
+   → Directly fix the problematic idea/plan
+   → Output: new version of the fixed section
+   → Suitable for: problems with clear solutions
+
+B. Action Items
+   → Checklist to be executed by user
+   → Output: [ ] specific item with done criteria
+   → Suitable for: problems requiring user decision
+
+C. Deep Dive
+   → Detailed problem explanation with concrete examples
+   → Output: in-depth analysis + trade-offs
+   → Suitable for: problems requiring understanding before deciding
+```
+
+### Resolution Summary Table
+
+```markdown
+| # | Issue | Severity | Primary Recommendation |
+|---|-------|----------|------------------------|
+| 1 | [title] | 🔴 Critical | [one sentence fix] |
+| 2 | [title] | 🟠 High | [one sentence fix] |
+```
+
+---
+
+## Section 6: Full Protocol Template
+
+```markdown
+# Adversarial Review — [Document/Project Name]
+
+## Stage 1 — Reality vs Claims
+[Results from 3+ web searches with diverse angles]
+[Status per claim: VALID/PARTIAL/INVALID/UNVERIFIED]
+
+## Stage 2 — Acceptance Criteria
+[Stress test per component/bet]
+
+## Stage 3 — Mandatory Bug Quota (minimum 3)
+[Bug #1 — Critical/High/Medium/Low]
+[Bug #2 — ...]
+[Bug #3 — ...]
+
+## Stage 4 — Interactive Resolution
+[Per bug: option A / B / C]
+
+### Summary Priority Matrix
+| # | Issue | Severity | Primary Recommendation |
+|---|-------|----------|------------------------|
+
+## Meta-Conclusion
+[One paragraph: what changed the most? first step priority?]
+```
+
+---
+
+## Section 7: Quick Reference
+
+**Do's:**
+- Run 4 stages sequentially without skipping
+- Diversify web search angles (don't search the same topic 3x)
+- Be honest about executor capability
+- Provide all three resolution options for each Critical and High finding
+
+**Don'ts:**
+- Don't stop at < 3 issues
+- Don't create resolutions that are too generic ("just fix it")
+- Don't skip Stage 2 — executor stress test is this protocol's main differentiator
+- Don't combine multiple components in one bug report
+
+**Trigger phrases:**
+```
+"run adversarial review protocol for [document]"
+"adversarial review this"
+"validate this brainstorming hard"
+"stress test this plan"
+"find weaknesses in [plan/architecture]"
+```

package/skills/skills/baby-education/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: baby-education
+description: Makes agent explain concepts with extreme clarity for beginners learning new topics or projects. Uses analogies-first approach, visual mental models, and ELI5 style to transform complex technical explanations into accessible learning experiences. Trigger when user is new to a technology, starting a project, or explicitly requests simple explanations.
+category: engineering
+---
+
+# Baby Education
+
+## Overview
+
+This skill transforms your explanations into beginner-friendly learning experiences. Instead of diving into technical jargon, you'll explain concepts using everyday analogies, build visual mental models step-by-step, and maintain a conversational storytelling tone that makes complex ideas accessible.
+
+**When to use this skill:**
+- User is learning a new programming language, framework, or technology
+- Starting a new project type they haven't worked with before
+- User explicitly asks for "simple explanation", "ELI5", or mentions being a beginner
+- Explaining architecture, design patterns, or abstract concepts
+- Debugging errors for someone new to the codebase
+
+## Core Principles
+
+### 1. Analogies-First Approach
+
+Always start with a concrete analogy from everyday life before introducing technical concepts.
+
+**Bad (technical-first):**
+```
+A REST API uses HTTP methods like GET, POST, PUT, DELETE to perform
+CRUD operations on resources identified by URIs.
+```
+
+**Good (analogies-first):**
+```
+Think of a REST API like a restaurant:
+- The menu (API documentation) lists what you can order
+- You tell the waiter your order (send a request)
+- The kitchen (server) prepares it
+- The waiter brings your food (returns a response)
+
+Now mapping to technical terms:
+- GET = "Show me the menu" (reading data)
+- POST = "Place a new order" (creating data)
+- PUT = "Change my order" (updating data)
+- DELETE = "Cancel my order" (deleting data)
+```
+
+### 2. Build Visual Mental Models
+
+Help users visualize abstract concepts by describing them spatially or structurally.
+
+**Example for explaining async/await:**
+```
+Imagine you're cooking dinner:
+
+WITHOUT async/await (blocking):
+1. Put rice in cooker → wait 20 min standing there doing nothing ⏰
+2. Then chop vegetables → wait 10 min ⏰
+3. Then cook vegetables → wait 15 min ⏰
+Total: 45 minutes
+
+WITH async/await (non-blocking):
+1. Put rice in cooker (start it, walk away)
+2. While rice cooks, chop vegetables
+3. While rice still cooks, start cooking vegetables
+4. When rice beeps, it's ready - combine everything
+Total: 20 minutes
+
+The keyword `await` is like checking "is the rice done?" before serving.
+You can do other things, but when you NEED the rice, you wait for it.
+```
+
+### 3. Progressive Complexity
+
+Start simple, then gradually introduce technical details.
+
+**Structure:**
+1. **Opening analogy** - relate to familiar experience
+2. **Basic concept** - simple version without edge cases
+3. **Technical vocabulary** - introduce terms with context
+4. **Real implementation** - show actual code/solution
+5. **Recap** - tie analogy back to technical reality
+
+**Example:**
+```
+1. Analogy: "Git branches are like parallel universes where you can
+   try different versions of your story."
+
+2. Basic: "You create a branch to test a new feature without breaking
+   your main code. If it works, you merge it back."
+
+3. Technical: "A branch is a pointer to a commit in the Git tree.
+   'main' is just the default branch name."
+
+4. Implementation:
+   git checkout -b new-feature
+   # make changes
+   git commit -m "add feature"
+   git checkout main
+   git merge new-feature
+
+5. Recap: "So those 'parallel universes' are actually just pointers
+   in a commit graph, letting you work on multiple versions safely."
+```
+
+### 4. Jargon Handling Rules
+
+**Rule 1: Avoid jargon when possible**
+- Instead of "instantiate an object" → "create a copy of the blueprint"
+- Instead of "dependency injection" → "passing tools into a function instead of creating them inside"
+
+**Rule 2: When unavoidable, define with examples**
+```
+Bad: "You need to serialize the data before sending it over the network."
+
+Good: "You need to convert your data into a format that can travel through
+the internet - like packing your items into a shipping box. This process
+is called 'serialization'. JSON is one common packing format."
+```
+
+**Rule 3: Use "In other words..." bridges**
+```
+"The function is idempotent. In other words, calling it 5 times gives
+the same result as calling it once - like pressing an elevator button
+multiple times doesn't make it arrive faster."
+```
+
+### 5. Conversational Storytelling Tone
+
+Write like you're explaining to a friend over coffee, not presenting at a conference.
+
+**Characteristics:**
+- Use "you" and "we" (not passive voice)
+- Ask rhetorical questions: "Why does this matter?"
+- Acknowledge confusion: "This part trips up everyone at first..."
+- Celebrate small wins: "See? That wasn't so scary!"
+- Use casual connectors: "Now here's the cool part...", "But wait...", "The trick is..."
+
+**Example:**
+```
+Formal: "One must configure the environment variables prior to application
+initialization to ensure proper authentication credentials are available."
+
+Conversational: "Before you run your app, we need to set up environment
+variables - think of them as secret notes you leave for your code. This is
+where you'll tell it things like API keys and passwords, without hardcoding
+them into your files (which would be like writing your PIN on your credit card!)."
+```
+
+## Common Patterns
+
+### Pattern: Explaining Errors
+
+**Structure:**
+1. "Here's what happened..." (translate error message)
+2. "Why this happened..." (root cause in simple terms)
+3. "How to fix it..." (concrete steps)
+4. "How to avoid it..." (prevention tip)
+
+**Example:**
+```
+Error: `TypeError: Cannot read property 'length' of undefined`
+
+Here's what happened:
+Your code tried to check how long something is (.length), but that "something"
+doesn't exist yet (undefined). It's like trying to measure the length of a box
+that hasn't been delivered yet.
+
+Why this happened:
+The variable might not have been assigned a value, or it came back empty from
+a function that didn't return what you expected.
+
+How to fix it:
+Add a safety check before using .length:
+if (myArray && myArray.length > 0) {
+  // safe to use myArray now
+}
+
+How to avoid it:
+Always check if data exists before using it, especially when it comes from
+external sources (APIs, user input, databases).
+```
+
+### Pattern: Comparing Options
+
+Use tables or clear comparisons when showing multiple approaches:
+
+```
+"Should I use forEach or map?"
+
+Think of them like this:
+
+forEach = walking through a museum, just looking
+- You see each painting
+- You don't create anything new
+- Just doing something with each item
+
+map = walking through a museum with a camera
+- You see each painting
+- You create a new photo collection
+- Returns a new array with transformed items
+
+When to use:
+- forEach: "Do something with each item" (logging, updating UI)
+- map: "Transform each item into something new" (formatting data)
+```
+
+## Integration Tips
+
+### With Code Examples
+
+Always provide code with comments that explain WHY, not just WHAT:
+
+```javascript
+// Bad comments (what)
+// Create a new array
+const numbers = [1, 2, 3];
+
+// Good comments (why)
+// We'll use map to create a new array instead of modifying the original
+// (keeping original data unchanged is safer for debugging)
+const doubled = numbers.map(n => n * 2);
+```
+
+### With Documentation References
+
+Bridge the gap between your explanation and official docs:
+
+```
+"Now that you understand the restaurant analogy, the official docs will
+make more sense. When they say 'RESTful endpoints', they mean the different
+menu items. When they mention 'HTTP verbs', those are the GET/POST/PUT/DELETE
+actions we talked about."
+
+[Link to official docs]
+```
+
+## Quick Reference
+
+**Before explaining, ask yourself:**
+1. ✅ Did I start with an analogy from everyday life?
+2. ✅ Can someone visualize this concept spatially/structurally?
+3. ✅ Did I avoid jargon, or define it with examples?
+4. ✅ Does my tone sound like talking to a friend?
+5. ✅ Would a complete beginner understand each step?
+
+**Tone checklist:**
+- ✅ Use "you" and "we"
+- ✅ Ask rhetorical questions
+- ✅ Acknowledge common struggles
+- ✅ Celebrate small wins
+- ❌ No passive voice
+- ❌ No unexplained acronyms
+- ❌ No assuming prior knowledge
+
+## Resources
+
+This skill includes reference materials with advanced techniques and examples:
+
+- `references/advanced-techniques.md` - Visual mental models, scaffolding patterns, handling difficult topics
+- `references/transformations.md` - Before/after examples of technical explanations transformed into beginner-friendly versions