@rune-kit/rune 2.1.1

package/skills/db/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: db
+description: Database workflow specialist. Generates migration files with rollback scripts, detects breaking schema changes, and validates query parameterization.
+metadata:
+  author: runedev
+  version: "0.1.0"
+  layer: L2
+  model: sonnet
+  group: development
+  tools: "Read, Write, Edit, Bash, Glob, Grep"
+---
+
+# db
+
+## Purpose
+
+Database workflow specialist. Handles the parts of database work that cause production incidents — breaking schema changes, migrations without rollback, raw SQL injection vectors, and missing indexes on growing tables. Acts as a pre-deploy gate for any schema change, and generates correct migration files (up + down) for common ORMs.
+
+## Triggers
+
+- `/rune db` — manual invocation when schema changes are planned
+- Called by `cook` (L1): schema change detected in diff
+- Called by `deploy` (L2): pre-deploy migration safety check
+- Called by `audit` (L2): database health dimension
+
+## Calls (outbound)
+
+- `scout` (L2): find schema files, migration files, ORM config
+- `verification` (L3): run migration in test environment if configured
+- `hallucination-guard` (L3): verify SQL syntax and ORM method names
+
+## Called By (inbound)
+
+- `cook` (L1): schema change detected in diff
+- `deploy` (L2): pre-deploy migration safety check
+- `audit` (L2): database health dimension
+
+## Executable Steps
+
+### Step 1 — Discovery
+
+Invoke `scout` to locate:
+- Schema definition files: `*.sql`, `schema.prisma`, `models.py`, `*.migration.ts`, `db/migrate/*.rb`
+- Migration directory and existing migration files (to determine next migration number)
+- ORM in use: **Prisma** | **TypeORM** | **SQLAlchemy/Alembic** | **Django ORM** | **ActiveRecord** | **raw SQL** | **unknown**
+- Database type: **PostgreSQL** | **MySQL** | **SQLite** | **MongoDB** | **unknown**
+
+If ORM cannot be determined with confidence, fall back to generic SQL migration format.
+
+### Step 2 — Diff Analysis
+
+Read current schema and compare against previous version (git diff if available):
+- List all **added** columns, tables, indexes, constraints
+- List all **removed** columns, tables, indexes
+- List all **modified** columns (type changes, nullability changes, default changes)
+- List all **renamed** columns or tables
+
+### Step 3 — Breaking Change Detection
+
+Classify each change by impact:
+
+| Change | Classification | Why |
+|--------|---------------|-----|
+| ADD COLUMN NOT NULL without DEFAULT | **BREAKING** | Fails on existing rows |
+| DROP COLUMN | **BREAKING** | Irreversible data loss |
+| RENAME COLUMN or TABLE | **BREAKING** | Breaks all existing queries |
+| CHANGE column type (e.g. VARCHAR→INT) | **BREAKING** | Data truncation risk |
+| ADD COLUMN nullable | SAFE | Existing rows get NULL |
+| ADD TABLE | SAFE | No impact on existing data |
+| ADD INDEX | SAFE (but may lock table) | Lock risk on large tables |
+| DROP INDEX | SAFE | Slight query slowdown |
+| DROP TABLE | **BREAKING** | Irreversible data loss |
+
+For any **BREAKING** change: output `BREAKING: [change description]` and require explicit user confirmation before generating migration.
+
+<HARD-GATE>
+Migration adding NOT NULL column to existing table without DEFAULT value = BLOCK.
+Column rename or type change on data-bearing table = BREAKING — emit warning and require confirmation before proceeding.
+Empty downgrade/rollback function = BLOCK — every migration MUST have a working down/rollback path.
+</HARD-GATE>
+
+### Step 4 — Migration Generation
+
+For each schema change, generate a migration file with **up** (apply) and **down** (rollback) scripts.
+
+**Prisma:**
+```typescript
+// migrations/[timestamp]_[description]/migration.sql
+-- Up
+ALTER TABLE "users" ADD COLUMN "avatar_url" TEXT;
+
+-- Down (in separate migration file or comment)
+ALTER TABLE "users" DROP COLUMN "avatar_url";
+```
+
+**Django / Alembic:**
+```python
+def upgrade():
+    op.add_column('users', sa.Column('avatar_url', sa.Text(), nullable=True))
+
+def downgrade():
+    op.drop_column('users', 'avatar_url')
+# NEVER leave downgrade() empty — HARD-GATE blocks this
+```
+
+**TypeORM:**
+```typescript
+public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.addColumn('users', new TableColumn({
+        name: 'avatar_url', type: 'text', isNullable: true
+    }));
+}
+public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.dropColumn('users', 'avatar_url');
+}
+```
+
+**Raw SQL:**
+```sql
+-- up.sql
+ALTER TABLE users ADD COLUMN avatar_url TEXT;
+-- down.sql
+ALTER TABLE users DROP COLUMN avatar_url;
+```
+
+Use `hallucination-guard` to verify syntax of generated SQL and ORM method names before writing.
+
+### Step 5 — Index Analysis
+
+For every new table or column added, check:
+- Foreign key columns without index → flag `MISSING_INDEX: [column] — add index for JOIN performance`
+- High-cardinality columns used in WHERE clauses (email, user_id, status) without index → flag `CONSIDER_INDEX`
+- Composite indexes: if queries filter on (A, B), index should be on (A, B) not just A
+
+For existing tables with new query patterns:
+- If query uses ORDER BY [column] on large table without index → flag `SORT_INDEX_MISSING`
+
+### Step 6 — Query Parameterization Scan
+
+Scan migration files and any raw SQL files for injection vectors:
+
+```python
+# BAD: string interpolation in SQL
+query = f"SELECT * FROM users WHERE email = '{email}'"
+
+# GOOD: parameterized
+query = "SELECT * FROM users WHERE email = %s"
+cursor.execute(query, (email,))
+```
+
+Finding: `SQL_INJECTION_RISK — [file:line] — string interpolation in query — use parameterized query`
+
+### Step 7 — Schema Documentation
+
+Update or create `.rune/schema-changelog.md` with a human-readable entry:
+
+```markdown
+## [date] — [migration name]
+- Added: [column list]
+- Removed: [column list — note if data was migrated]
+- Breaking: [yes/no] — [details if yes]
+- Rollback: [migration name or "manual"]
+```
+
+### Step 8 — Report
+
+Emit structured report:
+
+```
+## DB Report: [scope]
+
+### Schema Changes
+- [SAFE|BREAKING] [change description]
+
+### Breaking Changes Requiring Confirmation
+- BREAKING: [description] — requires explicit approval before migration runs
+
+### Generated Files
+- [migration file path] (up + down)
+
+### Index Recommendations
+- MISSING_INDEX: [table.column] — [reason]
+
+### Query Safety
+- SQL_INJECTION_RISK: [file:line] — [description]
+- Clean: [list of checked files with no issues]
+
+### Verdict: PASS | WARN | BLOCK
+```
+
+## Output Format
+
+```
+## DB Report: schema.prisma diff
+
+### Schema Changes
+- SAFE: Added users.avatar_url (TEXT, nullable)
+- BREAKING: Renamed users.created → users.created_at
+
+### Breaking Changes Requiring Confirmation
+- BREAKING: Column rename users.created → users.created_at
+  Impact: all queries referencing 'created' will break
+  Confirm before proceeding? [yes/no]
+
+### Generated Files
+- migrations/20260224_add_avatar_url/migration.sql (up + down)
+
+### Index Recommendations
+- MISSING_INDEX: users.email — high-cardinality FK, add for login query performance
+
+### Verdict: BLOCK (breaking change unconfirmed)
+```
+
+## Constraints
+
+1. MUST generate both up and down scripts for every migration — empty rollback = BLOCK
+2. MUST flag NOT NULL without DEFAULT as BLOCK — never silently generate broken migration
+3. MUST NOT run migration in production — only in test environment (via verification)
+4. MUST use hallucination-guard to verify SQL syntax before writing migration files
+5. MUST NOT rename columns silently — always present impact and require confirmation
+
+## Mesh Gates (L1/L2 only)
+
+| Gate | Requires | If Missing |
+|------|----------|------------|
+| ORM Gate | ORM identified before migration generation | Fall back to raw SQL format + note |
+| Breaking Gate | User confirmation before proceeding on BREAKING changes | BLOCK and await response |
+| Rollback Gate | Working down() / rollback script before writing migration | BLOCK — prompt for rollback logic |
+| Safety Gate | hallucination-guard verified SQL before Write | Re-verify or flag as unverified |
+
+## Sharp Edges
+
+Known failure modes for this skill. Check these before declaring done.
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Empty downgrade() written silently | CRITICAL | HARD-GATE: never write empty rollback — always prompt for rollback logic |
+| NOT NULL column added without DEFAULT on existing table | CRITICAL | HARD-GATE: BLOCK and explain that this will fail on existing rows |
+| Migration generated for wrong ORM (TypeORM syntax in Django project) | HIGH | hallucination-guard verifies method names match detected ORM |
+| Index recommendations skipped on large tables | MEDIUM | Always run Step 5 — never skip index analysis |
+| Schema changelog not updated after migration | LOW | Step 7 runs always — log INFO if skipped due to no .rune/ directory |
+
+## Done When
+
+- All schema changes classified (SAFE vs BREAKING)
+- Breaking changes surfaced and confirmed (or BLOCK issued)
+- Migration files generated with working up + down scripts
+- hallucination-guard verified SQL syntax
+- Index recommendations listed
+- Query parameterization scan complete
+- Schema changelog updated in .rune/schema-changelog.md
+- Structured DB Report emitted with PASS/WARN/BLOCK verdict
+
+## Cost Profile
+
+~2000-6000 tokens input, ~800-2000 tokens output. Sonnet for migration generation quality.

