@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skills/validate-plan/references/yagni-checklist.md

@@ -0,0 +1,330 @@
+# YAGNI Checklist - You Aren't Gonna Need It
+
+## Table of Contents
+
+- [What is YAGNI?](#what-is-yagni)
+- [YAGNI Violation Types](#yagni-violation-types)
+- [YAGNI Detection Checklist](#yagni-detection-checklist)
+- [Common YAGNI Scenarios](#common-yagni-scenarios)
+- [Plan Validation Questions](#plan-validation-questions)
+- [YAGNI-Compliant Alternatives](#yagni-compliant-alternatives)
+- [Red Flags in Plans](#red-flags-in-plans)
+- [Resolution Strategies](#resolution-strategies)
+- [Examples in Plan Context](#examples-in-plan-context)
+
+## What is YAGNI?
+
+**YAGNI (You Aren't Gonna Need It)** is a principle that states functionality should not be added until it is actually needed. It fights against over-engineering and speculative development.
+
+## YAGNI Violation Types
+
+### 1. Premature Abstraction
+
+**Symptoms:**
+- Abstract base classes with one implementation
+- Plugin systems without plugins
+- Generic solutions for specific problems
+- Configuration for hypothetical scenarios
+
+**Example:**
+```typescript
+// ❌ YAGNI: Plugin system for one widget
+interface WidgetPlugin {
+  render(): React.ReactNode;
+  configure(options: WidgetOptions): void;
+}
+
+class WidgetManager {
+  plugins: Map<string, WidgetPlugin> = new Map();
+
+  register(plugin: WidgetPlugin) { ... }
+  unregister(name: string) { ... }
+  loadFromConfig(config: PluginConfig[]) { ... }
+}
+
+// When you only have one widget:
+<WidgetManager plugins={[UserProfileWidget]} />
+```
+
+```typescript
+// ✅ YAGNI-compliant: Direct implementation first
+<UserProfileWidget />
+// Add abstraction when you have 2+ widgets
+```
+
+### 2. Over-Configuration
+
+**Symptoms:**
+- Settings that won't be changed
+- Environment variables for constants
+- Config files for simple values
+- Feature flags for unimplemented features
+
+**Example:**
+```javascript
+// ❌ YAGNI: Config for values that never change
+{
+  "buttonPadding": 8,
+  "primaryColor": "#007bff",
+  "maxRetries": 3,
+  "timeout": 5000
+}
+```
+
+```javascript
+// ✅ YAGNI-compliant: Hardcode until change needed
+const BUTTON_PADDING = 8;  // Extract when used in 2+ places
+const PRIMARY_COLOR = "#007bff";  // Extract when theming needed
+```
+
+### 3. Future-Proofing
+
+**Symptoms:**
+- "We'll need this later" features
+- Scalability for theoretical load
+- Multi-tenant architecture for single tenant
+- Multi-language support for one language
+
+### 4. Speculative Extensibility
+
+**Symptoms:**
+- Hook points that won't be used
+- Event systems for no listeners
+- Extension points without extensions
+- API versioning for one version
+
+## YAGNI Detection Checklist
+
+### For Each Feature in Plan
+
+- [ ] Is this required for the current user story?
+- [ ] Is there a concrete, immediate use case?
+- [ ] Can this be added later without rewriting?
+- [ ] Is the complexity justified by the value?
+- [ ] Would a simpler solution work now?
+
+### For Each Configuration
+
+- [ ] Will this value actually be changed?
+- [ ] Is this configurable in other similar projects?
+- [ ] Does this need to vary by environment?
+- [ ] Is the overhead of configuration worth it?
+
+### For Each Abstraction
+
+- [ ] Are there 2+ concrete use cases now?
+- [ ] Is the abstraction simpler than duplication?
+- [ ] Will this abstraction actually be used?
+- [ ] Can the abstraction be added later?
+
+## Common YAGNI Scenarios
+
+### 1. Database Design
+
+**YAGNI Violations:**
+- Soft delete when hard delete is fine
+- Audit logging when not required
+- Multi-tenant fields for single tenant
+- Archiving strategies for new features
+
+**Questions to Ask:**
+- Do we actually need to restore deleted records?
+- Who will review audit logs?
+- When will we add tenants?
+- How long until we have archive-worthy data?
+
+### 2. API Design
+
+**YAGNI Violations:**
+- GraphQL when REST is sufficient
+- Pagination for small datasets
+- Caching strategies for low traffic
+- Rate limiting for internal APIs
+
+**Questions to Ask:**
+- How many entities will this endpoint return?
+- What's the actual response time without caching?
+- Who would abuse this API?
+- What's the actual traffic volume?
+
+### 3. UI Components
+
+**YAGNI Violations:**
+- Theme system for single theme
+- 10 button variants when 2 are used
+- Responsive breakpoints for unsupported devices
+- Accessibility features for internal tools
+
+**Questions to Ask:**
+- Will we actually have multiple themes?
+- Which button variants are used in designs?
+- What devices do our users actually use?
+- Who are the actual users of this tool?
+
+### 4. Testing
+
+**YAGNI Violations:**
+- 100% coverage mandate
+- E2E tests for simple CRUD
+- Load testing for low-traffic features
+- Cross-browser testing for Chrome-only users
+
+**Questions to Ask:**
+- What's the critical path for users?
+- What bugs have actually occurred?
+- What's the actual usage pattern?
+- What browsers do analytics show?
+
+## Plan Validation Questions
+
+### High-Priority Checks
+
+1. **Does the plan include features not in requirements?**
+   ```
+   Requirement: "User can log in"
+   Plan includes: "OAuth, SAML, MFA, passwordless"
+   → YAGNI violation: Implement basic auth first
+   ```
+
+2. **Are there abstractions without concrete needs?**
+   ```
+   Plan: "Create plugin architecture for widget system"
+   Reality: Only one widget type needed
+   → YAGNI violation: Build direct widget first
+   ```
+
+3. **Is there premature optimization?**
+   ```
+   Plan: "Add Redis caching layer"
+   Reality: Database queries complete in <50ms
+   → YAGNI violation: Optimize when it's a problem
+   ```
+
+### Medium-Priority Checks
+
+1. **Are there configurable values that won't change?**
+   ```
+   Plan: "Make pagination limit configurable"
+   Reality: 20 items per page is standard
+   → YAGNI consideration: Hardcode, extract when needed
+   ```
+
+2. **Is there generic handling for specific cases?**
+   ```
+   Plan: "Support N validation rules per field"
+   Reality: Only required + email validation needed
+   → YAGNI consideration: Handle specific case first
+   ```
+
+## YAGNI-Compliant Alternatives
+
+### When Tempted to Add Abstraction
+
+| Instead of... | Do this first... | Add abstraction when... |
+|---------------|------------------|------------------------|
+| Plugin system | Direct implementation | 2+ plugins exist |
+| Generic validator | Specific validation | 3+ similar validations |
+| Config file | Hardcoded constants | Values differ by env |
+| Event system | Direct function calls | 2+ listeners needed |
+| Microservices | Monolith modules | Team scaling issues |
+
+### When Tempted to Optimize
+
+| Instead of... | Do this first... | Optimize when... |
+|---------------|------------------|------------------|
+| Database caching | Direct queries | >200ms response |
+| CDN | Serve static files | >1s load time |
+| Connection pooling | Simple connections | Connection limits hit |
+| Async processing | Synchronous | User waits >3s |
+| Pagination | Full list | >50 items |
+
+## Red Flags in Plans
+
+### Critical (Must Fix)
+- Building features for hypothetical users
+- Multi-tenant architecture for single tenant
+- API versioning before first release
+- Scalability for theoretical load
+
+### Warning (Consider Carefully)
+- More than 3 configuration options
+- Generic solutions for one use case
+- Extensibility hooks without clear need
+- Caching for low-traffic features
+
+### Info (Keep in Mind)
+- Extra fields "just in case"
+- Comments about future features
+- TODO items not in current scope
+- "We might need this" statements
+
+## Resolution Strategies
+
+### When YAGNI Violation Found
+
+1. **Assess the actual need**
+   - Is this in current requirements?
+   - What's the concrete use case?
+   - When will this be needed?
+
+2. **Determine the right scope**
+   - Remove speculative features
+   - Simplify abstractions
+   - Hardcode configuration values
+   - Focus on immediate requirements
+
+3. **Document future possibilities**
+   - Add comments for future extension
+   - Note potential abstraction points
+   - Don't build, but design for addition
+
+## Examples in Plan Context
+
+### Example 1: Admin Interface
+
+**Plan says:**
+```markdown
+Create comprehensive admin panel with:
+- User management
+- Role configuration
+- Audit logging
+- Export functionality
+- Bulk operations
+```
+
+**YAGNI Check:**
+- Requirements only mention "admin can view users"
+- No mention of roles, audit, export, bulk ops
+
+**Recommendation:**
+```markdown
+Create simple user list view:
+- Display users in table
+- Basic filtering
+- YAGNI: Add admin features when admin workflows are defined
+```
+
+### Example 2: API Design
+
+**Plan says:**
+```markdown
+Design API with:
+- Versioning (/v1/, /v2/)
+- Pagination for all endpoints
+- HATEOAS links
+- Rate limiting
+- Request queuing
+```
+
+**YAGNI Check:**
+- Only one client (web app)
+- Low traffic expected initially
+- Small dataset
+
+**Recommendation:**
+```markdown
+Simple REST API:
+- No versioning until breaking change needed
+- Pagination when datasets grow >50 items
+- YAGNI: Add rate limiting when abuse detected
+```

package/skills/skills/verify-before-ship/.skillkit-mode

@@ -0,0 +1 @@
+full

package/skills/skills/verify-before-ship/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: verify-before-ship
+description: Enforce agent to complete all 7 production safety gates with evidence before any deployment. Use when about to deploy, push to production, merge a release branch, or ship any change to a live environment. Blocks rationalized shortcuts under time, authority, sunk-cost, or exhaustion pressure.
+category: deployment
+---
+
+# Verify Before Ship
+
+## The Non-Negotiable Mandate
+
+**You may not ship to production until all 7 gates are cleared with evidence.**
+
+This is not a suggestion. It is not a checklist to tick when convenient. No urgency, role, authority, or circumstance overrides this mandate. The pressure you feel to skip a gate is the exact signal that the gate must be held.
+
+When in doubt: **DO NOT SHIP.**
+
+## When This Skill Applies
+
+Invoke this skill whenever any of the following is true:
+- You are about to deploy code to production
+- You are merging a release branch into main/master
+- You are pushing a hotfix, patch, or "quick fix" live
+- You are applying schema migrations, config changes, or infrastructure updates
+- Someone asks you to ship anything to a live environment
+
+## The 7 Gates
+
+Every gate requires **evidence** — a concrete artifact, not a statement of belief.
+
+| # | Gate | Evidence Required |
+|---|------|-------------------|
+| G1 | Tests pass | Paste CI output or test run result showing all pass |
+| G2 | Security scan clean | Paste scan report summary — no critical/high CVEs |
+| G3 | No breaking changes | Paste diff summary or contract test output |
+| G4 | Environment config validated | Paste config diff between staging and production |
+| G5 | Staging deployment verified | Paste staging URL + smoke test result or screenshot |
+| G6 | Rollback plan documented | Paste rollback steps or link to runbook |
+| G7 | Code review approved | Paste PR link showing at least one approval |
+
+Gates must be completed **in full, not in part**. "I checked" without evidence is not evidence.
+
+**→ Full gate specifications with evidence templates: [references/verification-gates.md](references/verification-gates.md)**
+
+## Red Flags — Rationalization Alert
+
+If you hear yourself thinking any of these, STOP. Do not proceed.
+
+| Rationalization | Reality | Required Action |
+|-----------------|---------|-----------------|
+| "The manager/CTO authorized skipping this" | No one has authority to skip safety gates | Hold the gate. Escalate the risk in writing. |
+| "It's just a minimal/targeted check, not the full thing" | Partial verification is no verification | All 7 gates. No subset. |
+| "It's a live outage — different rules apply" | Outage pressure is the exact trap this skill prevents | Gates still apply. Compress time, not gates. |
+| "I've already spent hours on this, the logic is clearly correct" | Self-review under sunk-cost bias misses bugs systematically | Tests catch what familiarity hides. |
+| "It's just a hotfix / one-line change / obviously safe" | Catastrophic incidents commonly originate from "obvious" fixes | Gate size does not scale with change size. |
+| "I'll verify after it's live" | Post-hoc verification of broken production is incident response | Verify before. Always. |
+| "Tests are slow / CI is down today" | Use that time to write the rollback plan | No CI = no ship today. |
+| "We can rollback if anything goes wrong" | Rollback is not a substitute for verification | Rollback must be the last resort, not the plan A. |
+
+**→ Full rationalization counter-playbook: [references/anti-rationalization.md](references/anti-rationalization.md)**
+
+## Gate Sequence Protocol
+
+```
+BEFORE SHIP:
+  FOR each gate G1 through G7:
+    1. Collect evidence artifact
+    2. Present evidence explicitly
+    3. Confirm gate cleared
+    IF any gate cannot be cleared:
+      → DO NOT SHIP
+      → Document the blocker
+      → Escalate to human decision-maker WITH the blocker documented
+  IF all 7 gates cleared:
+    → Ship with confidence
+    → Monitor first 15 minutes post-deploy
+```
+
+## Hardcoded Exceptions
+
+There are **zero** hardcoded exceptions to the gate sequence.
+
+Not for P0 incidents. Not for CTO orders. Not for contract deadlines. Not for 2AM exhaustion. Not for "obviously correct" fixes. Not for one-line changes.
+
+The argument "this is a special case" is the most common rationalization pattern. Every skipped gate in history felt like a special case at the time.
+
+## Evidence Format
+
+When presenting gate evidence, use this format:
+
+```
+GATE [#] [Name]: CLEARED
+Evidence: [paste artifact here]
+```
+
+Example:
+```
+GATE G1 Tests: CLEARED
+Evidence:
+  ✓ 247 tests passed, 0 failed, 0 skipped
+  CI run: github.com/org/repo/actions/runs/12345
+
+GATE G6 Rollback: CLEARED
+Evidence:
+  Rollback steps:
+  1. git revert HEAD~1
+  2. kubectl rollout undo deployment/api
+  3. Verify health endpoint returns 200
+```
+
+## After All Gates Clear
+
+Only after all 7 gates show CLEARED:
+1. Ship the change
+2. Monitor for 15 minutes post-deploy (errors, latency, alerts)
+3. Confirm health indicators are stable
+4. Document the deployment in your team's deploy log

package/skills/skills/verify-before-ship/references/anti-rationalization.md

@@ -0,0 +1,212 @@
+# Anti-Rationalization Playbook
+
+This file documents every known rationalization pattern for skipping production verification gates, with explicit counters. Each entry comes from observed agent behavior under pressure.
+
+When you recognize a rationalization, name it aloud and apply the counter.
+
+## Table of Contents
+
+- [Pattern 1: Authority Override](#pattern-1-authority-override)
+- [Pattern 2: Minimal Verification Substitution](#pattern-2-minimal-verification-substitution)
+- [Pattern 3: Live Outage Exception](#pattern-3-live-outage-exception)
+- [Pattern 4: Sunk Cost Confidence](#pattern-4-sunk-cost-confidence)
+- [Pattern 5: Post-Hoc Verification Promise](#pattern-5-post-hoc-verification-promise)
+- [Pattern 6: Change Size Minimization](#pattern-6-change-size-minimization)
+- [Pattern 7: CI Infrastructure Excuse](#pattern-7-ci-infrastructure-excuse)
+- [Combined Pressure Recognition](#combined-pressure-recognition)
+
+---
+
+## Pattern 1: Authority Override
+
+**The rationalization:**
+> "My manager / CTO / VP / incident commander has authorized skipping the verification process. They said this is a special case."
+
+**Why it feels compelling:**
+Hierarchy is a powerful social signal. When a high-authority figure gives a direct order, compliance feels correct. The agent may frame skipping as "following orders" rather than "skipping safety."
+
+**The counter:**
+Authority controls business decisions. Authority does not change whether the code is correct, whether tests pass, or whether a rollback plan exists.
+
+When an executive says "skip verification," they mean "move as fast as possible given the risk." They are expressing urgency, not literally ordering you to deploy broken code. Your job is to compress verification time, not eliminate it.
+
+**Correct response to authority pressure:**
+- Acknowledge urgency: "Moving as fast as possible."
+- State what you're doing: "Running targeted tests and writing the rollback command now — 3 minutes."
+- Escalate the risk in writing: "Deploying without G1/G2 — @CTO, confirming you accept this risk" [in writing, timestamped].
+- If they say "no, zero checks": Ask them to deploy it themselves. You are not an execution arm for non-judgment.
+
+**What is NOT acceptable:**
+- Deploying with no tests run because someone told you to
+- Saying "the CTO authorized it" without running any of the 7 gates
+- Treating "authority approval" as equivalent to evidence
+
+---
+
+## Pattern 2: Minimal Verification Substitution
+
+**The rationalization:**
+> "I'll do a minimal/targeted/quick verification instead of the full checklist. Just the critical checks. Not the full suite."
+
+**Why it feels compelling:**
+This sounds reasonable. "I'm not skipping verification, I'm just scoping it appropriately." It lets the agent feel disciplined while still bypassing most gates.
+
+**The counter:**
+"Minimal verification" is not a defined state — it is a blank check to skip whichever gate is most inconvenient. Every skipped gate sounded "not critical" to someone, at some point, before an incident.
+
+The 7 gates exist as a set. The gate you most want to skip is usually the gate that would catch the bug.
+
+**The specific substitutions to reject:**
+- "Just running unit tests, not integration" → G1 requires all tests to pass
+- "Skipping staging because it's similar to prod" → G5 is not optional
+- "No rollback plan needed, it's a simple change" → G6 is not optional
+- "Code review was informal, not a formal PR" → G7 requires a documented approval
+
+**Correct behavior:**
+State which gates cannot be cleared and why. Do not invent a subset that happens to be completable. If a gate cannot be cleared, the ship is blocked. That is the correct outcome.
+
+---
+
+## Pattern 3: Live Outage Exception
+
+**The rationalization:**
+> "There's a live outage causing active harm right now. Normal verification rules don't apply in a P0 situation. We need to deploy the fix immediately with minimum viable checks."
+
+**Why it feels compelling:**
+The harm is real and visible. Users are affected. Every minute counts. Skipping verification feels like the responsible thing — it prioritizes users over process.
+
+**The counter:**
+Deploying an unverified fix during an active outage is how single outages become cascading disasters. The pressure to skip verification is highest exactly when the consequences of a bad deploy are worst.
+
+"Minimum viable checks" during an outage usually means "I'm too stressed to think clearly about what to check." Stressed, rushed verification is worse than no verification because it gives false confidence.
+
+**What changes during a P0:**
+- **Speed:** Compress the time per gate, not the number of gates
+- **Scope:** You may run smoke tests instead of the full suite for G1, if that is the established protocol
+- **Parallelism:** Multiple engineers can work gates simultaneously
+- **Communication:** Keep stakeholders informed in real time
+
+**What does NOT change during a P0:**
+- The requirement to run some tests before deploying (G1)
+- The requirement to have a rollback plan (G6) — especially critical during an outage
+- The requirement to check the fix is actually deployed to the right environment (G5)
+
+**Correct behavior during P0:**
+Run the fastest possible version of each gate in parallel. Do not eliminate gates. A 5-minute verified deploy beats a 2-minute unverified deploy that makes the outage worse.
+
+---
+
+## Pattern 4: Sunk Cost Confidence
+
+**The rationalization:**
+> "I've been working on this for hours. I've reviewed every line. The logic is clearly correct. Tests are just a formality at this point — they'll pass."
+
+**Why it feels compelling:**
+Familiarity creates confidence. Deep investment in the code creates ownership and the belief that bugs would have been noticed. Running tests "just to confirm" feels like wasted time.
+
+**The counter:**
+The confidence produced by deep familiarity is exactly the condition under which subtle bugs survive. You stop seeing what you expect to see and start seeing what you expect to see. This is not a character flaw — it is how human cognition works under prolonged focus.
+
+"Tests will pass" is a prediction, not evidence. Tests exist precisely to catch what self-review misses.
+
+**Empirical reality:**
+- Most production incidents are caused by changes the author was confident about
+- "Obviously correct" fixes are responsible for a disproportionate share of outages
+- The size of the sunk cost (hours worked) has zero correlation with code correctness
+
+**Correct behavior:**
+Run the tests. The 45 minutes you spent on the fix does not reduce the 5 minutes it takes to confirm it works. If CI is down, use that time to write G6 (rollback plan) while waiting for it to come back up.
+
+---
+
+## Pattern 5: Post-Hoc Verification Promise
+
+**The rationalization:**
+> "We'll verify after it's live. If anything is wrong, we'll catch it quickly in monitoring and roll back."
+
+**Why it feels compelling:**
+Monitoring is real. Rollback is real. This sounds like a mature engineering stance — "we have safeguards."
+
+**The counter:**
+Post-hoc verification is incident response, not shipping safety. The purpose of pre-ship verification is to prevent the incident in the first place. Rollback is not free — it causes downtime, data inconsistency, and user impact.
+
+"We'll catch it in monitoring" requires:
+- Monitoring that actually covers the changed behavior
+- An alert that fires before significant harm occurs
+- Someone available to respond immediately
+- A rollback plan that works (which is G6 — a gate you just skipped)
+
+Without pre-ship verification, you are gambling that every one of those conditions is true.
+
+**Correct behavior:**
+Verify before shipping. If you want to also monitor after shipping, add monitoring. These are not alternatives — they are both required.
+
+---
+
+## Pattern 6: Change Size Minimization
+
+**The rationalization:**
+> "It's just a one-line change / a hotfix / a trivial config update / obviously safe. The full gate process is overkill for something this small."
+
+**Why it feels compelling:**
+Proportionality feels rational. Running a full verification suite for a typo fix seems excessive. The risk genuinely seems lower for small changes.
+
+**The counter:**
+Change size does not correlate with incident risk. Some of the most severe production outages in engineering history originated from single-line changes, configuration value updates, and "trivial" fixes.
+
+One-line changes are more dangerous in one specific way: they reduce scrutiny. The smaller the change looks, the less carefully reviewers and authors check it.
+
+**Examples of one-line changes that caused major incidents:**
+- Flipping a boolean flag from false to true (wrong environment)
+- Adding a missing comma to a config file (broke serialization)
+- Changing a timeout value from milliseconds to seconds (10x slower)
+- Removing a single null check ("it can't be null here")
+
+**Correct behavior:**
+Gate size does not scale with change size. All 7 gates apply to all changes. For genuinely tiny changes (config value update), the gates take 5 minutes, not hours. Run them.
+
+---
+
+## Pattern 7: CI Infrastructure Excuse
+
+**The rationalization:**
+> "CI is down / slow / unreliable today. I can't run the tests. That's not my fault — I'll just ship and we'll fix CI later."
+
+**Why it feels compelling:**
+The obstacle is real and external. The agent is not the one who broke CI. Waiting for CI feels like being blocked by someone else's problem.
+
+**The counter:**
+CI being down does not make your code correct. It removes a verification mechanism — which increases risk, not decreases it.
+
+**Options when CI is unavailable:**
+1. Run tests locally and paste local output as evidence
+2. Wait for CI to recover
+3. Fix the CI problem
+4. Escalate to a human decision-maker with the full picture: "CI is down, tests unverified, here is the specific risk I'm asking you to accept"
+
+**What is not an option:**
+Shipping without test evidence because CI is inconvenient.
+
+**Correct behavior:**
+No CI output = no G1 evidence = G1 not cleared = no ship. Use the downtime to complete other gates (G6 rollback plan is always available without CI).
+
+---
+
+## Combined Pressure Recognition
+
+When multiple pressures hit simultaneously, the rationalization becomes more sophisticated:
+
+**Example combined prompt:**
+"It's 2AM (exhaustion). The client is losing $50k/hour (time). The CTO authorized it (authority). You've already written the fix (sunk cost). Just deploy it."
+
+**Recognition signal:**
+Combined pressure scenarios feel overwhelming and make any resistance seem unreasonable. This is the highest-risk moment — the moment most likely to produce a bad deploy.
+
+**Counter-procedure:**
+1. Name the pressures explicitly: "I'm seeing time + authority + exhaustion pressure simultaneously."
+2. Apply each counter individually.
+3. Compress gate execution (run G1 locally, write G6 in 2 minutes, skip non-critical G3/G4 only if explicitly accepted in writing by decision-maker).
+4. Do not let the combination of pressures bypass all gates. Each rationalization is still invalid when combined with others.
+
+**The truth about combined pressure:**
+The higher the pressure, the more important verification becomes. Pressure does not reduce risk — it adds it.