skillstore-cli 1.0.0

package/data/shared/framework/skills/codebase-analysis/references/tech-debt-assessment.md

@@ -0,0 +1,208 @@
+# Tech Debt Assessment
+
+## Tech Debt Taxonomy
+
+### Code Debt
+- **Duplication**: copy-pasted logic instead of shared abstractions
+- **Complexity**: functions with cyclomatic complexity > 15, deeply nested conditionals
+- **Naming**: unclear variable/function names that require comments to explain
+- **Style inconsistency**: mixed formatting, different patterns for the same operation
+
+### Design Debt
+- **Wrong abstractions**: premature abstractions that don't match actual use cases
+- **Tight coupling**: modules that cannot be changed or tested independently
+- **Leaky abstractions**: implementation details exposed through interfaces
+- **Missing boundaries**: business logic mixed with infrastructure (SQL in controllers, HTTP in services)
+
+### Infrastructure Debt
+- **Outdated tooling**: old Node.js/Python/Go versions, deprecated bundlers
+- **Manual processes**: deployments, database migrations, or environment setup done by hand
+- **Missing CI/CD**: no automated testing, linting, or deployment pipeline
+- **Configuration drift**: environments differ in ways that cause "works on my machine" bugs
+
+### Testing Debt
+- **Low coverage**: critical paths with < 50% test coverage
+- **Flaky tests**: tests that fail intermittently due to timing, external dependencies, or shared state
+- **Missing test types**: no integration tests, no E2E tests, no contract tests
+- **Slow test suite**: test suite takes > 10 minutes, discouraging frequent runs
+
+### Documentation Debt
+- **Stale docs**: README or wiki that describes a previous version of the system
+- **Missing ADRs**: architectural decisions made without recorded reasoning
+- **No onboarding guide**: new developers take weeks to become productive
+- **Undocumented APIs**: internal or external APIs without request/response examples
+
+## Severity Scoring Matrix
+
+Rate each tech debt item on two dimensions:
+
+### Impact Score (1-5)
+
+| Score | Impact Level | Description |
+|---|---|---|
+| 1 | Minimal | Cosmetic issue, no functional impact |
+| 2 | Low | Minor inconvenience, easy workaround exists |
+| 3 | Moderate | Slows development, occasional bugs |
+| 4 | High | Frequent bugs, significant velocity impact |
+| 5 | Critical | Security risk, data loss potential, blocks features |
+
+### Effort Score (1-5)
+
+| Score | Effort Level | Description |
+|---|---|---|
+| 1 | Trivial | < 1 hour, single file change |
+| 2 | Small | 1-4 hours, few files |
+| 3 | Medium | 1-2 days, multiple modules |
+| 4 | Large | 3-5 days, cross-cutting changes |
+| 5 | Major | 1+ weeks, architecture-level change |
+
+### Priority Calculation
+
+```
+Priority Score = Impact × (6 - Effort)
+```
+
+Higher score = higher priority. This formula favors high-impact, low-effort items (quick wins).
+
+| Priority Score | Action |
+|---|---|
+| 20-25 | Immediate — fix in current sprint |
+| 12-19 | Planned — schedule in next 2-3 sprints |
+| 6-11 | Backlog — address when touching related code |
+| 1-5 | Defer — not worth dedicated effort |
+
+## Tech Debt Discovery Checklist
+
+### Automated Checks
+
+```bash
+# Count linter warnings
+npx eslint src/ --format json | jq '[.[].messages | length] | add'
+
+# Count TODO/FIXME/HACK markers
+grep -rn 'TODO\|FIXME\|HACK\|XXX\|WORKAROUND' --include='*.ts' --include='*.tsx' src/ | wc -l
+
+# List all TODO/FIXME with file locations
+grep -rn 'TODO\|FIXME\|HACK' --include='*.ts' --include='*.tsx' src/
+
+# TypeScript strict mode gaps
+npx tsc --noEmit --strict 2>&1 | wc -l
+
+# Check TypeScript strict settings
+cat tsconfig.json | grep -E '"strict"|"noImplicit|"strictNull"'
+
+# Dependency age — packages not updated in 12+ months
+npm outdated --long
+
+# Test coverage summary
+npx jest --coverage --coverageReporters=text-summary 2>&1 | tail -5
+
+# Bundle size analysis
+npx webpack-bundle-analyzer stats.json
+```
+
+### Manual Inspection Points
+
+- [ ] Are there god classes/files (> 500 lines)?
+- [ ] Do any modules have 10+ dependencies?
+- [ ] Are error messages helpful for debugging?
+- [ ] Is there consistent error handling across the codebase?
+- [ ] Are environment variables validated at startup?
+- [ ] Is there a consistent data validation strategy?
+- [ ] Are database queries parameterized (no string concatenation)?
+- [ ] Is there a clear separation between business logic and infrastructure?
+- [ ] Can each module be tested in isolation?
+- [ ] Are there any hardcoded secrets, URLs, or configuration values?
+
+## Remediation Prioritization
+
+### Quadrant Model
+
+```
+                    High Impact
+                        |
+         PLANNED        |        QUICK WINS
+      (schedule it)     |     (do it now)
+                        |
+  High Effort -------- -+--------- Low Effort
+                        |
+         IGNORE         |        BOY SCOUT
+    (not worth it)      |    (fix when nearby)
+                        |
+                    Low Impact
+```
+
+### Quick Wins (High Impact, Low Effort)
+- Add missing input validation on public endpoints
+- Fix known security vulnerabilities in dependencies
+- Add TypeScript strict mode to new files
+- Remove dead code flagged by tooling
+- Add error monitoring (Sentry, DataDog)
+
+### Planned Work (High Impact, High Effort)
+- Break apart monolithic services
+- Migrate from deprecated framework version
+- Add integration test suite for critical paths
+- Implement proper authentication/authorization
+- Establish CI/CD pipeline
+
+### Boy Scout Items (Low Impact, Low Effort)
+- Rename unclear variables when editing a file
+- Add type annotations to functions you're modifying
+- Remove commented-out code you encounter
+- Fix linter warnings in files you touch
+- Add JSDoc to public functions you're working on
+
+### Ignore (Low Impact, High Effort)
+- Rewriting stable legacy code that rarely changes
+- Migrating to a new ORM when the current one works fine
+- Full code style migration when auto-formatters exist
+- Abstracting one-off scripts that run correctly
+
+## Tech Debt Tracking Template
+
+Use this template to create a tech debt inventory:
+
+| ID | Category | Description | Impact (1-5) | Effort (1-5) | Priority | Status | Owner |
+|---|---|---|---|---|---|---|---|
+| TD-001 | Testing | No E2E tests for checkout flow | 5 | 4 | 10 | Planned | @team-payments |
+| TD-002 | Code | Duplicated validation in 3 controllers | 3 | 2 | 12 | Backlog | — |
+| TD-003 | Infra | Node.js 16 EOL, need upgrade to 20 | 4 | 3 | 12 | In Progress | @platform |
+| TD-004 | Design | Auth logic spread across 5 modules | 4 | 4 | 8 | Planned | @team-identity |
+| TD-005 | Docs | API docs 6 months out of date | 3 | 2 | 12 | Backlog | — |
+
+### Tracking Best Practices
+
+- Review the inventory quarterly — remove resolved items, reassess priorities
+- Assign owners to high-priority items — unowned debt never gets fixed
+- Include tech debt budget in sprint planning (15-20% of capacity)
+- Celebrate debt reduction — make it visible in retrospectives
+- Link tech debt items to incidents they cause — builds business case
+
+## "Boy Scout Rule" Integration
+
+> "Leave the code better than you found it." — Robert C. Martin
+
+### Within Scope
+
+When working on a feature or bug fix, improve nearby code:
+- Fix linter warnings in files you're editing
+- Add types to functions you're calling
+- Rename unclear variables in your working area
+- Remove dead code you discover
+- Add missing tests for functions you're modifying
+
+### Out of Scope
+
+Do NOT let Boy Scout improvements derail your current task:
+- Don't refactor an entire module when fixing a one-line bug
+- Don't upgrade a dependency if it's not related to your change
+- Don't rewrite a function if the existing behavior is correct
+- Keep cleanup commits separate from feature commits for clean git history
+
+### Making It Sustainable
+
+- Time-box Boy Scout improvements to 15-20 minutes per PR
+- If you find something bigger, create a tech debt ticket instead of fixing it now
+- Review Boy Scout changes in PRs — they should be low-risk and obvious improvements
+- Track cumulative impact — small improvements compound over time

