@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/emergence-detector/scripts/check_emergence.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""
+Emergence Detector Script
+Detects unexpected AI behaviors in generated code
+
+Usage:
+    python check_emergence.py <file_or_directory>
+    python check_emergence.py --compare <intent_file> <output_file>
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+
+
+@dataclass
+class EmergenceIssue:
+    type: str  # SCOPE_CREEP, PHANTOM_PACKAGE, PHANTOM_API, SECURITY, PATTERN_DEVIATION
+    severity: str  # CRITICAL, HIGH, MEDIUM, LOW
+    file: str
+    line: Optional[int]
+    detail: str
+    suggestion: Optional[str] = None
+
+
+class EmergenceDetector:
+    """Detect unexpected behaviors in AI-generated code"""
+    
+    # Patterns that suggest hallucinated APIs
+    PHANTOM_API_PATTERNS = [
+        (r"fetch\.advanced\(", "fetch.advanced() does not exist"),
+        (r"console\.print\(", "console.print() does not exist, use console.log()"),
+        (r"Array\.smart\(", "Array.smart() does not exist"),
+        (r"Object\.deepMerge\(", "Object.deepMerge() does not exist"),
+        (r"String\.format\(", "String.format() does not exist in JS"),
+        (r"process\.env\.AUTO_", "AUTO_ prefixed env vars are likely hallucinated"),
+    ]
+    
+    # Security patterns
+    SECURITY_PATTERNS = [
+        (r"eval\s*\(", "Dangerous eval() usage", "CRITICAL"),
+        (r"innerHTML\s*=", "Potential XSS via innerHTML", "HIGH"),
+        (r"document\.write\s*\(", "Deprecated document.write()", "MEDIUM"),
+        (r"exec\s*\(", "Dangerous exec() usage", "CRITICAL"),
+        (r"__import__\s*\(", "Dynamic import can be dangerous", "HIGH"),
+        (r"password\s*=\s*['\"][^'\"]+['\"]", "Hardcoded password detected", "CRITICAL"),
+        (r"api_key\s*=\s*['\"][^'\"]+['\"]", "Hardcoded API key detected", "CRITICAL"),
+        (r"secret\s*=\s*['\"][^'\"]+['\"]", "Hardcoded secret detected", "CRITICAL"),
+    ]
+    
+    def __init__(self, verbose: bool = False):
+        self.verbose = verbose
+        self.issues: List[EmergenceIssue] = []
+    
+    def check_file(self, filepath: str) -> List[EmergenceIssue]:
+        """Check a single file for emergence issues"""
+        issues = []
+        
+        try:
+            with open(filepath, 'r', encoding='utf-8') as f:
+                content = f.read()
+                lines = content.split('\n')
+        except Exception as e:
+            if self.verbose:
+                print(f"Could not read {filepath}: {e}")
+            return issues
+        
+        # Check for phantom APIs
+        for pattern, message in self.PHANTOM_API_PATTERNS:
+            for i, line in enumerate(lines, 1):
+                if re.search(pattern, line):
+                    issues.append(EmergenceIssue(
+                        type="PHANTOM_API",
+                        severity="HIGH",
+                        file=filepath,
+                        line=i,
+                        detail=message,
+                        suggestion="Check official documentation"
+                    ))
+        
+        # Check for security issues
+        for pattern, message, severity in self.SECURITY_PATTERNS:
+            for i, line in enumerate(lines, 1):
+                if re.search(pattern, line, re.IGNORECASE):
+                    issues.append(EmergenceIssue(
+                        type="SECURITY",
+                        severity=severity,
+                        file=filepath,
+                        line=i,
+                        detail=message
+                    ))
+        
+        # Check for phantom packages in imports
+        issues.extend(self._check_imports(filepath, content))
+        
+        return issues
+    
+    def _check_imports(self, filepath: str, content: str) -> List[EmergenceIssue]:
+        """Check if imported packages actually exist"""
+        issues = []
+        
+        # JavaScript/TypeScript imports
+        js_imports = re.findall(r"(?:import\s+.*?from\s+['\"]|require\s*\(\s*['\"])([^'\"./][^'\"]*)['\"]", content)
+        
+        # Python imports
+        py_imports = re.findall(r"^(?:from\s+(\w+)|import\s+(\w+))", content, re.MULTILINE)
+        py_imports = [p[0] or p[1] for p in py_imports]
+        
+        all_imports = js_imports + py_imports
+        
+        for pkg in set(all_imports):
+            if not self._package_exists(pkg, filepath):
+                issues.append(EmergenceIssue(
+                    type="PHANTOM_PACKAGE",
+                    severity="CRITICAL",
+                    file=filepath,
+                    line=None,
+                    detail=f"Package '{pkg}' may not exist",
+                    suggestion=f"Verify package exists: npm view {pkg} OR pip show {pkg}"
+                ))
+        
+        return issues
+    
+    def _package_exists(self, package: str, filepath: str) -> bool:
+        """Check if a package exists (basic heuristic)"""
+        # Skip checking for common/known packages
+        KNOWN_PACKAGES = {
+            # JS/TS
+            'react', 'next', 'express', 'lodash', 'axios', 'moment', 'dayjs',
+            'typescript', 'zod', 'prisma', 'tailwindcss', 'postcss', 'autoprefixer',
+            # Python
+            'os', 'sys', 'json', 're', 'datetime', 'pathlib', 'typing',
+            'requests', 'flask', 'django', 'fastapi', 'pydantic',
+        }
+        
+        base_pkg = package.split('/')[0].split('.')[0]
+        return base_pkg.lower() in KNOWN_PACKAGES
+    
+    def check_directory(self, dirpath: str, extensions: List[str] = None) -> List[EmergenceIssue]:
+        """Check all files in a directory"""
+        if extensions is None:
+            extensions = ['.js', '.jsx', '.ts', '.tsx', '.py', '.go', '.rs']
+        
+        issues = []
+        for root, dirs, files in os.walk(dirpath):
+            # Skip node_modules, .git, etc.
+            dirs[:] = [d for d in dirs if d not in ['node_modules', '.git', 'dist', 'build', '__pycache__']]
+            
+            for file in files:
+                if any(file.endswith(ext) for ext in extensions):
+                    filepath = os.path.join(root, file)
+                    issues.extend(self.check_file(filepath))
+        
+        return issues
+    
+    def compare_intent_output(self, intent: str, output: str) -> Dict[str, Any]:
+        """Compare user intent with AI output to detect scope creep"""
+        # This is a simplified heuristic-based approach
+        # In production, you'd use LLM for semantic comparison
+        
+        intent_keywords = set(re.findall(r'\b\w+\b', intent.lower()))
+        output_keywords = set(re.findall(r'\b\w+\b', output.lower()))
+        
+        # Keywords in output but not in intent might indicate scope creep
+        extra_keywords = output_keywords - intent_keywords
+        
+        # Filter out common code keywords
+        CODE_KEYWORDS = {'const', 'let', 'var', 'function', 'return', 'if', 'else', 
+                         'import', 'export', 'from', 'class', 'interface', 'type'}
+        extra_keywords = extra_keywords - CODE_KEYWORDS
+        
+        return {
+            "potential_scope_creep": len(extra_keywords) > len(intent_keywords) * 2,
+            "extra_concepts": list(extra_keywords)[:20],
+            "recommendation": "Review if these additions were requested" if extra_keywords else "Output appears aligned with intent"
+        }
+    
+    def format_report(self, issues: List[EmergenceIssue]) -> str:
+        """Format issues as a readable report"""
+        if not issues:
+            return "✅ No emergence issues detected"
+        
+        report = []
+        report.append(f"⚠️ EMERGENCE REPORT: {len(issues)} issues found\n")
+        report.append("=" * 50)
+        
+        # Group by severity
+        by_severity = {}
+        for issue in issues:
+            by_severity.setdefault(issue.severity, []).append(issue)
+        
+        severity_order = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']
+        severity_emoji = {'CRITICAL': '🔴', 'HIGH': '🟠', 'MEDIUM': '🟡', 'LOW': '🟢'}
+        
+        for severity in severity_order:
+            if severity in by_severity:
+                report.append(f"\n{severity_emoji[severity]} {severity} ({len(by_severity[severity])})")
+                report.append("-" * 30)
+                for issue in by_severity[severity]:
+                    loc = f":{issue.line}" if issue.line else ""
+                    report.append(f"  [{issue.type}] {issue.file}{loc}")
+                    report.append(f"    → {issue.detail}")
+                    if issue.suggestion:
+                        report.append(f"    💡 {issue.suggestion}")
+        
+        return "\n".join(report)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Detect emergence issues in AI-generated code")
+    parser.add_argument("path", help="File or directory to check")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    parser.add_argument("--verbose", "-v", action="store_true", help="Verbose output")
+    parser.add_argument("--compare", nargs=2, metavar=("INTENT", "OUTPUT"), 
+                        help="Compare intent file with output file")
+    
+    args = parser.parse_args()
+    
+    detector = EmergenceDetector(verbose=args.verbose)
+    
+    if args.compare:
+        with open(args.compare[0]) as f:
+            intent = f.read()
+        with open(args.compare[1]) as f:
+            output = f.read()
+        result = detector.compare_intent_output(intent, output)
+        print(json.dumps(result, indent=2))
+        return
+    
+    path = args.path
+    
+    if os.path.isfile(path):
+        issues = detector.check_file(path)
+    elif os.path.isdir(path):
+        issues = detector.check_directory(path)
+    else:
+        print(f"Error: {path} not found")
+        sys.exit(1)
+    
+    if args.json:
+        print(json.dumps([{
+            "type": i.type,
+            "severity": i.severity,
+            "file": i.file,
+            "line": i.line,
+            "detail": i.detail,
+            "suggestion": i.suggestion
+        } for i in issues], indent=2))
+    else:
+        print(detector.format_report(issues))
+    
+    # Exit with error code if critical issues found
+    if any(i.severity == "CRITICAL" for i in issues):
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/.agent/skills/explained-qa/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: explained-qa
+description: Skill to generate Q&A with explanations for non-tech stakeholders. Use when asking technical questions to PM, Designer, or non-developer users. Includes game-specific terminology database.
+allowed-tools: Read, Glob, Grep
+---
+
+# Explained Q&A Skill
+
+> **Purpose:** Make technical questions accessible to ALL stakeholders by providing real-world analogies and clear options.
+
+---
+
+## When to Use This Skill
+
+| Scenario | Trigger |
+|----------|---------|
+| Asking game architecture questions | User is PM/Designer |
+| Technical decision needed | User skill_level != "technical" |
+| Complex trade-off question | Any user |
+| Game development terminology | Any game project |
+
+---
+
+## Question Format (MANDATORY)
+
+Every technical question MUST follow this structure:
+
+```markdown
+### ❓ [Question Title in Simple Terms]
+
+> 💡 **Giải thích đơn giản (Explained Simply):**
+> [Real-world analogy in 2-3 sentences]
+> 
+> **Ví dụ thực tế:** [Concrete example from everyday life]
+
+**Câu hỏi kỹ thuật:** [Original technical question]
+
+**Lựa chọn:**
+| Option | Mô tả đơn giản | Phù hợp khi |
+|--------|----------------|-------------|
+| (A) [Name] | [Simple description] | [Use case] |
+| (B) [Name] | [Simple description] | [Use case] |
+| (C) Để AI quyết định | Bạn không chắc, để AI chọn dựa trên context | Bạn tin tưởng AI |
+
+**Nếu không chọn:** [Default option + why]
+```
+
+---
+
+## Example: Timestep Question
+
+```markdown
+### ❓ Game của bạn xử lý thời gian như thế nào?
+
+> 💡 **Giải thích đơn giản:**
+> Hãy tưởng tượng game như một bộ phim. Camera có thể quay theo 2 cách:
+> - **Cách A:** Quay đúng 24 khung hình/giây, dù máy nhanh hay chậm
+> - **Cách B:** Quay bao nhiêu khung hình tùy khả năng của máy
+> 
+> **Ví dụ thực tế:** Cách A giống như đồng hồ cơ - luôn đều đặn. Cách B giống như nhịp tim - thay đổi theo hoạt động.
+
+**Câu hỏi kỹ thuật:** Fixed Timestep hay Variable Timestep?
+
+**Lựa chọn:**
+| Option | Mô tả đơn giản | Phù hợp khi |
+|--------|----------------|-------------|
+| (A) Fixed | Chính xác, công bằng | Game PvP, esport, multiplayer |
+| (B) Variable | Mượt mà, linh hoạt | Game casual, single-player |
+| (C) Để AI quyết định | Dựa trên loại game bạn mô tả | Bạn không chắc |
+
+**Nếu không chọn:** Fixed Timestep (an toàn hơn cho hầu hết game)
+```
+
+---
+
+## Analogy Bank (Quick Reference)
+
+| Technical Concept | Analogy |
+|-------------------|---------|
+| **Fixed Timestep** | Đồng hồ cơ - luôn đều đặn |
+| **Variable Timestep** | Nhịp tim - thay đổi theo hoạt động |
+| **ECS** | LEGO - entity là hộp rỗng, component là viên gạch |
+| **State Machine** | Đèn giao thông - chỉ 1 màu tại 1 thời điểm |
+| **Object Pooling** | Hồ bơi bi - tái sử dụng thay vì tạo mới |
+| **Event Bus** | Loa phát thanh - thông báo cho tất cả ai quan tâm |
+| **Singleton** | Vua của vương quốc - chỉ có 1, ai cũng biết |
+| **ScriptableObject** | Công thức nấu ăn - dữ liệu tách riêng khỏi nồi nấu |
+
+> **Full terminology:** See `game-terminology.md` in this skill folder.
+
+---
+
+## Decision Logging
+
+After EVERY answered question, log to `.agent/memory/decisions.md`:
+
+```markdown
+## Session: [DATE]
+
+### Q[N]: [Topic]
+- **Câu hỏi:** [Technical question]
+- **Giải thích:** [Analogy used]
+- **Trả lời:** [User's choice]
+- **Lý do:** "[User's reasoning if provided]"
+- **Ảnh hưởng:** [Technical impact on project]
+
+---
+```
+
+---
+
+## Integration Points
+
+| Skill/Workflow | Integration |
+|----------------|-------------|
+| `brainstorming` | Use Explained Q&A format for all Socratic questions |
+| `/game-from-idea` | Phase 1 ideation uses this for all decisions |
+| `/game-hybrid` | Tier 1 Macro Spec uses this for architecture questions |
+| `/gamekit.spec` | All spec clarification questions use this |
+
+---
+
+## Anti-Patterns (AVOID)
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Ask raw technical question | Always include "Giải thích đơn giản" box |
+| Use jargon without context | Provide real-world analogy |
+| Assume user knows terms | Link to terminology if complex |
+| Skip decision logging | ALWAYS log to decisions.md |
+
+---
+
+## Quality Checklist
+
+Before asking any question:
+
+- [ ] Analogy is from everyday life (not another tech domain)
+- [ ] Options have simple descriptions
+- [ ] "Để AI quyết định" option available
+- [ ] Default specified if user skips
+- [ ] Decision will be logged after answer

