@rune-kit/rune 2.8.0 → 2.11.0

package/skills/autopsy/references/repo-analysis-patterns.md

@@ -0,0 +1,113 @@
+# Repo Analysis Patterns
+
+Reference for autopsy Step 0 (repo intelligence) and cross-cutting analysis.
+
+## GitHub API Metrics Interpretation
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| Commits/week (avg last 12w) | > 5 | 1-5 | < 1 |
+| Contributors (all-time) | > 5 | 2-4 | 1 (bus factor) |
+| Open issues / total issues | < 30% | 30-60% | > 60% |
+| Days since last push | < 14 | 14-90 | > 90 |
+| Stars/fork ratio | > 5:1 | 2-5:1 | < 2:1 (fork-heavy = fragmentation) |
+
+## Bus Factor Assessment
+
+Bus factor = number of contributors who authored > 10% of recent commits (last 6 months).
+
+```bash
+# Bus factor calculation
+git shortlog -sn --since="6 months ago" | awk '{total+=$1; print}' | \
+  awk -v t=$(git shortlog -sn --since="6 months ago" | awk '{s+=$1}END{print s}') \
+  '{pct=$1/t*100; if(pct>10) count++} END{print "Bus factor:", count}'
+```
+
+| Bus Factor | Risk | Action |
+|-----------|------|--------|
+| 1 | Critical | Flag in report — single point of failure |
+| 2-3 | Moderate | Note in report — knowledge concentration |
+| 4+ | Low | Healthy distribution |
+
+## Hotspot-Complexity Correlation
+
+Files that are BOTH hotspots (high change frequency) AND high complexity are the highest-priority rescue targets. Plot on a 2x2 matrix:
+
+```
+                High Complexity
+                     |
+    Refactor NOW     |    Monitor
+    (hot + complex)  |    (cold + complex)
+  -------------------+-------------------
+    Leave alone      |    Review
+    (hot + simple)   |    (cold + simple)
+                     |
+                Low Complexity
+        High Churn ←————→ Low Churn
+```
+
+Priority order: hot+complex > cold+complex > hot+simple > cold+simple.
+
+## Dependency Health Signals
+
+### Outdated packages
+```bash
+# Node.js
+npx npm-check-updates --format group 2>/dev/null | head -40
+
+# Python
+pip list --outdated --format columns 2>/dev/null | head -20
+```
+
+### Known vulnerabilities
+```bash
+# Node.js
+npm audit --json 2>/dev/null | jq '.metadata.vulnerabilities'
+
+# Python
+pip-audit --format json 2>/dev/null | jq '.dependencies | length'
+```
+
+### Circular dependency detection
+```bash
+# Node.js (madge)
+npx madge --circular --extensions ts,js src/ 2>/dev/null
+
+# Python (pydeps)
+pydeps --no-output --show-cycles . 2>/dev/null
+```
+
+## Dead Code Heuristics
+
+A file is likely dead code if ALL of these are true:
+1. No other file imports it (check with grep/madge)
+2. Not referenced in any config (webpack entry, tsconfig paths, package.json bin/main)
+3. Last modified > 6 months ago
+4. Not a test file, fixture, or migration
+
+False positive checklist (do NOT flag these as dead):
+- Dynamic imports (`import()`, `require(variable)`)
+- Plugin/middleware loaded by config (e.g., babel plugins, ESLint rules)
+- CLI entry points referenced in package.json `bin`
+- Database migrations (executed by ORM, not imported)
+- Template files loaded by path string
+
+## Velocity Trend Analysis
+
+Compare commit counts across 3-month windows to detect trajectory:
+
+| Pattern | Signal | Interpretation |
+|---------|--------|---------------|
+| M1 > M2 > M3 | Decelerating | Project may be winding down or blocked |
+| M1 < M2 < M3 | Accelerating | Active development, check for quality regression |
+| M1 ~ M2 ~ M3 | Stable | Healthy maintenance pace |
+| Spiky (high variance) | Irregular | Deadline-driven development — check quality around spikes |
+
+```bash
+# Monthly commit counts for last 6 months
+for i in 0 1 2 3 4 5; do
+  month=$(date -d "$i months ago" +%Y-%m 2>/dev/null || date -v-${i}m +%Y-%m)
+  count=$(git log --after="$month-01" --before="$month-31" --oneline 2>/dev/null | wc -l)
+  echo "$month: $count commits"
+done
+```

package/skills/ba/SKILL.md

@@ -3,7 +3,7 @@ name: ba
 description: Business Analyst agent. Deeply understands user requirements before any planning or coding begins. Asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document that plan and cook consume.
 metadata:
   author: runedev
-  version: "0.4.0"
+  version: "0.5.0"
   layer: L2
   model: opus
   group: creation
@@ -34,6 +34,7 @@ Output is a Requirements Document → hand off to rune:plan for implementation p
 - `research` (L3): look up similar products, APIs, integrations
 - `plan` (L2): hand off Requirements Document for implementation planning
 - `brainstorm` (L2): when multiple approaches exist for a requirement
+- `design` (L2): when requirements include UI/UX components — hand off visual requirements
 
 ## Called By (inbound)
 
@@ -64,7 +65,7 @@ Read the user's request. Classify the requirement type:
 | Greenfield | "new project", "build from scratch" | Full BA + market context |
 
 If Bug Fix → skip BA, route to cook/debug directly.
-If Refactor → light version (Step 1 + Step 4 only).
+If Refactor → light version (Step 1 + Step 4 only). Skip Steps 2, 2.5, 3, 5, 6.
 
 If existing codebase → invoke `rune:scout` for context before proceeding.
 
