ai-developer-skill-os 7.0.2 → 7.5.0

package/skills/qk-data-lifecycle/SKILL.md

@@ -1,44 +1,192 @@
----
-name: qk-data-lifecycle
-category: backend
-version: 7.0.0
-description: "Quản lý Database Schema, Migrations, và Repositories khắt khe với Zero-Trust."
----
-
-# qk-data-lifecycle
-
-## Scope
-- Database Schema management, Migrations, and Repositories (Plan & Execute)
-- Enforcing structural database contracts before implementation.
-
-## Verbs
-- `[SCHEMA]`: Define database tables/models explicitly.
-- `[MIGRATE]`: Safely manage state changes.
-
-## Constraints
-```yaml
-must:
-  - "MUST define explicitly strict database schemas (e.g., Prisma/TypeORM) before writing repository code"
-  - "Enforce strict types for all database operations"
-must_not:
-  - "Create dynamic queries without schema definitions"
-  - "Delete or drop columns without a deprecation phase"
-  - "Write complex business logic inside repository files"
-```
-
-## Policies
-```yaml
-prefer:
-  - "Separation of concerns (Repositories handle data, Services handle logic)"
-  - "Transactions for multi-table updates"
-```
-
-## Escalation
-```yaml
-stop:
-  - "Missing database schema or ORM models"
-  - "Attempting destructive migrations on production"
-```
-
-## Output
-- ORM Schema, Repositories, and Migration files.
+---
+name: qk-data-lifecycle
+category: backend
+version: 7.5.0
+description: "Quản lý Schema, Migrations an toàn — schema freeze → backward-compat migration → cleanup."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: high
+latency: slow
+risk: high
+side_effects: edit_files
+produces: [code, schema]
+consumes: [context-graph, user-description]
+token_budget:
+  max_files_read: 4
+  max_lines_per_read: 100
+  max_shell_commands: 1
+  stop_early: false
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-data-lifecycle — Database Schema & Repository Manager
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Existing schema is identified (ORM model files)
+- [ ] Change intent is clear (add field / modify field / drop field)
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Cần xác định: schema hiện tại + loại thay đổi (add/modify/drop)."
+```
+
+---
+
+## Scope
+- ✅ Define strict schema BEFORE writing repository code
+- ✅ Always backward-compatible migrations (never destructive in first pass)
+- ✅ Separate schema (models) from business logic (services)
+
+## Non-Goals
+- ❌ DROP columns without deprecation phase first
+- ❌ Write complex business logic inside repositories
+- ❌ Dynamic queries without schema definitions
+
+---
+
+## Priority Order
+| P | Task | Skip Threshold |
+|---|------|----------------|
+| P1 | Read existing schema | Never |
+| P2 | Design migration (backward-compat) | Never |
+| P3 | Write migration file | Never |
+| P4 | Update repository layer | Budget < 30% |
+| P5 | Update affected service layer | Budget < 50% |
+
+---
+
+## Migration Safety Rules
+```yaml
+add_column:
+  strategy: nullable OR has default value (never NOT NULL without default)
+  
+modify_column:
+  strategy: add new column → migrate data → drop old column (3-phase)
+  
+drop_column:
+  strategy: Phase 1 — mark deprecated (keep in schema)
+            Phase 2 — next release — remove from queries
+            Phase 3 — next migration — DROP COLUMN
+
+rename_table:
+  strategy: create new table → migrate → drop old (never ALTER TABLE RENAME in prod)
+```
+
+---
+
+## Workflow
+
+### Phase 1 — Schema Read
+1. `grep_search` for existing model/entity file
+2. Read current schema (targeted, ≤ 100 lines)
+3. Identify impact of proposed change
+
+### Phase 2 — Migration Design
+1. Choose safety strategy (see Migration Safety Rules)
+2. Write migration file (up + down)
+3. Verify down() is always defined (rollback support)
+
+### Phase 3 — Repository Update
+1. Update repository methods to use new schema
+2. Verify no raw queries reference old column names
+
+**Decision:**
+```
+IF migration is backward-compat AND down() defined → EXIT: SUCCESS
+ELSE IF destructive migration attempted → EXIT: BLOCKED — apply 3-phase strategy
+```
+
+---
+
+## Evidence Format
+```
+[SEVERITY] migration: [filename]
+Issue:      [NOT NULL without default | missing down() | direct DROP]
+Confidence: HIGH
+Fix:        [specific safer strategy]
+```
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Schema, migration, and repository complete | Validated execution |
+| PARTIAL | Migration generated but untested | Missing DB connection |
+| BLOCKED | Fields or relationships ambiguous | Missing entity data |
+| FAILED | Migration involves destructive DROP without backup | Architecture violation |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Entity schema completely defined by user | Implement immediately |
+| MEDIUM | Schema inferred from JSON or forms | Ask for review before generating migration |
+| LOW | "Add database" request with no schema | EXIT: BLOCKED |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Data loss risk in migration | Direct `DROP TABLE` without data copy |
+| HIGH | Missing index on foreign key | Performance degrade on JOIN |
+| MEDIUM | N+1 query vulnerability in repository | Fetching related entities in a loop |
+| LOW | Naming convention violation | `userId` instead of `user_id` in DB |
+
+---
+
+## Retry Policy
+```
+Migration generation fails
+  └─ Syntax error in SQL/ORM
+       ├─ Fix syntax based on engine (Postgres/MySQL)
+       └─ Do NOT retry more than 1 time — risk of bad migration state
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Entity schema undefined
+Missing:
+  - List of fields (types, constraints)
+  - Relationships (1:1, 1:N, M:N)
+Questions:
+  1. Bảng này cần lưu những trường dữ liệu nào?
+  2. Bảng này có liên kết với bảng nào khác không? (ví dụ User)
+Recommended Assumptions:
+  - Add standard created_at, updated_at timestamps
+  - UUID primary keys
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["entity_name", "fields"],
+  "optional_fields": ["relationships", "db_engine"]
+}
+```
+### Produces
+```json
+{
+  "to": "user or db-optimizer",
+  "output_fields": ["schema_file", "migration_file", "repository_file", "exit_code"]
+}
+```
+
+---
+

package/skills/qk-db-optimizer/SKILL.md

@@ -1,41 +1,196 @@
----
-name: qk-db-optimizer
-category: backend
-version: 7.0.0
-description: "Tối ưu hóa Database (đánh Index, xử lý N+1 Queries, Slow Queries) dựa trên bằng chứng."
----
-
-# qk-db-optimizer
-
-## Scope
-- Database Optimization and Performance Auditing (Diagnose & Execute)
-
-## Verbs
-- `[OPTIMIZE]`: Analyze query plans and apply targeted indexes.
-
-## Constraints
-```yaml
-must:
-  - "Analyze EXPLAIN or Query Plans BEFORE adding indexes"
-  - "Solve N+1 queries using Data Loaders or explicit Joins"
-  - "Validate query performance improvements"
-must_not:
-  - "Guess missing indexes without slow query logs"
-  - "Add overlapping or redundant indexes"
-```
-
-## Policies
-```yaml
-prefer:
-  - "Compound indexes for multi-column queries"
-  - "Eager loading over lazy loading for known data relations"
-```
-
-## Escalation
-```yaml
-stop:
-  - "No evidence of slow queries or performance bottlenecks"
-```
-
-## Output
-- Optimized queries and index migration files.
+---
+name: qk-db-optimizer
+category: backend
+version: 7.5.0
+description: "Tối ưu Database dựa trên bằng chứng: EXPLAIN → phân tích → index/join — không đoán mò."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: medium
+latency: medium
+risk: medium
+side_effects: edit_files
+produces: [code, report]
+consumes: [query-log, source-code]
+token_budget:
+  max_files_read: 3
+  max_lines_per_read: 100
+  max_shell_commands: 2
+  stop_early: true
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-db-optimizer — Database Performance Tuner
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Slow query log OR specific slow query is provided
+- [ ] Database schema/ORM models accessible
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Cần: slow query log hoặc query cụ thể cần tối ưu."
+```
+
+---
+
+## Scope
+- ✅ Analyze EXPLAIN/query plans before adding indexes
+- ✅ Solve N+1 with Data Loaders or explicit Joins
+- ✅ Validate performance improvement
+
+## Non-Goals
+- ❌ Add indexes without slow query evidence
+- ❌ Add overlapping or redundant indexes
+- ❌ Optimize queries not shown in slow query log
+
+---
+
+## Priority Order
+| P | Issue Type | Action | Skip Threshold |
+|---|-----------|--------|----------------|
+| P1 | Sequential scan on large table (> 10k rows) | Add composite index | Never |
+| P2 | N+1 query pattern | Eager load / DataLoader | Budget < 30% |
+| P3 | Missing JOIN (multiple queries for related data) | Rewrite with JOIN | Budget < 50% |
+| P4 | SELECT * (over-fetching) | Select specific columns | Budget < 60% |
+
+---
+
+## EXPLAIN Decision Tree
+
+```
+Run EXPLAIN ANALYZE on slow query
+
+IF "Seq Scan" on table > 10k rows
+  → Check cardinality of filter column
+  → IF cardinality > 100 → add B-tree index
+  → IF low cardinality → add partial index or reconsider query
+
+IF "Nested Loop" with many iterations
+  → Check: is this N+1?
+  → IF yes → rewrite as single JOIN or use DataLoader
+
+IF "Sort" without index
+  → Add index on ORDER BY column
+
+IF index exists but not used ("Index Scan" missing)
+  → Check: is WHERE clause using non-leading column of composite index?
+  → Reorder composite index columns
+```
+
+---
+
+## Workflow
+
+### Phase 1 — Evidence Collection
+1. Read slow query log or provided query
+2. Run EXPLAIN ANALYZE (1 command) — or analyze ORM-generated SQL
+3. Identify bottleneck pattern (seq scan / N+1 / sort / over-fetch)
+
+### Phase 2 — Solution Design
+1. Apply Decision Tree above
+2. Design minimal index or query rewrite
+
+### Phase 3 — Apply & Verify
+1. Apply change (add index migration OR rewrite query via `replace_file_content`)
+2. (Optional) Re-run EXPLAIN to verify improvement (2nd command)
+
+**Decision:**
+```
+IF improvement verified → EXIT: SUCCESS
+IF improvement not measurable → EXIT: PARTIAL, note "verify in production"
+```
+
+---
+
+## Evidence Format
+```
+[SEVERITY] query in src/repositories/[name].ts:LINE
+Pattern:    [SEQ_SCAN | N+1 | MISSING_JOIN | OVER_FETCH | UNUSED_INDEX]
+Table:      [table_name] (~N rows estimated)
+Confidence: HIGH
+Fix:        [specific index or rewrite]
+Estimated improvement: [X% reduction in scan rows]
+```
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Index added or query rewritten, improvement verified | Post-optimization |
+| PARTIAL | Optimization applied but could not verify via EXPLAIN | DB access blocked |
+| BLOCKED | Log not provided or DB engine unknown | Missing inputs |
+| FAILED | Optimization breaks existing test or query syntax | Logic error |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | EXPLAIN plan shows SEQ SCAN, user confirms index is missing | Add index / rewrite |
+| MEDIUM | Query looks inefficient but no EXPLAIN available | Ask to run EXPLAIN |
+| LOW | "Make DB faster" with no slow query log | EXIT: BLOCKED |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Query locking table in production | Long running UPDATE |
+| HIGH | Missing index on frequently joined table | Full scan on million rows |
+| MEDIUM | N+1 queries due to missing JOIN | ORM fetching relations in loop |
+| LOW | Over-fetching columns | `SELECT *` instead of specific |
+
+---
+
+## Retry Policy
+```
+EXPLAIN query fails
+  └─ Check SQL syntax error vs connection error
+       ├─ Syntax error → correct SQL → retry EXPLAIN
+       └─ Do NOT retry more than 1 time — risk of locking
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Slow query log not provided
+Missing:
+  - The actual slow query SQL
+  - Current schema of the involved tables
+Questions:
+  1. Câu query nào đang bị chậm? (Xin SQL / ORM log)
+  2. Bảng này hiện đang có những index nào?
+Recommended Assumptions:
+  - Do NOT assume table size or indexes blindly
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["slow_query"],
+  "optional_fields": ["schema", "explain_plan", "db_engine"]
+}
+```
+### Produces
+```json
+{
+  "to": "user",
+  "output_fields": ["optimized_query", "migration_file", "explain_diff", "exit_code"]
+}
+```
+
+---
+