package/.agent/skills/explained-qa/game-terminology.md

@@ -0,0 +1,214 @@
+# Game Development Terminology - Explained for Non-Tech
+
+> Database of game development terms with simple explanations and real-world analogies.
+> Used by `explained-qa` skill to help PM, Designer, and non-developers understand technical decisions.
+
+---
+
+## 🎮 Core Game Concepts
+
+### Game Loop
+**Technical:** The continuous cycle of input-update-render that runs every frame.
+**Simple:** Như nhịp tim của game - liên tục đập: đọc nút bấm → tính toán → vẽ lên màn hình.
+**Ví dụ:** Mỗi lần "đập" là 1/60 giây (60 FPS).
+
+### Fixed Timestep
+**Technical:** Game logic updates at a constant rate regardless of frame rate.
+**Simple:** Như đồng hồ cơ học - luôn tích tắc đều đặn, dù pin yếu hay mạnh.
+**Phù hợp:** Game cần công bằng (PvP, esport), multiplayer sync.
+
+### Variable Timestep
+**Technical:** Game logic updates based on actual time elapsed since last frame.
+**Simple:** Như nhịp tim - đập nhanh hơn khi chạy, chậm hơn khi nghỉ.
+**Phù hợp:** Game single-player, casual, cần mượt mà trên nhiều máy.
+
+### Frame Rate (FPS)
+**Technical:** Frames per second - how many images drawn per second.
+**Simple:** Như flipbook (sách lật) - càng nhiều trang/giây, hoạt hình càng mượt.
+**Chuẩn:** 30 FPS = chấp nhận được, 60 FPS = mượt, 120 FPS = cực mượt.
+
+---
+
+## 🏗️ Architecture Patterns
+
+### ECS (Entity Component System)
+**Technical:** Architecture separating entities (IDs), components (data), and systems (logic).
+**Simple:** Như LEGO - Entity là hộp rỗng, Component là viên gạch bạn gắn vào (tốc độ, máu, hình ảnh).
+**Phù hợp:** Game có nhiều đối tượng tương tự (bullet hell, RTS, particle systems).
+
+### State Machine
+**Technical:** System where object can only be in one state at a time, with defined transitions.
+**Simple:** Như đèn giao thông - chỉ có thể Đỏ HOẶC Vàng HOẶC Xanh, không bao giờ 2 màu cùng lúc.
+**Phù hợp:** Nhân vật (Idle→Walk→Jump), AI đơn giản, menu states.
+
+### Object Pooling
+**Technical:** Reusing objects instead of creating/destroying them.
+**Simple:** Như hồ bơi bi - khi cần bi, lấy từ hồ ra; khi xong, trả lại hồ thay vì vứt đi.
+**Phù hợp:** Đạn, particle, enemies spawn nhiều - tránh lag do tạo/xóa liên tục.
+
+### Singleton
+**Technical:** Design pattern ensuring only one instance of a class exists.
+**Simple:** Như Vua của vương quốc - chỉ có 1, ai cũng biết ai là Vua, không cần hỏi.
+**Phù hợp:** GameManager, AudioManager, UIManager - những thứ chỉ cần 1 cái duy nhất.
+
+### Event Bus / Observer
+**Technical:** Publish-subscribe pattern for decoupled communication.
+**Simple:** Như loa phát thanh trong trường - khi có thông báo, ai quan tâm thì nghe.
+**Phù hợp:** UI cập nhật khi điểm thay đổi, Achievement unlock khi đạt điều kiện.
+
+### ScriptableObject (Unity)
+**Technical:** Data containers that store configuration separate from code.
+**Simple:** Như công thức nấu ăn tách riêng khỏi nồi nấu - thay đổi công thức không cần đập nồi.
+**Phù hợp:** Game balance (damage, speed), item definitions, level configs.
+
+---
+
+## 🎨 Graphics & Rendering
+
+### Sprite
+**Technical:** 2D image used as game object.
+**Simple:** Như sticker dán - hình 2D di chuyển trên màn hình.
+**Phù hợp:** Game 2D, UI elements.
+
+### Shader
+**Technical:** Program that runs on GPU to determine how pixels look.
+**Simple:** Như filter Instagram - thay đổi cách hình ảnh được hiển thị.
+**Phù hợp:** Effects (glow, blur, water), visual style.
+
+### Draw Call
+**Technical:** Command sent to GPU to render something.
+**Simple:** Như đơn hàng gửi đến nhà bếp - mỗi đơn tốn thời gian xử lý.
+**Quan trọng:** Ít draw call = game chạy nhanh hơn.
+
+### Batching
+**Technical:** Combining multiple draw calls into one.
+**Simple:** Như gom nhiều đơn hàng nhỏ thành 1 đơn lớn - nhà bếp xử lý nhanh hơn.
+**Phù hợp:** Khi có nhiều object giống nhau (cây, đá, enemy cùng loại).
+
+### LOD (Level of Detail)
+**Technical:** Using simpler models for distant objects.
+**Simple:** Như mắt người - nhìn xa thấy mờ, nhìn gần thấy chi tiết.
+**Phù hợp:** Game 3D với world lớn, open world.
+
+---
+
+## 🔊 Audio
+
+### Spatial Audio
+**Technical:** 3D positioned sound that changes based on listener position.
+**Simple:** Như tai người thật - nghe được âm thanh từ trái/phải/trước/sau.
+**Phù hợp:** Game FPS, VR, horror - cần biết hướng âm thanh.
+
+### Audio Mixer
+**Technical:** Tool to control volume and effects for groups of sounds.
+**Simple:** Như bàn trộn DJ - điều chỉnh âm lượng Music, SFX, Voice riêng biệt.
+**Phù hợp:** Mọi game cần settings âm thanh.
+
+---
+
+## 🌐 Multiplayer
+
+### Client-Server
+**Technical:** Architecture where server is authoritative and clients send inputs.
+**Simple:** Như lớp học - Thầy giáo (server) quyết định điểm, học sinh (client) chỉ nộp bài.
+**Phù hợp:** Game cần chống gian lận, competitive.
+
+### Peer-to-Peer (P2P)
+**Technical:** Direct connection between players without central server.
+**Simple:** Như nhóm bạn nói chuyện trực tiếp - không qua ai trung gian.
+**Phù hợp:** Game casual, co-op, ít người chơi.
+
+### Lag Compensation
+**Technical:** Techniques to hide network latency from players.
+**Simple:** Như dự đoán thời tiết - đoán trước vị trí người chơi để game vẫn mượt dù mạng chậm.
+**Phù hợp:** Game FPS tốc độ cao, fighting games.
+
+### Rollback Netcode
+**Technical:** Predicting inputs and correcting when actual inputs arrive.
+**Simple:** Như viết thư - đoán thư trả lời trước, sửa lại nếu đoán sai.
+**Phù hợp:** Fighting games, games cần phản hồi tức thì.
+
+---
+
+## 💾 Data & Save
+
+### PlayerPrefs
+**Technical:** Simple key-value storage for small data.
+**Simple:** Như ghi chú Post-it - nhanh, tiện, nhưng chỉ cho thông tin nhỏ.
+**Phù hợp:** Settings, high scores, simple progress.
+
+### JSON Save
+**Technical:** Structured data format saved as text file.
+**Simple:** Như hồ sơ bệnh án - có cấu trúc rõ ràng, dễ đọc.
+**Phù hợp:** Complex game state, inventory, quest progress.
+
+### Cloud Save
+**Technical:** Saving game data to remote server.
+**Simple:** Như lưu file lên Google Drive - chơi máy nào cũng có dữ liệu.
+**Phù hợp:** Game mobile, cross-platform, account-based.
+
+---
+
+## 📊 AI & Behavior
+
+### Behavior Tree
+**Technical:** Hierarchical structure for complex AI decision making.
+**Simple:** Như sơ đồ tư duy - "Nếu thấy địch → tiến công, nếu máu thấp → chạy".
+**Phù hợp:** AI phức tạp, boss patterns, NPCs thông minh.
+
+### Finite State Machine (FSM)
+**Technical:** AI with discrete states and transitions.
+**Simple:** Như đèn giao thông cho AI - Patrol → Chase → Attack → Return.
+**Phù hợp:** AI đơn giản đến trung bình, enemies cơ bản.
+
+### Pathfinding (A*)
+**Technical:** Algorithm to find shortest path between points.
+**Simple:** Như Google Maps cho nhân vật - tìm đường đi ngắn nhất tránh vật cản.
+**Phù hợp:** Bất kỳ game nào AI cần di chuyển thông minh.
+
+---
+
+## 🎯 Game Design Terms
+
+### Core Loop
+**Technical:** The primary repeated gameplay cycle.
+**Simple:** Vòng lặp 30 giây mà người chơi lặp đi lặp lại: Hành động → Phần thưởng → Tiến bộ.
+**Ví dụ:** Candy Crush: Ghép → Điểm → Level mới.
+
+### Progression System
+**Technical:** How players advance and unlock content.
+**Simple:** Như leo thang - mỗi bậc là reward mới, giữ người chơi muốn tiếp tục.
+**Ví dụ:** XP + Level, Skill Tree, Story chapters.
+
+### Meta Game
+**Technical:** Systems outside core gameplay that affect long-term engagement.
+**Simple:** "Game ngoài game" - collection, achievements, daily rewards.
+**Phù hợp:** F2P games, live service games.
+
+### Gacha
+**Technical:** Random reward system, often monetized.
+**Simple:** Như máy gắp thú - bỏ tiền, quay ngẫu nhiên, may mắn được đồ hiếm.
+**Lưu ý:** Cần cân nhắc ethical design.
+
+---
+
+## 🔧 Performance
+
+### Garbage Collection (GC)
+**Technical:** Automatic memory cleanup that can cause frame drops.
+**Simple:** Như dọn rác tự động - đôi khi dừng mọi thứ để dọn, gây giật.
+**Giải pháp:** Object pooling, tránh tạo object trong Update().
+
+### Memory Leak
+**Technical:** Memory not released when no longer needed.
+**Simple:** Như bồn rửa bị tắc - nước (memory) cứ đổ vào mà không thoát ra.
+**Hậu quả:** Game ngày càng chậm, crash.
+
+### Profiling
+**Technical:** Measuring performance to find bottlenecks.
+**Simple:** Như khám sức khỏe cho game - tìm chỗ nào "bệnh" (chậm) để chữa.
+**Tool:** Unity Profiler, Godot Profiler, Chrome DevTools.
+
+---
+
+*Tài liệu này được sử dụng bởi `explained-qa` skill để giúp mọi người hiểu các quyết định kỹ thuật trong phát triển game.*