@@ -110,6 +111,72 @@ O: 30% faster incident detection (measurable KPI)
 - Product/UX feature → Jobs-to-be-Done (keeps focus on user motivation)
 - Integration → 5 Questions only (frameworks add noise for plumbing tasks)
 
+### Step 2.5 — Ambiguity Scoring (Execution Gate)
+
+After each question round, compute an **Ambiguity Score** to determine if requirements are clear enough to proceed. This prevents premature handoff to `plan` with vague inputs.
+
+#### Scoring Formula
+
+```
+Ambiguity = 1 - weighted_average(dimensions)
+
+Dimensions (weights vary by requirement type):
+  Greenfield:  Goal (40%) + Constraints (30%) + Success Criteria (30%)
+  Feature:     Goal (30%) + Constraints (30%) + Success Criteria (20%) + Integration (20%)
+  Integration: Goal (20%) + Constraints (25%) + Success Criteria (20%) + API Contract (35%)
+```
+
+#### Dimension Scoring (0.0 – 1.0)
+
+| Dimension | 0.0 (Unknown) | 0.5 (Partial) | 1.0 (Clear) |
+|-----------|---------------|----------------|--------------|
+| **Goal** | "Make it better" | "Improve dashboard performance" | "Dashboard loads in <2s with 10k rows" |
+| **Constraints** | No constraints mentioned | "Use existing DB" | "PostgreSQL 15, no new deps, GDPR compliant" |
+| **Success Criteria** | "It should work" | "Users can see their data" | "AC-1.1: GIVEN 10k rows WHEN page loads THEN render <2s" |
+| **Integration** | "Connect to the API" | "Use REST, need auth" | "POST /api/v2/orders, OAuth2, rate limit 100/min" |
+| **API Contract** | "It sends data somewhere" | "JSON payload to endpoint" | "OpenAPI spec provided, request/response schemas defined" |
+
+#### Threshold Gate
+
+| Ambiguity | Level | Action |
+|-----------|-------|--------|
+| **< 15%** | Crystal Clear | Proceed to Step 3 immediately |
+| **15-25%** | Acceptable | Proceed with noted assumptions — flag gaps in Requirements Doc |
+| **25-40%** | Unclear | Ask 1-2 targeted follow-up questions on weakest dimension |
+| **> 40%** | Blocked | Do NOT proceed. Re-ask the weakest dimension question with examples |
+
+<HARD-GATE>
+NEVER hand off to plan with Ambiguity > 40%.
+If user insists "just build it" at > 40%, respond:
+"Ambiguity is [X]% — the weakest area is [dimension]. One more answer cuts this in half: [targeted question]"
+</HARD-GATE>
+
+#### Scoring After Each Question
+
+After each of the 5 Questions (Step 2), update the score:
+
+```
+Round 1 (WHO):    Goal ≈ 0.3, others = 0.0 → Ambiguity ≈ 91%
+Round 2 (WHAT):   Goal ≈ 0.7, Success ≈ 0.3 → Ambiguity ≈ 72%
+Round 3 (WHY):    Goal ≈ 0.9, Success ≈ 0.5 → Ambiguity ≈ 47%
+Round 4 (BOUNDS): Constraints ≈ 0.6 → Ambiguity ≈ 30%
+Round 5 (CONSTR): Constraints ≈ 0.9 → Ambiguity ≈ 12% ✅
+```
+
+If Ambiguity drops below 15% before all 5 questions are asked (e.g., user provides a detailed PRD), skip remaining questions and proceed. The gate is about clarity, not ceremony.
+
+#### Display Format
+
+After completing Step 2, show the user:
+
+```
+Clarity Score: [100 - ambiguity]%
+  Goal:             [██████████] 0.9
+  Constraints:      [████████░░] 0.8
+  Success Criteria: [██████░░░░] 0.6  ← weakest
+  Status: ACCEPTABLE (ambiguity 23%) — proceeding with noted gaps
+```
+
 ### Step 3 — Hidden Requirement Discovery
 
 After the 5 questions, analyze for requirements the user DIDN'T mention:
@@ -332,11 +399,14 @@ Known failure modes for this skill. Check these before declaring done.
 | Requirements doc too verbose (>500 lines) | MEDIUM | Max 200 lines — concise, actionable, testable |
 | Skipping BA for "simple" features that turn out complex | HIGH | Let cook's complexity detection trigger BA, not user judgment |
 | Recommending shortcuts without Completeness Score | MEDIUM | Step 3.5: every option needs X/10 score + dual effort estimate (human vs AI). "90% coverage" is a red flag when 100% costs 15 min more |
+| Handing off to plan with ambiguity > 40% | CRITICAL | Step 2.5 HARD-GATE: compute ambiguity score after elicitation, block handoff if > 40%, ask targeted follow-up on weakest dimension |
+| Skipping ambiguity scoring because "user seems clear" | HIGH | Always compute the score — perceived clarity ≠ measured clarity. The formula catches gaps humans miss |
 
 ## Done When
 
 - Requirement type classified (feature/refactor/integration/greenfield)
 - 5 probing questions asked and answered (or extracted from spec/PRD)
+- Ambiguity Score computed and displayed — must be ≤ 40% before proceeding (≤ 25% preferred)
 - Hidden requirements discovered and confirmed with user
 - Scope defined (in/out/assumptions/dependencies)
 - User stories with testable acceptance criteria produced