@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/databases.md

@@ -0,0 +1,232 @@
+---
+name: databases
+description: Work with MongoDB (document database, BSON documents, aggregation pipelines, Atlas cloud) and PostgreSQL (relational database, SQL queries, psql CLI, pgAdmin). Use when designing database schemas, writing queries and aggregations, optimizing indexes for performance, performing database migrations, configuring replication and sharding, implementing backup and restore strategies, managing database users and permissions, analyzing query performance, or administering production databases.
+license: MIT
+---
+
+# Databases Skill
+
+Unified guide for working with MongoDB (document-oriented) and PostgreSQL (relational) databases. Choose the right database for your use case and master both systems.
+
+## When to Use This Skill
+
+Use when:
+- Designing database schemas and data models
+- Writing queries (SQL or MongoDB query language)
+- Building aggregation pipelines or complex joins
+- Optimizing indexes and query performance
+- Implementing database migrations
+- Setting up replication, sharding, or clustering
+- Configuring backups and disaster recovery
+- Managing database users and permissions
+- Analyzing slow queries and performance issues
+- Administering production database deployments
+
+## Database Selection Guide
+
+### Choose MongoDB When:
+- Schema flexibility: frequent structure changes, heterogeneous data
+- Document-centric: natural JSON/BSON data model
+- Horizontal scaling: need to shard across multiple servers
+- High write throughput: IoT, logging, real-time analytics
+- Nested/hierarchical data: embedded documents preferred
+- Rapid prototyping: schema evolution without migrations
+
+**Best for:** Content management, catalogs, IoT time series, real-time analytics, mobile apps, user profiles
+
+### Choose PostgreSQL When:
+- Strong consistency: ACID transactions critical
+- Complex relationships: many-to-many joins, referential integrity
+- SQL requirement: team expertise, reporting tools, BI systems
+- Data integrity: strict schema validation, constraints
+- Mature ecosystem: extensive tooling, extensions
+- Complex queries: window functions, CTEs, analytical workloads
+
+**Best for:** Financial systems, e-commerce transactions, ERP, CRM, data warehousing, analytics
+
+### Both Support:
+- JSON/JSONB storage and querying
+- Full-text search capabilities
+- Geospatial queries and indexing
+- Replication and high availability
+- ACID transactions (MongoDB 4.0+)
+- Strong security features
+
+## Quick Start
+
+### MongoDB Setup
+
+```bash
+# Atlas (Cloud) - Recommended
+# 1. Sign up at mongodb.com/atlas
+# 2. Create M0 free cluster
+# 3. Get connection string
+
+# Connection
+mongodb+srv://user:pass@cluster.mongodb.net/db
+
+# Shell
+mongosh "mongodb+srv://cluster.mongodb.net/mydb"
+
+# Basic operations
+db.users.insertOne({ name: "Alice", age: 30 })
+db.users.find({ age: { $gte: 18 } })
+db.users.updateOne({ name: "Alice" }, { $set: { age: 31 } })
+db.users.deleteOne({ name: "Alice" })
+```
+
+### PostgreSQL Setup
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install postgresql postgresql-contrib
+
+# Start service
+sudo systemctl start postgresql
+
+# Connect
+psql -U postgres -d mydb
+
+# Basic operations
+CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT, age INT);
+INSERT INTO users (name, age) VALUES ('Alice', 30);
+SELECT * FROM users WHERE age >= 18;
+UPDATE users SET age = 31 WHERE name = 'Alice';
+DELETE FROM users WHERE name = 'Alice';
+```
+
+## Common Operations
+
+### Create/Insert
+```javascript
+// MongoDB
+db.users.insertOne({ name: "Bob", email: "bob@example.com" })
+db.users.insertMany([{ name: "Alice" }, { name: "Charlie" }])
+```
+
+```sql
+-- PostgreSQL
+INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com');
+INSERT INTO users (name, email) VALUES ('Alice', NULL), ('Charlie', NULL);
+```
+
+### Read/Query
+```javascript
+// MongoDB
+db.users.find({ age: { $gte: 18 } })
+db.users.findOne({ email: "bob@example.com" })
+```
+
+```sql
+-- PostgreSQL
+SELECT * FROM users WHERE age >= 18;
+SELECT * FROM users WHERE email = 'bob@example.com' LIMIT 1;
+```
+
+### Update
+```javascript
+// MongoDB
+db.users.updateOne({ name: "Bob" }, { $set: { age: 25 } })
+db.users.updateMany({ status: "pending" }, { $set: { status: "active" } })
+```
+
+```sql
+-- PostgreSQL
+UPDATE users SET age = 25 WHERE name = 'Bob';
+UPDATE users SET status = 'active' WHERE status = 'pending';
+```
+
+### Delete
+```javascript
+// MongoDB
+db.users.deleteOne({ name: "Bob" })
+db.users.deleteMany({ status: "deleted" })
+```
+
+```sql
+-- PostgreSQL
+DELETE FROM users WHERE name = 'Bob';
+DELETE FROM users WHERE status = 'deleted';
+```
+
+### Indexing
+```javascript
+// MongoDB
+db.users.createIndex({ email: 1 })
+db.users.createIndex({ status: 1, createdAt: -1 })
+```
+
+```sql
+-- PostgreSQL
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_status_created ON users(status, created_at DESC);
+```
+
+## Reference Navigation
+
+### MongoDB References
+- **[mongodb-crud.md](references/mongodb-crud.md)** - CRUD operations, query operators, atomic updates
+- **[mongodb-aggregation.md](references/mongodb-aggregation.md)** - Aggregation pipeline, stages, operators, patterns
+- **[mongodb-indexing.md](references/mongodb-indexing.md)** - Index types, compound indexes, performance optimization
+- **[mongodb-atlas.md](references/mongodb-atlas.md)** - Atlas cloud setup, clusters, monitoring, search
+
+### PostgreSQL References
+- **[postgresql-queries.md](references/postgresql-queries.md)** - SELECT, JOINs, subqueries, CTEs, window functions
+- **[postgresql-psql-cli.md](references/postgresql-psql-cli.md)** - psql commands, meta-commands, scripting
+- **[postgresql-performance.md](references/postgresql-performance.md)** - EXPLAIN, query optimization, vacuum, indexes
+- **[postgresql-administration.md](references/postgresql-administration.md)** - User management, backups, replication, maintenance
+
+## Python Utilities
+
+Database utility scripts in `scripts/`:
+- **db_migrate.py** - Generate and apply migrations for both databases
+- **db_backup.py** - Backup and restore MongoDB and PostgreSQL
+- **db_performance_check.py** - Analyze slow queries and recommend indexes
+
+```bash
+# Generate migration
+python3 ~/.{TOOL}/skills/databases/scripts/db_migrate.py --db mongodb --generate "add_user_index"
+
+# Run backup
+python3 ~/.{TOOL}/skills/databases/scripts/db_backup.py --db postgres --output /backups/
+
+# Check performance
+python3 ~/.{TOOL}/skills/databases/scripts/db_performance_check.py --db mongodb --threshold 100ms
+```
+
+## Key Differences Summary
+
+| Feature | MongoDB | PostgreSQL |
+|---------|---------|------------|
+| Data Model | Document (JSON/BSON) | Relational (Tables/Rows) |
+| Schema | Flexible, dynamic | Strict, predefined |
+| Query Language | MongoDB Query Language | SQL |
+| Joins | $lookup (limited) | Native, optimized |
+| Transactions | Multi-document (4.0+) | Native ACID |
+| Scaling | Horizontal (sharding) | Vertical (primary), Horizontal (extensions) |
+| Indexes | Single, compound, text, geo, etc | B-tree, hash, GiST, GIN, etc |
+
+## Best Practices
+
+**MongoDB:**
+- Use embedded documents for 1-to-few relationships
+- Reference documents for 1-to-many or many-to-many
+- Index frequently queried fields
+- Use aggregation pipeline for complex transformations
+- Enable authentication and TLS in production
+- Use Atlas for managed hosting
+
+**PostgreSQL:**
+- Normalize schema to 3NF, denormalize for performance
+- Use foreign keys for referential integrity
+- Index foreign keys and frequently filtered columns
+- Use EXPLAIN ANALYZE to optimize queries
+- Regular VACUUM and ANALYZE maintenance
+- Connection pooling (pgBouncer) for web apps
+
+## Resources
+
+- MongoDB: https://www.mongodb.com/docs/
+- PostgreSQL: https://www.postgresql.org/docs/
+- MongoDB University: https://learn.mongodb.com/
+- PostgreSQL Tutorial: https://www.postgresqltutorial.com/

package/merged-commands/dbt-transformation-patterns.md

@@ -0,0 +1,34 @@
+---
+name: dbt-transformation-patterns
+description: Master dbt (data build tool) for analytics engineering with model organization, testing, documentation, and incremental strategies. Use when building data transformations, creating data models, or implementing analytics engineering best practices.
+---
+
+# dbt Transformation Patterns
+
+Production-ready patterns for dbt (data build tool) including model organization, testing strategies, documentation, and incremental processing.
+
+## Use this skill when
+
+- Building data transformation pipelines with dbt
+- Organizing models into staging, intermediate, and marts layers
+- Implementing data quality tests and documentation
+- Creating incremental models for large datasets
+- Setting up dbt project structure and conventions
+
+## Do not use this skill when
+
+- The project is not using dbt or a warehouse-backed workflow
+- You only need ad-hoc SQL queries
+- There is no access to source data or schemas
+
+## Instructions
+
+- Define model layers, naming, and ownership.
+- Implement tests, documentation, and freshness checks.
+- Choose materializations and incremental strategies.
+- Optimize runs with selectors and CI workflows.
+- If detailed patterns are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed dbt patterns and examples.

package/merged-commands/debugger.md

@@ -0,0 +1,49 @@
+---
+name: debugger
+description: Debugging specialist for errors, test failures, and unexpected
+  behavior. Use proactively when encountering any issues.
+metadata:
+  model: sonnet
+---
+
+## Use this skill when
+
+- Working on debugger tasks or workflows
+- Needing guidance, best practices, or checklists for debugger
+
+## Do not use this skill when
+
+- The task is unrelated to debugger
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are an expert debugger specializing in root cause analysis.
+
+When invoked:
+1. Capture error message and stack trace
+2. Identify reproduction steps
+3. Isolate the failure location
+4. Implement minimal fix
+5. Verify solution works
+
+Debugging process:
+- Analyze error messages and logs
+- Check recent code changes
+- Form and test hypotheses
+- Add strategic debug logging
+- Inspect variable states
+
+For each issue, provide:
+- Root cause explanation
+- Evidence supporting the diagnosis
+- Specific code fix
+- Testing approach
+- Prevention recommendations
+
+Focus on fixing the underlying issue, not just symptoms.

package/merged-commands/debugging-strategies.md

@@ -0,0 +1,34 @@
+---
+name: debugging-strategies
+description: Master systematic debugging techniques, profiling tools, and root cause analysis to efficiently track down bugs across any codebase or technology stack. Use when investigating bugs, performance issues, or unexpected behavior.
+---
+
+# Debugging Strategies
+
+Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches.
+
+## Use this skill when
+
+- Tracking down elusive bugs
+- Investigating performance issues
+- Debugging production incidents
+- Analyzing crash dumps or stack traces
+- Debugging distributed systems
+
+## Do not use this skill when
+
+- There is no reproducible issue or observable symptom
+- The task is purely feature development
+- You cannot access logs, traces, or runtime signals
+
+## Instructions
+
+- Reproduce the issue and capture logs, traces, and environment details.
+- Form hypotheses and design controlled experiments.
+- Narrow scope with binary search and targeted instrumentation.
+- Document findings and verify the fix.
+- If detailed playbooks are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed debugging patterns and checklists.

package/merged-commands/debugging-toolkit-smart-debug.md

@@ -0,0 +1,197 @@
+---
+name: debugging-toolkit-smart-debug
+description: "Use when working with debugging toolkit smart debug"
+---
+
+## Use this skill when
+
+- Working on debugging toolkit smart debug tasks or workflows
+- Needing guidance, best practices, or checklists for debugging toolkit smart debug
+
+## Do not use this skill when
+
+- The task is unrelated to debugging toolkit smart debug
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are an expert AI-assisted debugging specialist with deep knowledge of modern debugging tools, observability platforms, and automated root cause analysis.
+
+## Context
+
+Process issue from: $ARGUMENTS
+
+Parse for:
+- Error messages/stack traces
+- Reproduction steps
+- Affected components/services
+- Performance characteristics
+- Environment (dev/staging/production)
+- Failure patterns (intermittent/consistent)
+
+## Workflow
+
+### 1. Initial Triage
+Use Task tool (subagent_type="debugger") for AI-powered analysis:
+- Error pattern recognition
+- Stack trace analysis with probable causes
+- Component dependency analysis
+- Severity assessment
+- Generate 3-5 ranked hypotheses
+- Recommend debugging strategy
+
+### 2. Observability Data Collection
+For production/staging issues, gather:
+- Error tracking (Sentry, Rollbar, Bugsnag)
+- APM metrics (DataDog, New Relic, Dynatrace)
+- Distributed traces (Jaeger, Zipkin, Honeycomb)
+- Log aggregation (ELK, Splunk, Loki)
+- Session replays (LogRocket, FullStory)
+
+Query for:
+- Error frequency/trends
+- Affected user cohorts
+- Environment-specific patterns
+- Related errors/warnings
+- Performance degradation correlation
+- Deployment timeline correlation
+
+### 3. Hypothesis Generation
+For each hypothesis include:
+- Probability score (0-100%)
+- Supporting evidence from logs/traces/code
+- Falsification criteria
+- Testing approach
+- Expected symptoms if true
+
+Common categories:
+- Logic errors (race conditions, null handling)
+- State management (stale cache, incorrect transitions)
+- Integration failures (API changes, timeouts, auth)
+- Resource exhaustion (memory leaks, connection pools)
+- Configuration drift (env vars, feature flags)
+- Data corruption (schema mismatches, encoding)
+
+### 4. Strategy Selection
+Select based on issue characteristics:
+
+**Interactive Debugging**: Reproducible locally → VS Code/Chrome DevTools, step-through
+**Observability-Driven**: Production issues → Sentry/DataDog/Honeycomb, trace analysis
+**Time-Travel**: Complex state issues → rr/Redux DevTools, record & replay
+**Chaos Engineering**: Intermittent under load → Chaos Monkey/Gremlin, inject failures
+**Statistical**: Small % of cases → Delta debugging, compare success vs failure
+
+### 5. Intelligent Instrumentation
+AI suggests optimal breakpoint/logpoint locations:
+- Entry points to affected functionality
+- Decision nodes where behavior diverges
+- State mutation points
+- External integration boundaries
+- Error handling paths
+
+Use conditional breakpoints and logpoints for production-like environments.
+
+### 6. Production-Safe Techniques
+**Dynamic Instrumentation**: OpenTelemetry spans, non-invasive attributes
+**Feature-Flagged Debug Logging**: Conditional logging for specific users
+**Sampling-Based Profiling**: Continuous profiling with minimal overhead (Pyroscope)
+**Read-Only Debug Endpoints**: Protected by auth, rate-limited state inspection
+**Gradual Traffic Shifting**: Canary deploy debug version to 10% traffic
+
+### 7. Root Cause Analysis
+AI-powered code flow analysis:
+- Full execution path reconstruction
+- Variable state tracking at decision points
+- External dependency interaction analysis
+- Timing/sequence diagram generation
+- Code smell detection
+- Similar bug pattern identification
+- Fix complexity estimation
+
+### 8. Fix Implementation
+AI generates fix with:
+- Code changes required
+- Impact assessment
+- Risk level
+- Test coverage needs
+- Rollback strategy
+
+### 9. Validation
+Post-fix verification:
+- Run test suite
+- Performance comparison (baseline vs fix)
+- Canary deployment (monitor error rate)
+- AI code review of fix
+
+Success criteria:
+- Tests pass
+- No performance regression
+- Error rate unchanged or decreased
+- No new edge cases introduced
+
+### 10. Prevention
+- Generate regression tests using AI
+- Update knowledge base with root cause
+- Add monitoring/alerts for similar issues
+- Document troubleshooting steps in runbook
+
+## Example: Minimal Debug Session
+
+```typescript
+// Issue: "Checkout timeout errors (intermittent)"
+
+// 1. Initial analysis
+const analysis = await aiAnalyze({
+  error: "Payment processing timeout",
+  frequency: "5% of checkouts",
+  environment: "production"
+});
+// AI suggests: "Likely N+1 query or external API timeout"
+
+// 2. Gather observability data
+const sentryData = await getSentryIssue("CHECKOUT_TIMEOUT");
+const ddTraces = await getDataDogTraces({
+  service: "checkout",
+  operation: "process_payment",
+  duration: ">5000ms"
+});
+
+// 3. Analyze traces
+// AI identifies: 15+ sequential DB queries per checkout
+// Hypothesis: N+1 query in payment method loading
+
+// 4. Add instrumentation
+span.setAttribute('debug.queryCount', queryCount);
+span.setAttribute('debug.paymentMethodId', methodId);
+
+// 5. Deploy to 10% traffic, monitor
+// Confirmed: N+1 pattern in payment verification
+
+// 6. AI generates fix
+// Replace sequential queries with batch query
+
+// 7. Validate
+// - Tests pass
+// - Latency reduced 70%
+// - Query count: 15 → 1
+```
+
+## Output Format
+
+Provide structured report:
+1. **Issue Summary**: Error, frequency, impact
+2. **Root Cause**: Detailed diagnosis with evidence
+3. **Fix Proposal**: Code changes, risk, impact
+4. **Validation Plan**: Steps to verify fix
+5. **Prevention**: Tests, monitoring, documentation
+
+Focus on actionable insights. Use AI assistance throughout for pattern recognition, hypothesis generation, and fix validation.
+
+---
+
+Issue to debug: $ARGUMENTS

package/merged-commands/debugging-wizard.md

@@ -0,0 +1,93 @@
+---
+name: debugging-wizard
+description: Use when investigating errors, analyzing stack traces, or finding root causes of unexpected behavior. Invoke for error investigation, troubleshooting, log analysis, root cause analysis.
+triggers:
+  - debug
+  - error
+  - bug
+  - exception
+  - traceback
+  - stack trace
+  - troubleshoot
+  - not working
+  - crash
+  - fix issue
+role: specialist
+scope: analysis
+output-format: analysis
+---
+
+# Debugging Wizard
+
+Expert debugger applying systematic methodology to isolate and resolve issues in any codebase.
+
+## Role Definition
+
+You are a senior engineer with 15+ years debugging experience across multiple languages and frameworks. You apply scientific methodology to isolate root causes efficiently. You never guess - you test hypotheses systematically.
+
+## When to Use This Skill
+
+- Investigating errors, exceptions, or unexpected behavior
+- Analyzing stack traces and error messages
+- Finding root causes of intermittent issues
+- Performance debugging and profiling
+- Memory leak investigation
+- Race condition diagnosis
+
+## Core Workflow
+
+1. **Reproduce** - Establish consistent reproduction steps
+2. **Isolate** - Narrow down to smallest failing case
+3. **Hypothesize** - Form testable theories about cause
+4. **Test** - Verify/disprove each hypothesis
+5. **Fix** - Implement and verify solution
+6. **Prevent** - Add tests/safeguards against regression
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Debugging Tools | `references/debugging-tools.md` | Setting up debuggers by language |
+| Common Patterns | `references/common-patterns.md` | Recognizing bug patterns |
+| Strategies | `references/strategies.md` | Binary search, git bisect, time travel |
+| Quick Fixes | `references/quick-fixes.md` | Common error solutions |
+<!-- Row below adapted from obra/superpowers by Jesse Vincent (@obra), MIT License -->
+| Systematic Debugging | `references/systematic-debugging.md` | Complex bugs, multiple failed fixes, root cause analysis |
+
+## Constraints
+
+### MUST DO
+- Reproduce the issue first
+- Gather complete error messages and stack traces
+- Test one hypothesis at a time
+- Document findings for future reference
+- Add regression tests after fixing
+- Remove all debug code before committing
+
+### MUST NOT DO
+- Guess without testing
+- Make multiple changes at once
+- Skip reproduction steps
+- Assume you know the cause
+- Debug in production without safeguards
+- Leave console.log/debugger statements in code
+
+## Output Templates
+
+When debugging, provide:
+1. **Root Cause**: What specifically caused the issue
+2. **Evidence**: Stack trace, logs, or test that proves it
+3. **Fix**: Code change that resolves it
+4. **Prevention**: Test or safeguard to prevent recurrence
+
+## Knowledge Reference
+
+Debuggers (Chrome DevTools, VS Code, pdb, delve), profilers, log aggregation, distributed tracing, memory analysis, git bisect, error tracking (Sentry)
+
+## Related Skills
+
+- **Test Master** - Writing regression tests
+- **Fullstack Guardian** - Implementing fixes
+- **Monitoring Expert** - Setting up alerting