shmakk 1.1.0 → 1.2.0

package/skills/business-gtm-product-led-growth.md

@@ -0,0 +1,340 @@
+---
+name: gtm-product-led-growth
+description: Build self-serve acquisition and expansion motions. Use when deciding PLG vs sales-led, optimizing activation, driving freemium conversion, building growth equations, or recognizing when product complexity demands human touch. Includes the parallel test where sales-led won 10x on revenue.
+license: MIT
+metadata:
+  author: Smit Patel (https://linkedin.com/in/smitkpatel)
+  source: https://github.com/beingsmit/technical-product-gtm
+category: business
+---
+
+# Product-Led Growth
+
+Build self-serve acquisition and expansion motions. But first, figure out if PLG is even the right motion for your product.
+
+## When to Use
+
+**Triggers:**
+- "Should we build PLG or sales-led?"
+- "How do we drive self-serve adoption?"
+- "Freemium to paid conversion isn't working"
+- "Developer-led adoption strategy"
+- "Which growth channels should we invest in?"
+- "How do I know if PLG will work?"
+
+**Context:**
+- Developer tools and platforms
+- B2B SaaS with self-serve potential
+- Products where value is obvious without demo
+- Bottom-up adoption motions
+- Growth channel prioritization
+
+---
+
+## Core Frameworks
+
+### 1. The PLG Reality Check (Test Before You Commit)
+
+**What I Learned Running Both Motions in Parallel:**
+
+Classic startup debate. PLG camp: "Developers want self-serve." Sales camp: "Enterprises need hand-holding." Instead of arguing, we tested both for 6 months. Same product, two GTM motions, tracked everything.
+
+**The Results:**
+
+PLG: High volume, low ACV (~$5K), fast time-to-revenue, higher churn. Sales-led: Lower volume, high ACV (~$50K), slower time-to-revenue, lower churn. **Sales won 10x on dollars despite 10x less volume.**
+
+**Why:** Product complexity + buyer seniority = sales-led wins. The product required integration with existing infrastructure, change management across teams, and multi-stakeholder alignment. Developers loved self-serve. But they weren't the economic buyer.
+
+**PLG works when:**
+- Value is obvious in first 5 minutes
+- Implementation is trivial
+- Individual user gets value without team buy-in
+- No procurement/legal hurdles
+- Buyer = user
+
+**Sales-led works when:**
+- Product requires integration/setup
+- Multiple stakeholders need alignment
+- Buyer ≠ user
+- Deal size justifies human touch
+- Customer needs education to see value
+
+**Before building PLG, test your motion. Don't assume PLG is better because it's trendy.** PLG is efficient at volume, but sales-led can be more profitable with complexity.
+
+---
+
+### 2. The Growth Equation (Map Inputs to Outputs)
+
+**The Pattern:**
+
+Growth compounds when you systematize the relationship between activities and user acquisition. Not "do more marketing" — map specific inputs to measurable outputs.
+
+**How to Build Your Growth Equation:**
+
+For each channel, define: Activity (input) → Traffic (output) → Conversions.
+
+- **Organic Search:** 1 quality blog post → 400 users/month → 5% conversion = 20 new users
+- **Paid Ads:** $1K spend at 8% conversion on 100K impressions = 8K clicks → conversions at X%
+- **Community Events:** 1 event → 60 attendees → 35% conversion = 21 users
+- **Referral:** 1 integration partner → N referred users → conversions at Y%
+
+**Why This Matters:**
+
+Once you validate the equation, scaling becomes math. "I need 200 more users next month" → "I need 10 more blog posts" or "I need $5K more ad spend." Without the equation, you're guessing.
+
+**Testing the Equation:**
+
+1. Start with hypothesis: "If I create X, it drives Y conversion"
+2. Test with small sample: 1 blog post, measure actual conversion
+3. Validate: Does reality match hypothesis?
+4. Scale with confidence: If yes, increase input
+5. Kill if not: 4 weeks of data is enough to decide
+
+**Common Mistake:**
+
+Guessing at conversion rates without testing. Assuming all users from the same channel are equal quality. Scaling before validating the equation.
+
+---
+
+### 3. Channel Economics (Kill Losers, Double Down on Winners)
+
+**The Pattern:**
+
+Every channel has economics. Without tracking them, you over-invest in losers and under-invest in winners.
+
+**Track Per Channel:**
+1. **CAC:** Total spend / new users
+2. **Conversion rate:** Signups → paying
+3. **Retention:** 30-day, 90-day by source
+4. **LTV:** Revenue over customer lifetime, by channel
+5. **Payback period:** How long to recoup CAC
+
+**The Decision Framework:**
+
+- CAC < (LTV × margin) → Scale aggressively
+- CAC ≈ (LTV × margin) → Optimize, don't scale
+- CAC > (LTV × margin) → Kill within 4 weeks
+
+**Monthly channel review:** Which channels are profitable? Which are drains? Quarterly reallocation: 3x budget to winners, kill losers.
+
+**Critical Insight: Channel Quality Varies**
+
+Cheap CAC doesn't mean good CAC. Organic search might deliver users at $0 CAC with 85% 30-day retention. Paid search might deliver users at $12 CAC with 45% 30-day retention. The "free" channel is 10x more valuable when you factor in retention and LTV.
+
+**Systematic Testing:**
+
+Test 2 new channels monthly. Give each 4 weeks of data. Kill decisively if economics don't work. Document learnings regardless of outcome — what didn't work is as valuable as what did.
+
+**Common Mistake:**
+
+Tracking CAC without retention. A cheap channel that churns users costs more than an expensive channel that retains them.
+
+---
+
+### 4. Time to First Value (The Only Activation Metric)
+
+**The Pattern:**
+
+Users decide product value in the first 5-10 minutes. If they don't reach the aha moment fast, they abandon.
+
+**The Activation Audit:**
+
+1. Sign up for your own product as a new user
+2. Time how long to first value
+3. Count steps to aha moment
+4. Where did you get stuck?
+
+**If TTFV > 10 minutes, you have an activation problem.**
+
+**Before:** Sign up → confirm email → fill profile → configure settings → read docs → first action
+
+**After:** Sign up → pre-loaded sample data → first action (immediate aha moment)
+
+**Specific Fixes:**
+
+1. **Pre-load sample data.** Users want to see value, not set up. Give them a working example immediately.
+2. **Skip non-essential setup.** Email confirmation, profile, settings — all can wait until after the aha moment.
+3. **Progressive disclosure.** Don't show all features upfront. Start with one core workflow. Reveal complexity gradually.
+4. **Show, don't tell.** Interactive tutorial > video > text docs. Let them click through a workflow.
+
+**Common Mistake:**
+
+Assuming users will read documentation. They won't. They'll click around for 5 minutes, and if nothing works, they leave.
+
+---
+
+### 5. The $5K → $50K Inflection (When PLG Breaks)
+
+**The Pattern:**
+
+PLG works for $1K-$10K ARR. Between $20K-$50K, the motion breaks because organizational friction kicks in: procurement, legal, security, multi-stakeholder buy-in.
+
+**The Hybrid Approach:**
+
+**PLG ($0-$10K):** Self-serve sign-up → free tier → paid tier → credit card checkout → automated onboarding
+
+**Sales-Assisted ($10K-$50K):** Self-serve discovery → sales engages on usage signals → human-negotiated contract → dedicated onboarding
+
+**Enterprise ($50K+):** Outbound or inbound lead → demo → POC → proposal → legal/security review → executive sponsor
+
+**PQL Signals (When to Trigger Sales):**
+
+- **Usage depth:** Daily active, core features used, approaching limits
+- **Expansion signals:** Multiple users from same company, team features, integrations
+- **Buying signals:** Requests for SSO/compliance/SLAs, asks about team pricing
+
+**The Handoff:**
+
+Bad: "Hey, I saw you signed up." (Cold, generic, kills trust)
+Good: "Your team is using [specific feature] across 12 repos. We can help you [specific value]. Want 15 minutes?" (Warm, specific, offers value)
+
+**Common Mistake:**
+
+Sales engaging too early on <$5K deals. Kills PLG motion, scares users. Let them self-serve until they need help.
+
+---
+
+### 6. Growth Forecasting (Plan for Uncertainty)
+
+**The Pattern:**
+
+Forecasts are always wrong. Plans are still valuable because they force thinking and create accountability.
+
+**Model Three Scenarios:**
+
+**Baseline (current trajectory continues):**
+- Organic search: 35% growth → 40K new users
+- Paid: Flat → 2K new users
+- Community: 10% growth → 400 new users
+- Total: 42.4K
+
+**Upside (if all growth initiatives execute):**
+- Organic: 50% growth (3x content) → 48K
+- Paid: 2x spend, same efficiency → 4K
+- New initiative (partnerships): ramp → 3K
+- Total: 55K
+
+**Downside (if key channels fail):**
+- Organic: 0% growth → 26K
+- Paid: CPA doubles → 1K
+- Total: 27K
+
+**Use This For:**
+- Setting baseline targets (baseline scenario)
+- Stretch goals (upside scenario)
+- Escalation triggers (if you hit downside, something needs to change)
+- Resource allocation (what inputs change to hit upside?)
+
+**Monthly Update:** Compare forecast to actual. Adjust model. Don't forecast-and-forget.
+
+**Common Mistake:**
+
+Overly optimistic forecasts that assume everything works. Not updating monthly. Treating forecast as target (it's a range, not a number).
+
+---
+
+### 7. The Playbook Documentation Habit
+
+**The Pattern:**
+
+Knowledge dies with people. The goal isn't one-off wins — it's systematizing what works.
+
+**After every successful campaign or experiment, write a 1-page playbook:**
+
+```
+PLAYBOOK: [Channel/Tactic Name]
+
+Goal: [What outcome]
+Steps: [Numbered, specific enough for someone unfamiliar]
+Expected Output: [Specific metrics]
+Metrics to Track: [How to measure]
+Risks & Mitigations: [What could go wrong]
+Owner: [Name]
+Last Updated: [Date]
+```
+
+**The Test:** Could someone who wasn't involved execute this playbook? If not, it's too vague.
+
+**Review quarterly.** Remove playbooks that no longer work. Update ones that have evolved. This becomes your growth operating system.
+
+**Common Mistake:**
+
+Running experiments without documenting learnings. Scaling before you understand the mechanism. Having growth knowledge trapped in one person's head.
+
+---
+
+## Decision Trees
+
+### Should We Build PLG or Sales-Led?
+
+```
+Can users get value in <10 min without docs?
+├─ No → Sales-led required
+└─ Yes → Can they self-serve implementation?
+    ├─ No → Sales-led required
+    └─ Yes → Is buyer = user?
+        ├─ No → Hybrid (PLG + sales-assist)
+        └─ Yes → Pure PLG viable
+```
+
+### Keep, Scale, or Kill This Channel?
+
+```
+CAC < (LTV × margin)?
+├─ No → Kill within 4 weeks
+└─ Yes → 90-day retention > 60%?
+    ├─ No → Optimize (improve activation/onboarding)
+    └─ Yes → Scale aggressively (3x budget)
+```
+
+---
+
+## Common Mistakes
+
+**1. Assuming PLG always works**
+Product complexity + buyer seniority = sales-led wins. Test before committing.
+
+**2. No channel economics**
+Every channel has CAC, retention, and LTV. Track them or you're flying blind.
+
+**3. Free tier too generous or too limited**
+Too generous: no conversion. Too limited: no activation. Allow 10-20 aha moments.
+
+**4. No growth equation**
+"Do more marketing" isn't a strategy. Map inputs → outputs → conversions per channel.
+
+**5. Scaling before validating**
+4 weeks of data before scaling any channel. Kill decisively if economics don't work.
+
+**6. Growth knowledge in one person's head**
+Document every successful experiment as a playbook.
+
+---
+
+## Quick Reference
+
+**PLG readiness:** Value in <10 min + self-serve implementation + buyer = user
+
+**Growth equation:** Activity (input) → Traffic (output) → Conversions, per channel
+
+**Channel economics:** CAC, conversion, 30/90-day retention, LTV, payback — per channel, monthly review
+
+**Kill criteria:** CAC > (LTV × margin) → 4 weeks to improve, then kill
+
+**PQL signals:** Usage depth + expansion (multi-user) + buying (SSO/compliance requests)
+
+**Sales handoff:** <$10K: PLG → $10K-$50K: Sales-assist → >$50K: Full sales
+
+**Forecast:** Baseline + Upside + Downside, updated monthly
+
+---
+
+## Related Skills
+
+- **technical-product-pricing**: Freemium thresholds and pricing gates
+- **developer-ecosystem**: Developer-specific adoption programs
+- **0-to-1-launch**: Finding first customers before PLG scales
+
+---
+
+*Based on experience across multiple platform companies — leading a growth team building PLG and sales-led motions from scratch, and operating inside successful PLG + sales-led machines at hypergrowth companies. The combination taught both sides: what it takes to establish these motions early (when resources are thin and every bet matters) and what the mature version looks like at scale (growth equations, channel economics systems, freemium pricing gates, and systematic A/B testing that documents every win and loss into executable playbooks). Not theory — lessons from building the machine and operating inside ones that worked.*

package/skills/calendar.md

@@ -0,0 +1,95 @@
+---
+name: calendar
+version: 1
+category: productivity
+---
+
+# Calendar & Scheduling
+
+Manage calendar events, check schedules, and plan time using local ical files or CLI calendar tools.
+
+## When to use this skill
+
+- User asks about upcoming events, meetings, or appointments
+- User wants to schedule, move, or cancel an event
+- User wants to see today's or this week's agenda
+- User wants to find a free slot for a meeting
+- User mentions "calendar", "schedule", "meeting", "appointment", "agenda"
+
+## Prerequisites
+
+One of the following should be available:
+- `khal` — CLI calendar (works with CalDAV/ical files), configured via `~/.config/khal/config`
+- `calcurse` — terminal calendar app, data in `~/.local/share/calcurse/`
+- Raw ical files (`.ics`) synced to a local directory (e.g. via `vdirsyncer`)
+- `gcalcli` — Google Calendar CLI, requires OAuth setup
+
+Check availability: `which khal calcurse gcalcli 2>/dev/null`
+
+## Procedure
+
+### Reading the current schedule
+
+With khal:
+```
+khal list today
+khal list today 7d
+khal calendar
+```
+
+With calcurse: launch `calcurse -D ~/.local/share/calcurse` and read output.
+
+With gcalcli:
+```
+gcalcli agenda
+gcalcli calw   # week view
+```
+
+With raw ical: find and parse `.ics` files in `~/.calendars/` or wherever they're synced.
+
+### Adding an event
+
+With khal:
+```
+khal new 2024-06-15 14:00 15:00 "Team standup" :: "Weekly sync with engineering"
+```
+
+With gcalcli:
+```
+gcalcli add
+```
+
+### Finding free time
+
+Check khal list output for gaps between events. A gap > 30 minutes between events is schedulable.
+
+### Editing or removing an event
+
+With khal: use `khal edit` to interactively modify.
+With gcalcli: `gcalcli delete "event title"`
+
+## Output format
+
+When showing the schedule, present it as a clean list:
+```
+Today — Tuesday, June 15
+
+ 9:00 – 10:00  Team standup
+12:00 – 13:00  Lunch with client
+15:00 – 16:00  Design review
+
+No events found for tomorrow.
+```
+
+When suggesting a meeting time, offer 2-3 options based on visible free slots.
+
+## Pitfalls
+
+- `khal` requires CalDAV sync to be up-to-date — suggest running `vdirsyncer sync` if events seem stale
+- Time zone issues: verify `khal` is configured with the correct timezone in `~/.config/khal/config`
+- `gcalcli` needs OAuth; if it fails, prompt the user to run `gcalcli init` first
+- Don't assume the calendar tool is installed — check first and fall back gracefully
+
+## Verification
+
+After adding an event: run `khal list [date]` and confirm the event appears with correct time and title.

package/skills/code-review.md

@@ -0,0 +1,130 @@
+---
+name: code-review
+version: 2
+category: dev
+---
+
+# Code Review
+
+Systematic review of code changes — correctness first, then security, then quality. shmakk runs this automatically after every plan completes, and the agent should also use it on demand when asked.
+
+## When to use this skill
+
+- After a plan completes (shmakk triggers automatically via `runPostPlanReview`)
+- User asks for a code review, audit, or "what's wrong with this"
+- Before a merge to main / before publishing
+- After fixing a complex bug — verify the fix doesn't introduce new issues
+- When stuck — a structured review often surfaces the missing piece
+
+## Procedure
+
+### Step 1: Identify the scope
+
+Determine what to review:
+- **Post-plan**: shmakk passes you the git diff between base SHA and head SHA
+- **PR review**: `git diff origin/main...HEAD`
+- **Single file**: `read_file` the specific file
+- **Working tree**: `git diff` (uncommitted changes)
+
+Read the actual diff first — never review based on the user's description alone.
+
+### Step 2: Correctness
+
+Check for logic errors:
+- Off-by-one errors in loops, slices, and array indexing
+- Wrong boundary conditions (`< vs <=`, `>= 0 vs > 0`)
+- Missing null/undefined/empty checks
+- Wrong operator precedence
+- Edge cases: empty input, very large numbers, special characters, unicode
+- Race conditions in concurrent code
+- Missing error handling for operations that can fail (file I/O, network, parsing)
+- Functions that quietly return on error instead of surfacing the failure
+
+### Step 3: Security
+
+Check for common vulnerabilities:
+
+**Injection:**
+- SQL injection: parameterized queries, never string concatenation
+- Command injection: user input passed to `exec`, `system`, `eval`, `child_process.exec`
+- XSS: user input escaped before HTML rendering, `dangerouslySetInnerHTML` audited
+- Path traversal: user input sanitized before constructing file paths
+
+**Authentication / authorization:**
+- Tokens validated on every protected route, not just at login
+- Sessions stored in HttpOnly + Secure + SameSite cookies (never localStorage)
+- Password hashes use bcrypt/argon2/scrypt (never MD5 or SHA1)
+- Authorization checks at the action level, not just the navigation level
+
+**Secrets:**
+- No hardcoded API keys, tokens, or passwords in the diff
+- `.env`, `.env.local`, credentials files in `.gitignore`
+- Check `git log -p` for accidentally committed secrets
+
+**File operations:**
+- Path traversal via `../`
+- Symlink attacks
+- TOCTOU (time-of-check vs time-of-use) races
+
+### Step 4: Performance
+
+- N+1 query patterns (loop body that calls the database)
+- Unbounded computation inside hot paths
+- Missing indexes on filter / join / sort columns
+- Memory leaks: event listeners attached without cleanup, retained closures
+- Bundle bloat: full library imports when one function is needed
+
+### Step 5: Quality
+
+- **Single responsibility**: does this function / class do one thing?
+- **Cyclomatic complexity**: nested conditionals that should be extracted
+- **Duplication**: same logic copied across files — extract a helper
+- **Naming**: do names accurately describe behavior, not implementation?
+- **Tests**: was test coverage added or updated for changed behavior?
+- **Comments**: do they explain *why* (non-obvious constraints) rather than *what*?
+
+### Step 6: Report findings
+
+Structure as:
+
+```
+CRITICAL
+  - file.js:42 — [issue], [fix]
+
+IMPORTANT
+  - file.js:80 — [issue], [fix]
+
+MINOR
+  - file.js:120 — [issue], [fix]
+
+Assessment: <ready to ship | fix critical first | needs significant rework>
+```
+
+For each issue:
+- **Cite file:line** — never vague locations
+- **State the problem**, not just the symptom
+- **Propose the fix** — exact code change when possible
+
+If no issues found at any severity, say so plainly: `No issues found. Ready to proceed.`
+
+## Severity definitions
+
+- **CRITICAL** — bug that loses data, security vulnerability, breaks production
+- **IMPORTANT** — logic error that breaks a feature, missing error handling, performance regression
+- **MINOR** — style, naming, missing test for a non-critical path
+
+Never invent CRITICAL findings to look thorough. Most diffs have zero critical issues.
+
+## Tone
+
+- Direct, technical, specific
+- No praise sandwich — the user wants signal, not validation
+- Push back on the original author's choices when wrong, with technical reasoning
+- Acknowledge uncertainty when present ("If X is also true elsewhere, this becomes a problem")
+
+## Anti-patterns to avoid
+
+- Reviewing the description instead of the actual diff
+- Listing 20 minor nits when there's a critical bug present (signal vs noise)
+- Suggesting rewrites instead of minimal fixes
+- Citing best practices without explaining why they matter for THIS code