package/data/shared/framework/skills/databases/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: databases
+description: Database design, query optimization, migrations, and data modeling for SQL and NoSQL systems
+---
+
+# Databases
+
+## Triggers
+
+Activate this skill when:
+- Designing a new database schema or data model
+- Optimizing slow queries (identified by monitoring or EXPLAIN output)
+- Planning database migrations (especially for production systems)
+- Choosing between SQL and NoSQL for a new feature or service
+- Adding or reviewing indexes
+- Handling data integrity issues or race conditions
+- Implementing sharding, partitioning, or multi-tenant data isolation
+- Setting up Change Data Capture (CDC) or event streaming from databases
+- Designing temporal/versioned data or audit trail systems
+- Evaluating full-text search solutions (in-database vs external)
+
+## Process
+
+### 1. Requirements Analysis
+- Identify entities, their attributes, and relationships
+- Estimate data volume (rows per table now and in 12 months)
+- List read/write patterns (which queries run most often, at what frequency)
+- Identify consistency requirements (strict ACID vs. eventual consistency)
+- Note compliance requirements (data retention, PII handling, auditing)
+
+### 2. Data Modeling
+- Start with a conceptual model (entities and relationships on paper)
+- Create logical model (tables, columns, types, constraints)
+- Normalize to 3NF, then selectively denormalize for read performance
+- Define primary keys (prefer UUIDs or ULIDs for distributed systems, auto-increment for single-node)
+- Map relationships (foreign keys, junction tables, embedded docs)
+
+### 3. Schema Design
+- Choose appropriate data types (don't use VARCHAR(255) for everything)
+- Add NOT NULL constraints by default — make nullable only with reason
+- Define CHECK constraints for enums and ranges
+- Set up created_at/updated_at timestamps with defaults
+- Add soft delete (deleted_at) if required by business rules
+
+### 4. Index Design
+- Create indexes based on actual query patterns, not guesses
+- Start with indexes on: foreign keys, columns in WHERE/JOIN/ORDER BY
+- Use composite indexes matching query column order (leftmost prefix rule)
+- Monitor unused indexes and remove them (they slow down writes)
+
+### 5. Query Optimization
+- Run EXPLAIN/ANALYZE on slow queries
+- Fix common anti-patterns (N+1, SELECT *, missing indexes)
+- Consider denormalization or materialized views for complex reports
+- Set up query monitoring (slow query log, pg_stat_statements)
+
+### 6. Migration Planning
+- Write reversible migrations (up and down)
+- Plan zero-downtime migrations for production (expand-contract pattern)
+- Test migrations against production-size data before deploying
+- Back up before every production migration
+
+## References
+
+- [Schema Design](references/schema-design.md) — normalization, indexes, SQL vs NoSQL, naming conventions
+- [Query Optimization](references/query-optimization.md) — EXPLAIN, anti-patterns, connection pooling, migrations
+- [Advanced Data Patterns](references/advanced-data-patterns.md) — sharding, CDC, temporal tables, full-text search, multi-tenancy
+- [Troubleshooting](references/troubleshooting.md) — slow query diagnosis, lock contention, replication lag, migration failures, deadlocks
+
+## Assets
+
+- [Sample Output](assets/sample-output.md) — example database design for an E-commerce Order System

package/data/shared/framework/skills/databases/assets/sample-output.md

@@ -0,0 +1,212 @@
+# Sample Output: E-commerce Order System Database Design
+
+## Entities
+
+- **users** — customer accounts
+- **products** — catalog items with pricing
+- **orders** — purchase transactions
+- **order_items** — line items within an order
+- **addresses** — shipping/billing addresses
+- **payments** — payment records linked to orders
+
+## Schema
+
+### users
+```sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email TEXT NOT NULL UNIQUE,
+  name TEXT NOT NULL,
+  password_hash TEXT NOT NULL,
+  is_active BOOLEAN NOT NULL DEFAULT true,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### products
+```sql
+CREATE TABLE products (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  sku TEXT NOT NULL UNIQUE,
+  name TEXT NOT NULL,
+  description TEXT,
+  price_cents INTEGER NOT NULL CHECK (price_cents >= 0),
+  currency TEXT NOT NULL DEFAULT 'VND' CHECK (currency IN ('VND', 'USD')),
+  stock_quantity INTEGER NOT NULL DEFAULT 0 CHECK (stock_quantity >= 0),
+  is_active BOOLEAN NOT NULL DEFAULT true,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### addresses
+```sql
+CREATE TABLE addresses (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id),
+  label TEXT NOT NULL DEFAULT 'home' CHECK (label IN ('home', 'work', 'other')),
+  full_name TEXT NOT NULL,
+  phone TEXT NOT NULL,
+  address_line1 TEXT NOT NULL,
+  address_line2 TEXT,
+  city TEXT NOT NULL,
+  district TEXT,
+  postal_code TEXT,
+  country TEXT NOT NULL DEFAULT 'VN',
+  is_default BOOLEAN NOT NULL DEFAULT false,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### orders
+```sql
+CREATE TABLE orders (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id),
+  shipping_address_id UUID NOT NULL REFERENCES addresses(id),
+  status TEXT NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'confirmed', 'processing', 'shipped', 'delivered', 'cancelled', 'refunded')),
+  subtotal_cents INTEGER NOT NULL CHECK (subtotal_cents >= 0),
+  shipping_cents INTEGER NOT NULL DEFAULT 0 CHECK (shipping_cents >= 0),
+  discount_cents INTEGER NOT NULL DEFAULT 0 CHECK (discount_cents >= 0),
+  total_cents INTEGER NOT NULL CHECK (total_cents >= 0),
+  currency TEXT NOT NULL DEFAULT 'VND',
+  notes TEXT,
+  ordered_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  shipped_at TIMESTAMPTZ,
+  delivered_at TIMESTAMPTZ,
+  cancelled_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### order_items
+```sql
+CREATE TABLE order_items (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id UUID NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
+  product_id UUID NOT NULL REFERENCES products(id),
+  product_name TEXT NOT NULL,
+  product_sku TEXT NOT NULL,
+  unit_price_cents INTEGER NOT NULL CHECK (unit_price_cents >= 0),
+  quantity INTEGER NOT NULL CHECK (quantity > 0),
+  line_total_cents INTEGER NOT NULL CHECK (line_total_cents >= 0),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+**Note**: `product_name`, `product_sku`, and `unit_price_cents` are denormalized intentionally — they capture the values at time of purchase. If the product price changes later, historical orders remain accurate.
+
+### payments
+```sql
+CREATE TABLE payments (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id UUID NOT NULL REFERENCES orders(id),
+  method TEXT NOT NULL CHECK (method IN ('credit_card', 'bank_transfer', 'cod', 'momo', 'zalopay')),
+  status TEXT NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'processing', 'completed', 'failed', 'refunded')),
+  amount_cents INTEGER NOT NULL CHECK (amount_cents > 0),
+  currency TEXT NOT NULL DEFAULT 'VND',
+  provider_transaction_id TEXT,
+  paid_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+## Indexes
+
+```sql
+-- users
+CREATE INDEX idx_users_email ON users (email);
+
+-- products
+CREATE INDEX idx_products_sku ON products (sku);
+CREATE INDEX idx_products_active ON products (is_active, name) WHERE is_active = true;
+
+-- addresses
+CREATE INDEX idx_addresses_user ON addresses (user_id);
+
+-- orders (most queried table)
+CREATE INDEX idx_orders_user ON orders (user_id, ordered_at DESC);
+CREATE INDEX idx_orders_status ON orders (status) WHERE status NOT IN ('delivered', 'cancelled');
+CREATE INDEX idx_orders_date ON orders (ordered_at DESC);
+
+-- order_items
+CREATE INDEX idx_order_items_order ON order_items (order_id);
+CREATE INDEX idx_order_items_product ON order_items (product_id);
+
+-- payments
+CREATE INDEX idx_payments_order ON payments (order_id);
+CREATE INDEX idx_payments_status ON payments (status) WHERE status = 'pending';
+```
+
+### Index Rationale
+
+| Index | Supports Query |
+|-------|---------------|
+| `idx_orders_user` | "Show my orders" (user dashboard, sorted by date) |
+| `idx_orders_status` | Admin: "Show pending orders to process" (partial, excludes completed) |
+| `idx_products_active` | Product listing page (only active products) |
+| `idx_payments_status` | Payment reconciliation job (find pending payments) |
+
+## Common Queries
+
+### User's Recent Orders with Items
+```sql
+SELECT o.id, o.status, o.total_cents, o.ordered_at,
+       json_agg(json_build_object('name', oi.product_name, 'qty', oi.quantity, 'total', oi.line_total_cents)) as items
+FROM orders o
+JOIN order_items oi ON oi.order_id = o.id
+WHERE o.user_id = $1
+GROUP BY o.id
+ORDER BY o.ordered_at DESC
+LIMIT 10;
+```
+
+### Daily Revenue Report
+```sql
+SELECT DATE(ordered_at) as order_date,
+       COUNT(*) as order_count,
+       SUM(total_cents) as revenue_cents
+FROM orders
+WHERE status IN ('confirmed', 'processing', 'shipped', 'delivered')
+  AND ordered_at >= $1 AND ordered_at < $2
+GROUP BY DATE(ordered_at)
+ORDER BY order_date;
+```
+
+## Migration Plan
+
+### Phase 1: Initial Schema (Sprint 1)
+```
+001_create_users.sql
+002_create_products.sql
+003_create_addresses.sql
+004_create_orders.sql
+005_create_order_items.sql
+006_create_payments.sql
+007_create_indexes.sql
+```
+
+### Phase 2: Enhancements (Sprint 2-3)
+```
+008_add_orders_tracking_number.sql      -- ALTER TABLE orders ADD COLUMN tracking_number TEXT
+009_add_products_categories.sql         -- New categories table + product_categories junction
+010_add_order_status_history.sql        -- Audit table for status changes
+```
+
+### Zero-Downtime Migration Example
+Adding `tracking_number` to orders:
+1. `ALTER TABLE orders ADD COLUMN tracking_number TEXT;` (nullable, no lock on PostgreSQL 11+)
+2. Deploy code that writes tracking_number when available
+3. No backfill needed (existing orders don't have tracking numbers)
+4. Add index when needed: `CREATE INDEX CONCURRENTLY idx_orders_tracking ON orders (tracking_number) WHERE tracking_number IS NOT NULL;`
+
+### Backup Strategy
+- **Full backup**: Daily at 02:00 UTC via `pg_dump`
+- **WAL archiving**: Continuous to S3 for point-in-time recovery
+- **Retention**: 30 days of daily backups, 7 days of WAL
+- **Recovery test**: Monthly restore to staging environment