kodelyth-ecc 1.2.0

package/skills/skill-stocktake/scripts/scan.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+# scan.sh — enumerate skill files, extract frontmatter and UTC mtime
+# Usage: scan.sh [CWD_SKILLS_DIR]
+# Output: JSON to stdout
+#
+# When CWD_SKILLS_DIR is omitted, defaults to $PWD/.claude/skills so the
+# script always picks up project-level skills without relying on the caller.
+#
+# Environment:
+#   SKILL_STOCKTAKE_GLOBAL_DIR   Override ~/.claude/skills (for testing only;
+#                                do not set in production — intended for bats tests)
+#   SKILL_STOCKTAKE_PROJECT_DIR  Override project dir detection (for testing only)
+
+set -euo pipefail
+
+GLOBAL_DIR="${SKILL_STOCKTAKE_GLOBAL_DIR:-$HOME/.claude/skills}"
+CWD_SKILLS_DIR="${SKILL_STOCKTAKE_PROJECT_DIR:-${1:-$PWD/.claude/skills}}"
+# Path to JSONL file containing tool-use observations (optional; used for usage frequency counts).
+# Override via SKILL_STOCKTAKE_OBSERVATIONS env var if your setup uses a different path.
+OBSERVATIONS="${SKILL_STOCKTAKE_OBSERVATIONS:-$HOME/.claude/observations.jsonl}"
+
+# Validate CWD_SKILLS_DIR looks like a .claude/skills path (defense-in-depth).
+# Only warn when the path exists — a nonexistent path poses no traversal risk.
+if [[ -n "$CWD_SKILLS_DIR" && -d "$CWD_SKILLS_DIR" && "$CWD_SKILLS_DIR" != */.claude/skills* ]]; then
+  echo "Warning: CWD_SKILLS_DIR does not look like a .claude/skills path: $CWD_SKILLS_DIR" >&2
+fi
+
+# Extract a frontmatter field (handles both quoted and unquoted single-line values).
+# Does NOT support multi-line YAML blocks (| or >) or nested YAML keys.
+extract_field() {
+  local file="$1" field="$2"
+  awk -v f="$field" '
+    BEGIN { fm=0 }
+    /^---$/ { fm++; next }
+    fm==1 {
+      n = length(f) + 2
+      if (substr($0, 1, n) == f ": ") {
+        val = substr($0, n+1)
+        gsub(/^"/, "", val)
+        gsub(/"$/, "", val)
+        print val
+        exit
+      }
+    }
+    fm>=2 { exit }
+  ' "$file"
+}
+
+# Get UTC timestamp N days ago (supports both macOS and GNU date)
+date_ago() {
+  local n="$1"
+  date -u -v-"${n}d" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null ||
+  date -u -d "${n} days ago" +%Y-%m-%dT%H:%M:%SZ
+}
+
+# Count observations matching a file path since a cutoff timestamp
+count_obs() {
+  local file="$1" cutoff="$2"
+  if [[ ! -f "$OBSERVATIONS" ]]; then
+    echo 0
+    return
+  fi
+  jq -r --arg p "$file" --arg c "$cutoff" \
+    'select(.tool=="Read" and .path==$p and .timestamp>=$c) | 1' \
+    "$OBSERVATIONS" 2>/dev/null | wc -l | tr -d ' '
+}
+
+# Scan a directory and produce a JSON array of skill objects
+scan_dir_to_json() {
+  local dir="$1"
+  local c7 c30
+  c7=$(date_ago 7)
+  c30=$(date_ago 30)
+
+  local tmpdir
+  tmpdir=$(mktemp -d)
+  # Use a function to avoid embedding $tmpdir in a quoted string (prevents injection
+  # if TMPDIR were crafted to contain shell metacharacters).
+  local _scan_tmpdir="$tmpdir"
+  _scan_cleanup() { rm -rf "$_scan_tmpdir"; }
+  trap _scan_cleanup RETURN
+
+  # Pre-aggregate observation counts in two passes (one per window) instead of
+  # calling jq per-file — reduces from O(n*m) to O(n+m) jq invocations.
+  local obs_7d_counts obs_30d_counts
+  obs_7d_counts=""
+  obs_30d_counts=""
+  if [[ -f "$OBSERVATIONS" ]]; then
+    obs_7d_counts=$(jq -r --arg c "$c7" \
+      'select(.tool=="Read" and .timestamp>=$c) | .path' \
+      "$OBSERVATIONS" 2>/dev/null | sort | uniq -c)
+    obs_30d_counts=$(jq -r --arg c "$c30" \
+      'select(.tool=="Read" and .timestamp>=$c) | .path' \
+      "$OBSERVATIONS" 2>/dev/null | sort | uniq -c)
+  fi
+
+  local i=0
+  while IFS= read -r file; do
+    local name desc mtime u7 u30 dp
+    name=$(extract_field "$file" "name")
+    desc=$(extract_field "$file" "description")
+    mtime=$(date -u -r "$file" +%Y-%m-%dT%H:%M:%SZ)
+    # Use awk exact field match to avoid substring false-positives from grep -F.
+    # uniq -c output format: "   N /path/to/file" — path is always field 2.
+    u7=$(echo "$obs_7d_counts" | awk -v f="$file" '$2 == f {print $1}' | head -1)
+    u7="${u7:-0}"
+    u30=$(echo "$obs_30d_counts" | awk -v f="$file" '$2 == f {print $1}' | head -1)
+    u30="${u30:-0}"
+    dp="${file/#$HOME/~}"
+
+    jq -n \
+      --arg path "$dp" \
+      --arg name "$name" \
+      --arg description "$desc" \
+      --arg mtime "$mtime" \
+      --argjson use_7d "$u7" \
+      --argjson use_30d "$u30" \
+      '{path:$path,name:$name,description:$description,use_7d:$use_7d,use_30d:$use_30d,mtime:$mtime}' \
+      > "$tmpdir/$i.json"
+    i=$((i+1))
+  done < <(find "$dir" -name "*.md" -type f 2>/dev/null | sort)
+
+  if [[ $i -eq 0 ]]; then
+    echo "[]"
+  else
+    jq -s '.' "$tmpdir"/*.json
+  fi
+}
+
+# --- Main ---
+
+global_found="false"
+global_count=0
+global_skills="[]"
+
+if [[ -d "$GLOBAL_DIR" ]]; then
+  global_found="true"
+  global_skills=$(scan_dir_to_json "$GLOBAL_DIR")
+  global_count=$(echo "$global_skills" | jq 'length')
+fi
+
+project_found="false"
+project_path=""
+project_count=0
+project_skills="[]"
+
+if [[ -n "$CWD_SKILLS_DIR" && -d "$CWD_SKILLS_DIR" ]]; then
+  project_found="true"
+  project_path="$CWD_SKILLS_DIR"
+  project_skills=$(scan_dir_to_json "$CWD_SKILLS_DIR")
+  project_count=$(echo "$project_skills" | jq 'length')
+fi
+
+# Merge global + project skills into one array
+all_skills=$(jq -s 'add' <(echo "$global_skills") <(echo "$project_skills"))
+
+jq -n \
+  --arg global_found "$global_found" \
+  --argjson global_count "$global_count" \
+  --arg project_found "$project_found" \
+  --arg project_path "$project_path" \
+  --argjson project_count "$project_count" \
+  --argjson skills "$all_skills" \
+  '{
+    scan_summary: {
+      global: { found: ($global_found == "true"), count: $global_count },
+      project: { found: ($project_found == "true"), path: $project_path, count: $project_count }
+    },
+    skills: $skills
+  }'

package/skills/smart-debug/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: smart-debug
+description: Systematic debugging methodology — powered by Kodelyth. A step-by-step framework to diagnose any bug confidently across any language or framework. Prevents guess-and-check debugging, traces errors to their root cause, and produces a fix backed by evidence.
+origin: Kodelyth
+---
+
+# Smart Debug — Systematic Debugging Methodology
+
+A structured approach to debugging that works for any language, framework, or error type. Powered by Kodelyth.
+
+## When to Use
+
+- You have a bug that isn't obviously caused by the last change you made
+- You've tried a fix and it didn't work (or broke something else)
+- The error message is cryptic or misleading
+- The bug is intermittent or environment-specific
+- You're not sure where in the codebase the problem originates
+
+## How It Works
+
+Smart Debug applies the same process a seasoned senior engineer uses — but makes it explicit and repeatable. The core idea: **symptoms are not root causes**. Every step narrows the search space until you know exactly why the bug exists.
+
+## The 5-Step Framework
+
+### Step 1 — Characterize the Bug
+
+Before touching any code, answer these questions:
+
+```
+1. What is the exact error message or symptom? (copy it verbatim)
+2. Is it consistent or intermittent?
+3. What triggers it? (specific action, data input, timing, environment)
+4. When did it start? (after a code change, deployment, dependency update?)
+5. Where does it appear? (local only, staging, prod, specific browser/OS?)
+```
+
+This step alone eliminates 30% of debugging time by ruling out non-issues.
+
+### Step 2 — Read the Error, Not Just the Message
+
+Error messages have structure. Parse them:
+
+```
+[Error Type]: [Message]
+  at [function] ([file]:[line]:[column])
+  at [caller] ([file]:[line]:[column])
+  ...
+```
+
+**Read from the bottom of the stack trace up.** The bottom is the root call; the top is where it crashed.
+
+Find the **first line that references your own code** — that is your entry point.
+
+```bash
+# Common error classifications:
+TypeError           → wrong type passed, null/undefined accessed
+ReferenceError      → variable not defined or out of scope
+SyntaxError         → code can't be parsed (often a typo or missing bracket)
+RangeError          → value out of allowed range (infinite recursion, etc.)
+NetworkError / 4xx  → bad request — check what you're sending
+NetworkError / 5xx  → server crash — check server logs
+CORS Error          → origin policy mismatch — check headers
+Promise rejection   → async error not caught — check the chain above
+```
+
+### Step 3 — Form ONE Hypothesis
+
+Before running any code, state a hypothesis:
+
+```
+Hypothesis: The bug happens because [specific, technical reason].
+Evidence for this: [what in the code or logs suggests this].
+How to test: [what I will check or change to confirm/deny].
+```
+
+Only work one hypothesis at a time. If your test disproves it, form a new hypothesis — do not patch and pray.
+
+### Step 4 — Gather Evidence
+
+Check each source of truth in order:
+
+**A. The error site**
+```bash
+# Read 30 lines around the crash location
+# Understand what data was expected vs what arrived
+```
+
+**B. Recent changes**
+```bash
+git log --oneline -10 -- path/to/affected/file
+git diff HEAD~3 -- path/to/affected/file
+```
+
+**C. Data flowing in**
+```bash
+# Add a temporary log just before the crash
+console.log('DEBUG value at crash point:', variableName)
+# What does it actually contain vs what you expected?
+```
+
+**D. All callers**
+```bash
+grep -rn "functionName\|ClassName" src/
+# Is anyone calling this incorrectly?
+```
+
+**E. Dependencies / environment**
+```bash
+# Has a package version changed?
+git diff HEAD~10 package-lock.json | grep '"version"'
+
+# Is an env variable missing?
+echo $MY_VARIABLE
+```
+
+### Step 5 — Fix and Verify
+
+Once you've confirmed the root cause:
+
+1. **Make the minimal fix** — change only what's needed to address the root cause
+2. **Explain why it works** — if you can't explain it, you don't understand it yet
+3. **Test the fix** — reproduce the original symptom, confirm it's gone
+4. **Test adjacent behavior** — did the fix break anything nearby?
+5. **Add a regression test** — so this bug can never silently return
+
+```typescript
+// Before fix (document what was wrong)
+// BUG: user.profile could be undefined when user is a guest account
+const name = user.profile.name  // crashes for guest users
+
+// After fix (document why this is correct)
+// FIXED: optional chaining handles guest accounts (profile is null for guests)
+const name = user.profile?.name ?? 'Guest'
+```
+
+## Language-Specific Debugging Tips
+
+### TypeScript / JavaScript
+
+```typescript
+// Check for undefined at runtime even when types say it's safe
+console.log(typeof value, value)
+
+// Trace async errors to their source
+async function riskyOp() {
+  try {
+    return await fetch(url)
+  } catch (e) {
+    console.error('[riskyOp] failed:', e.message, { url })
+    throw e  // re-throw so caller knows it failed
+  }
+}
+
+// Find stale closure bugs
+useEffect(() => {
+  console.log('effect ran with:', { count, userId }) // log deps
+}, [count, userId])
+```
+
+### Python
+
+```python
+# Print full traceback, not just the last line
+import traceback
+try:
+    risky_call()
+except Exception as e:
+    traceback.print_exc()
+
+# Check types at runtime
+print(type(value), repr(value))
+
+# Isolate in a REPL
+python3 -c "from module import func; print(func(test_input))"
+```
+
+### Go
+
+```go
+// Always check error values
+result, err := someOperation()
+if err != nil {
+    log.Printf("someOperation failed: %v (input: %+v)", err, input)
+    return nil, fmt.Errorf("someOperation: %w", err)
+}
+
+// Use fmt.Sprintf for complex struct inspection
+fmt.Printf("value: %+v\n", myStruct)
+```
+
+### SQL / Database
+
+```sql
+-- Run the query manually with the exact values from the bug
+-- EXPLAIN ANALYZE to see query plan
+EXPLAIN ANALYZE SELECT * FROM users WHERE id = 123;
+
+-- Check for NULL propagation
+SELECT COALESCE(column_name, 'DEFAULT') FROM table;
+
+-- Check constraint violations
+SELECT * FROM pg_constraint WHERE conname = 'constraint_name';
+```
+
+## Common Root Causes by Symptom
+
+| Symptom | Most likely root cause |
+|---|---|
+| Works locally, fails in prod | Missing env variable, different data, different dependency version |
+| Works first time, fails after | State mutation, missing cleanup, memory leak |
+| Fails only for specific users | Permission issue, data-specific edge case, locale/timezone |
+| Intermittent failure | Race condition, network timeout, cache miss |
+| Broke after a "safe" refactor | Changed behavior, not just structure — test coverage gap |
+| Type error on a "correct" type | Async data not yet loaded, API response shape changed |
+| Infinite loop / stack overflow | Circular dependency, missing base case, recursive state update |
+
+## Red Flags That Mean You Haven't Found the Root Cause
+
+- Your fix is "just try X and see"
+- You changed multiple things at once
+- You can't explain *why* the fix works
+- The bug appears to be "gone" but you're not sure how
+- You're patching the symptom (e.g., `|| ''`) without understanding why the value was missing
+
+If any of these apply, go back to Step 3.
+
+## Rubber Duck Checklist
+
+When you're stuck, explain the bug out loud (or in writing) as if to someone with no context:
+
+1. What should happen?
+2. What actually happens?
+3. At what exact point does reality diverge from expectation?
+4. What is the data state at that point?
+5. What code runs between "expected" and "actual"?
+
+The act of articulating the problem often reveals the solution.
+
+---
+
+> Powered by Kodelyth — trace first, fix second, never guess.

package/skills/social-graph-ranker/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: social-graph-ranker
+description: Weighted social-graph ranking for warm intro discovery, bridge scoring, and network gap analysis across X and LinkedIn. Use when the user wants the reusable graph-ranking engine itself, not the broader outreach or network-maintenance workflow layered on top of it.
+origin: ECC
+---
+
+# Social Graph Ranker
+
+Canonical weighted graph-ranking layer for network-aware outreach.
+
+Use this when the user needs to:
+
+- rank existing mutuals or connections by intro value
+- map warm paths to a target list
+- measure bridge value across first- and second-order connections
+- decide which targets deserve warm intros versus direct cold outreach
+- understand the graph math independently from `lead-intelligence` or `connections-optimizer`
+
+## When To Use This Standalone
+
+Choose this skill when the user primarily wants the ranking engine:
+
+- "who in my network is best positioned to introduce me?"
+- "rank my mutuals by who can get me to these people"
+- "map my graph against this ICP"
+- "show me the bridge math"
+
+Do not use this by itself when the user really wants:
+
+- full lead generation and outbound sequencing -> use `lead-intelligence`
+- pruning, rebalancing, and growing the network -> use `connections-optimizer`
+
+## Inputs
+
+Collect or infer:
+
+- target people, companies, or ICP definition
+- the user's current graph on X, LinkedIn, or both
+- weighting priorities such as role, industry, geography, and responsiveness
+- traversal depth and decay tolerance
+
+## Core Model
+
+Given:
+
+- `T` = weighted target set
+- `M` = your current mutuals / direct connections
+- `d(m, t)` = shortest hop distance from mutual `m` to target `t`
+- `w(t)` = target weight from signal scoring
+
+Base bridge score:
+
+```text
+B(m) = Σ_{t ∈ T} w(t) · λ^(d(m,t) - 1)
+```
+
+Where:
+
+- `λ` is the decay factor, usually `0.5`
+- a direct path contributes full value
+- each extra hop halves the contribution
+
+Second-order expansion:
+
+```text
+B_ext(m) = B(m) + α · Σ_{m' ∈ N(m) \\ M} Σ_{t ∈ T} w(t) · λ^(d(m',t))
+```
+
+Where:
+
+- `N(m) \\ M` is the set of people the mutual knows that you do not
+- `α` discounts second-order reach, usually `0.3`
+
+Response-adjusted final ranking:
+
+```text
+R(m) = B_ext(m) · (1 + β · engagement(m))
+```
+
+Where:
+
+- `engagement(m)` is normalized responsiveness or relationship strength
+- `β` is the engagement bonus, usually `0.2`
+
+Interpretation:
+
+- Tier 1: high `R(m)` and direct bridge paths -> warm intro asks
+- Tier 2: medium `R(m)` and one-hop bridge paths -> conditional intro asks
+- Tier 3: low `R(m)` or no viable bridge -> direct outreach or follow-gap fill
+
+## Scoring Signals
+
+Weight targets before graph traversal with whatever matters for the current priority set:
+
+- role or title alignment
+- company or industry fit
+- current activity and recency
+- geographic relevance
+- influence or reach
+- likelihood of response
+
+Weight mutuals after traversal with:
+
+- number of weighted paths into the target set
+- directness of those paths
+- responsiveness or prior interaction history
+- contextual fit for making the intro
+
+## Workflow
+
+1. Build the weighted target set.
+2. Pull the user's graph from X, LinkedIn, or both.
+3. Compute direct bridge scores.
+4. Expand second-order candidates for the highest-value mutuals.
+5. Rank by `R(m)`.
+6. Return:
+   - best warm intro asks
+   - conditional bridge paths
+   - graph gaps where no warm path exists
+
+## Output Shape
+
+```text
+SOCIAL GRAPH RANKING
+====================
+
+Priority Set:
+Platforms:
+Decay Model:
+
+Top Bridges
+- mutual / connection
+  base_score:
+  extended_score:
+  best_targets:
+  path_summary:
+  recommended_action:
+
+Conditional Paths
+- mutual / connection
+  reason:
+  extra hop cost:
+
+No Warm Path
+- target
+  recommendation: direct outreach / fill graph gap
+```
+
+## Related Skills
+
+- `lead-intelligence` uses this ranking model inside the broader target-discovery and outreach pipeline
+- `connections-optimizer` uses the same bridge logic when deciding who to keep, prune, or add
+- `brand-voice` should run before drafting any intro request or direct outreach
+- `x-api` provides X graph access and optional execution paths