package/skills/debug/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: debug
+description: Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh.
+metadata:
+  author: runedev
+  version: "0.3.0"
+  layer: L2
+  model: sonnet
+  group: development
+  tools: "Read, Bash, Glob, Grep"
+---
+
+# debug
+
+## Purpose
+
+Root cause analysis ONLY. Debug investigates — it does NOT fix. It traces errors through code, analyzes stack traces, forms and tests hypotheses, and identifies the exact cause before handing off to rune:fix.
+
+<HARD-GATE>
+Do NOT fix the code. Debug investigates only. Any code change is out of scope.
+If root cause cannot be identified after 3 hypothesis cycles:
+- Escalate to `rune:problem-solver` for structured 5-Whys or Fishbone analysis
+- Or escalate to `rune:sequential-thinking` for multi-variable analysis
+- Report escalation in the Debug Report with all evidence gathered so far
+</HARD-GATE>
+
+## Triggers
+
+- Called by `cook` when implementation hits unexpected errors
+- Called by `test` when a test fails with unclear reason
+- Called by `fix` when root cause is unclear before fixing
+- `/rune debug <issue>` — manual debugging
+- Auto-trigger: when error output contains stack trace or error code
+
+## Calls (outbound)
+
+- `scout` (L2): find related code, trace imports, identify affected modules
+- `fix` (L2): when root cause found, hand off with diagnosis for fix application
+- `brainstorm` (L2): 3-Fix Escalation when root cause is "wrong approach" — invoke with mode="rescue" for category-diverse alternatives
+- `plan` (L2): 3-Fix Escalation when root cause is "wrong module design" — invoke for redesign
+- `docs-seeker` (L3): lookup API docs for unclear errors or deprecated APIs
+- `problem-solver` (L3): structured reasoning (5 Whys, Fishbone) for complex bugs
+- `browser-pilot` (L3): capture browser console errors, network failures, visual bugs
+- `sequential-thinking` (L3): multi-variable root cause analysis
+
+## Called By (inbound)
+
+- `cook` (L1): implementation hits bug during Phase 4
+- `fix` (L2): root cause unclear, can't fix blindly — needs diagnosis first
+- `test` (L2): test fails unexpectedly, unclear why
+- `surgeon` (L2): diagnose issues in legacy modules
+
+## Cross-Hub Connections
+
+- `debug` ↔ `fix` — bidirectional: debug finds cause → fix applies, fix can't determine cause → debug investigates
+- `debug` ← `test` — test fails → debug investigates
+
+## Execution
+
+### Step 1: Reproduce
+
+Understand and confirm the error described in the request.
+
+- Read the error message, stack trace, and reproduction steps
+- Identify which environment it occurs in (dev/prod, browser/server)
+- Confirm the error is consistent and reproducible before proceeding
+- If no reproduction steps provided, ask for them or attempt the most likely path
+
+### Step 2: Gather Evidence
+
+Use tools to collect facts — do NOT guess yet.
+
+- Use `Grep` to search codebase for the exact error string or related error codes
+- Use `Read` to examine stack trace files, log files, or the specific file:line mentioned
+- Use `Glob` to find related files (config, types, tests) that may be involved
+- Use `rune:browser-pilot` if the issue is UI-related (console errors, network failures, visual bugs)
+- Use `rune:scout` to trace imports and identify all modules touched by the affected code path
+
+#### Backward Tracing (for deep stack errors)
+
+When the error appears deep in execution (wrong directory, wrong path, wrong value):
+
+1. **Observe symptom** — what's the exact error and where does it appear?
+2. **Find immediate cause** — what code directly triggers this? Read that file:line
+3. **What called this?** — trace one level up. What value was passed? By whom?
+4. **Keep tracing up** — repeat until you find where the bad value ORIGINATES
+5. **Fix at source** — the root cause is where invalid data is CREATED, not where it CRASHES
+
+Rule: NEVER fix where the error appears. Trace back to where invalid data originated.
+
+#### Multi-Component Instrumentation (for systems with 3+ layers)
+
+When the system has multiple components (CI → build → deploy, API → service → DB):
+
+Before hypothesizing, add diagnostic logging at EACH component boundary:
+- Log what data ENTERS each component
+- Log what data EXITS each component
+- Verify environment/config propagation across boundaries
+- Run once → analyze logs → identify WHICH boundary fails → THEN hypothesize
+
+This reveals: "secrets reach workflow ✓, workflow reaches build ✗" — pinpoints the failing layer.
+
+### Step 3: Form Hypotheses
+
+List exactly 2-3 possible root causes — no more, no fewer.
+
+- Each hypothesis must be specific (name the file, function, or line if possible)
+- Order by likelihood (most likely first)
+- Format:
+  - H1: [specific hypothesis — file/function/pattern]
+  - H2: [specific hypothesis]
+  - H3: [specific hypothesis]
+
+### Step 4: Test Hypotheses
+
+Test each hypothesis systematically using tools.
+
+- Use `Read` to inspect the suspected file/function for each hypothesis
+- Use `Bash` to run targeted tests: a single failing test, a type check, a linter on the file
+- Use `rune:browser-pilot` for UI hypotheses (inspect DOM, network, console)
+- For each hypothesis: mark CONFIRMED / RULED OUT with evidence
+- If all 3 hypotheses are ruled out → go back to Step 2 to gather more evidence
+- Maximum 3 hypothesis cycles. If still unresolved after 3 cycles → escalate (see Hard-Gate)
+
+### Step 5: Identify Root Cause
+
+Narrow to the single actual cause.
+
+- State the confirmed hypothesis and the exact evidence that proves it
+- Identify the specific file, line number, and code construct responsible
+- Note any contributing factors (environment, data, timing, config)
+
+### Step 6: 3-Fix Escalation Rule
+
+<HARD-GATE>
+If the SAME bug has been "fixed" 3 times and keeps returning:
+1. STOP fixing. The bug is not the problem — the ARCHITECTURE is.
+2. **Classify the failure**:
+   - **Same category of blocker each time** (e.g., API doesn't support X, platform limitation) → the APPROACH is wrong, not just the code
+   - **Different bugs each time** (e.g., race condition, then null pointer, then type error) → the MODULE needs redesign
+3. **Route based on classification**:
+   - Approach is wrong → Escalate to `rune:brainstorm(mode="rescue")` for category-diverse alternatives
+   - Module needs redesign → Escalate to `rune:plan` for redesign of the affected module
+4. Report all 3 fix attempts and why each failed in the escalation.
+"Try a 4th fix" is NOT acceptable. After 3 failures, question the design OR the approach.
+</HARD-GATE>
+
+Track fix attempts in the Debug Report. If this is attempt N>1 for the same symptom:
+- Reference previous fix attempts and their outcomes
+- Explain why the previous fix didn't hold
+- If N=3: trigger the escalation gate above — classify and route accordingly
+
+### Step 7: Report
+
+Produce structured output and hand off to rune:fix.
+
+- Write the Debug Report (see Output Format below)
+- Call `rune:fix` with the full report if fix is needed
+- Do NOT apply any code changes — report only
+
+## Red Flags — STOP and Return to Step 2
+
+If you catch yourself thinking any of these, you are GUESSING, not debugging:
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- "One more fix attempt" (when already tried 2+)
+
+ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
+
+## Constraints
+
+1. MUST NOT apply any code changes — debug investigates only, fix applies
+2. MUST reproduce the error before forming hypotheses — no guessing from error messages alone
+3. MUST gather evidence (file reads, grep, stack traces) before hypothesizing
+4. MUST form exactly 2-3 hypotheses, ordered by likelihood — no more, no fewer
+5. MUST mark each hypothesis CONFIRMED or RULED OUT with specific evidence
+6. MUST NOT exceed 3 hypothesis cycles — escalate to problem-solver or sequential-thinking
+7. MUST NOT say "I know what's wrong" without citing file:line evidence
+8. For deep stack errors: MUST use backward tracing (Step 2) — never fix at the crash site
+9. For multi-component systems: MUST instrument boundaries before hypothesizing
+
+## Output Format
+
+```
+## Debug Report
+- **Error**: [error message]
+- **Severity**: critical | high | medium | low
+- **Confidence**: high | medium | low
+- **Fix Attempt**: [1/2/3 — track recurring bugs]
+
+### Root Cause
+[Detailed explanation of what's causing the error]
+
+### Location
+- `path/to/file.ts:42` — [description of the problematic code]
+
+### Evidence
+1. [observation supporting diagnosis]
+2. [observation supporting diagnosis]
+
+### Previous Fix Attempts (if any)
+- Attempt 1: [what was tried] → [why it didn't hold]
+- Attempt 2: [what was tried] → [why it didn't hold]
+
+### Suggested Fix
+[Description of what needs to change — no code, just direction]
+[If attempt 3: "ESCALATION: 3-fix rule triggered. Recommending redesign via rune:plan."]
+
+### Related Code
+- `path/to/related.ts` — [why it's relevant]
+```
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Forming hypothesis from error message alone without evidence | HIGH | Evidence-first rule: read files and grep logs BEFORE hypothesizing |
+| Modifying code while "investigating" | CRITICAL | HARD-GATE: any code change during debug = out of scope — hand off to fix |
+| Marking hypothesis CONFIRMED without file:line proof | HIGH | CONFIRMED requires specific evidence cited — "it makes sense" is not evidence |
+| Exceeding 3 hypothesis cycles without escalation | MEDIUM | After 3 cycles: escalate to rune:problem-solver or rune:sequential-thinking |
+| Same bug "fixed" 3+ times without questioning architecture | CRITICAL | 3-Fix Escalation Rule: classify failure → same blocker category = brainstorm(rescue), different bugs = plan redesign |
+| Escalating to plan when the APPROACH is wrong (not the module) | HIGH | If all 3 fixes hit the same category of blocker (API limit, platform gap), the approach needs pivoting via brainstorm(rescue), not re-planning |
+| Not tracking fix attempt number for recurring bugs | HIGH | Debug Report MUST include Fix Attempt counter — enables escalation gate |
+
+## Done When
+
+- Error reproduced (not assumed) with specific reproduction steps documented
+- 2-3 hypotheses formed, each marked CONFIRMED or RULED OUT with file:line evidence
+- Root cause identified at specific file:line
+- Structured Debug Report emitted
+- No code changes made — rune:fix called with the report if fix is needed
+
+## Cost Profile
+
+~2000-5000 tokens input, ~500-1500 tokens output. Sonnet for code analysis quality. May escalate to opus for deeply complex bugs.