# Cognitive Enhancement Suite - Integration Guide

## Quick Start Verification

Test that your cognitive skills are working:

```bash
# Start a new Claude Code session
# Then ask:

"Use cognitive-planner to analyze this task: Add user registration"

# Expected response:
# - Complexity analysis
# - Approach recommendation
# - Integration with Superpowers
```

---

## Skill Interaction Matrix

| User Request | cognitive-planner | cognitive-safety | cognitive-context | Superpowers |
|--------------|-------------------|-----------------|-------------------|-------------|
| "Build a REST API" | ✅ Analyzes complexity | ✅ Validates security | ✅ Detects expertise | ✅ TDD execution |
| "Fix this bug" | ✅ Selects debugging approach | ✅ Checks for vulnerabilities | ✅ Adapts explanation | ✅ Systematic debug |
| "Review this code" | ✅ Assesses review depth | ✅ Security scan | ✅ Detail level | ⚠️ Optional |
| "Add comments" | ⚠️ Simple task | ✅ No secrets in comments | ✅ Language adaptation | ❌ Not needed |
| "Deploy to production" | ✅ Complex planning | ✅ Config validation | ✅ Expert-level | ⚠️ Optional |

---

## Real-World Workflows

### Workflow 1: Feature Development

```
USER: "Add a payment system to my e-commerce site"

↓ COGNITIVE-PLANNER activates
   → Analyzes: COMPLEX task
   → Detects: Security critical
   → Recommends: Detailed plan + Superpowers
   → Confidence: 0.6 (needs clarification)

↓ CLAUDE asks questions
   "What payment provider? Stripe? PayPal?"
   "What's your tech stack?"

↓ USER answers
   "Stripe with Python Django"

↓ COGNITIVE-PLANNER updates
   → Confidence: 0.85
   → Plan: Use Superpowers TDD
   → Security: Critical (PCI compliance)

↓ COGNITIVE-SAFETY activates
   → Blocks: Hardcoded API keys
   → Requires: Environment variables
   → Validates: PCI compliance patterns
   → Warns: Never log card data

↓ SUPERPOWERS executes
   → /superpowers:write-plan
   → /superpowers:execute-plan
   → TDD throughout

↓ COGNITIVE-CONTEXT adapts
   → Language: English
   → Expertise: Intermediate
   → Style: Balanced with security focus

Result: Secure, tested payment integration
```

### Workflow 2: Bug Fixing

```
USER: "Users can't upload files, getting error 500"

↓ COGNITIVE-PLANNER activates
   → Analyzes: MODERATE bug fix
   → Recommends: Systematic debugging
   → Activates: Superpowers debug workflow

↓ SUPERPOWERS:DEBUG-PLAN
   Phase 1: Reproduce
   Phase 2: Isolate
   Phase 3: Root cause
   Phase 4: Fix & verify

↓ During fixing:
   COGNITIVE-SAFETY checks:
   - No hardcoded paths
   - Proper file validation
   - No directory traversal
   - Secure file permissions

↓ COGNITIVE-CONTEXT:
   → Detects: Intermediate developer
   → Provides: Clear explanations
   → Shows: Why each step matters

Result: Systematic fix, security verified, learning achieved
```

### Workflow 3: Code Review

```
USER: "Review this code for issues"

[User provides code snippet]

↓ COGNITIVE-PLANNER
   → Analyzes: Code review task
   → Depth: Based on code complexity

↓ COGNITIVE-SAFETY scans:
   ✅ Check: Hardcoded secrets
   ✅ Check: SQL injection
   ✅ Check: XSS vulnerabilities
   ✅ Check: Command injection
   ✅ Check: File operations
   ✅ Check: Dependencies
   ✅ Check: Error handling

↓ COGNITIVE-CONTEXT
   → Expertise: Developer (code review)
   → Style: Technical, direct
   → Focus: Security + best practices

↓ Response includes:
   1. Security issues (if any)
   2. Best practice violations
   3. Performance considerations
   4. Maintainability suggestions
   5. Positive feedback on good patterns

Result: Comprehensive security-focused code review
```

---

## Integration with Always-Use-Superpowers

If you use the `auto-superpowers` skill, cognitive skills integrate seamlessly:

```
USER MESSAGE
    ↓
[ALWAYS-USE-SUPERPOWERS]
    ↓
Check: Does any Superpowers skill apply?
    ↓
YES → Activate Superpowers skill
    ↓
[COGNITIVE-PLANNER]
    ↓
Assess: Task complexity
    ↓
IF COMPLEX:
    → Use detailed Superpowers workflow
IF SIMPLE:
    → Direct execution (skip overhead)
    ↓
[COGNITIVE-SAFETY]
    ↓
Validate: All code/commands
    ↓
IF SAFE:
    → Proceed
IF UNSAFE:
    → Block or warn
    ↓
[COGNITIVE-CONTEXT]
    ↓
Adapt: Response to user
    ↓
OUTPUT
```

---

## Example Sessions

### Session 1: Beginner Building First API

```
USER: "I want to build an API for my todo app"

🧠 COGNITIVE-PLANNER:
Task: Feature Implementation
Complexity: MODERATE
Approach: Plan then build
Confidence: 0.7

💡 COGNITIVE-CONTEXT:
Level: BEGINNER detected
Style: Educational, detailed
Language: English

🛡️ COGNITIVE-SAFETY:
Will ensure: No secrets in code, proper validation

📋 ACTION PLAN:
1. Clarify requirements
2. Choose framework (Flask/Django/Express)
3. Plan endpoints
4. Implement with Superpowers TDD
5. Security validation

💬 Let me ask you some questions:
- What programming language do you prefer?
- Have you built an API before?
- What features should it have?

USER: "Python, no this is my first one, just CRUD for todos"

🧠 COGNITIVE-PLANNER UPDATE:
Confidence: 0.9
Plan: Use Flask (beginner-friendly)
Superpowers: Activate TDD workflow

💡 COGNITIVE-CONTEXT ADAPTATION:
Beginner → Will explain each step
Show examples
Link to resources

📚 IMPLEMENTATION PLAN:
1. Set up Flask project structure
2. Create Todo model
3. Implement endpoints (POST, GET, PUT, DELETE)
4. Add input validation
5. Write tests (TDD)
6. Security check (cognitive-safety)

🛡️ SECURITY CONSIDERATIONS:
- Input validation (prevent injection)
- Error handling (don't leak internals)
- CORS if needed
- Rate limiting basics

Ready to start? I'll guide you through each step.
```

### Session 2: Expert Optimizing Performance

```
USER: "Optimize this slow database query"

[Provides query with N+1 problem]

🧠 COGNITIVE-PLANNER:
Task: Optimization (Expert level)
Complexty: MODERATE
Approach: Direct analysis

💡 COGNITIVE-CONTEXT:
Level: EXPERT detected
Style: Concise, technical

🔍 ANALYSIS:
Query: SELECT * FROM posts WHERE user_id = X
Problem: N+1 queries in loop
Impact: O(n) database calls

⚡ SOLUTION:
```python
# ❌ BEFORE (N+1)
posts = db.query('SELECT * FROM posts WHERE user_id = ?', user_id)
for post in posts:
    comments = db.query('SELECT * FROM comments WHERE post_id = ?', post.id)
    post.comments = comments

# ✅ AFTER (Single query with JOIN)
posts = db.query('''
    SELECT p.*, c.*
    FROM posts p
    LEFT JOIN comments c ON c.post_id = p.id
    WHERE p.user_id = ?
''', user_id)
```

📊 Performance:
- Before: 1 + N queries
- After: 1 query
- Improvement: O(n) → O(1)

🛡️ COGNITIVE-SAFETY:
✅ Parameterized query (SQL injection safe)
✅ No hardcoded values
✅ Proper error handling needed

💡 CONSIDERATIONS:
- For large datasets: Use pagination
- For complex relations: Consider ORM batching
- For read-heavy: Add caching layer

Want me to implement this with proper error handling?
```

### Session 3: Multilingual Support

```
USER: "Je veux ajouter une page de connexion"

🌐 COGNITIVE-CONTEXT:
Language: FRENCH detected 🇫🇷
Expertise: Intermediate
Style: Balanced, in French

🧠 COGNITIVE-PLANNER:
Tâche: Implémentation de fonctionnalité
Complexité: MODÉRÉE
Approche: Planifier avec Superpowers

📋 PLAN D'ACTION:
1. Créer le modèle User
2. Implémenter l'authentification
3. Créer la page de connexion
4. Ajouter la validation
5. Tests TDD
6. Sécurité (cognitive-safety)

🛡️ SÉCURITÉ:
- Hashage bcrypt pour les mots de passe
- Pas de secrets en dur
- Protection CSRF
- Validation des entrées

💡 EXEMPLE DE CODE:
```python
# login route
@app.route('/login', methods=['POST'])
def login():
    username = request.form.get('username')
    password = request.form.get('password')

    # Validation
    if not username or not password:
        return 'Missing credentials', 400

    # Authentification
    user = User.query.filter_by(username=username).first()
    if user and bcrypt.check_password_hash(user.password, password):
        login_user(user)
        return redirect('/dashboard')

    return 'Invalid credentials', 401
```

Voulez-vous que je mette en œuvre cela avec des tests?
```

---

## Customization

### Adjusting Complexity Threshold

```bash
# ~/.env
COGNITIVE_PLANNER_THRESHOLD=low  # Plan more tasks
COGNITIVE_PLANNER_THRESHOLD=high  # Plan only complex tasks
```

### Safety Strict Mode

```bash
# ~/.env
COGNITIVE_SAFETY_STRICT_MODE=true  # Block all potentially unsafe
COGNITIVE_SAFETY_STRICT_MODE=false # Warn but allow
```

### Language Preference

```bash
# ~/.env
COGNITIVE_CONTEXT_DEFAULT_LANGUAGE=spanish
```

---

## Troubleshooting Integration

### Problem: Skills conflict

```
SYMPTOM: Multiple skills trying to handle same task

SOLUTION: Skills have priority order
1. cognitive-planner (analyzes first)
2. cognitive-safety (validates)
3. cognitive-context (adapts)
4. Superpowers (executes)

If conflict: cognitive-planner decides which to use
```

### Problem: Too much planning overhead

```
SYMPTOM: Every task gets planned, even simple ones

SOLUTION: Adjust threshold
# ~/.env
COGNITIVE_PLANNER_AUTO_SIMPLE=true  # Auto-handle simple tasks
COGNITIVE_PLANNER_SIMPLE_THRESHOLD=5  # <5 minutes = simple
```

### Problem: Safety too strict

```
SYMPTOM: Legitimate code gets blocked

SOLUTION:
1. Acknowledge you understand risk
2. cognitive-safety will allow with warning
3. Or set strict mode in .env
```

---

## Performance Impact

Cognitive skills add minimal overhead:

```
WITHOUT COGNITIVE SKILLS:
User request → Immediate execution

WITH COGNITIVE SKILLS:
User request → Context analysis (0.1s)
             → Complexity check (0.1s)
             → Safety validation (0.2s)
             → Execution
             → Total overhead: ~0.4s

BENEFIT: Prevents hours of debugging, security issues
```

---

## Best Practices

1. **Trust the analysis**
   - cognitive-planner assesses complexity accurately
   - Use its recommendations

2. **Heed safety warnings**
   - cognitive-safety prevents real vulnerabilities
   - Don't ignore warnings

3. **Let it adapt**
   - cognitive-context learns from you
   - Respond naturally, it will adjust

4. **Use with Superpowers**
   - Best results when combined
   - Planning + TDD + Safety = Quality

5. **Provide feedback**
   - If expertise level is wrong, say so
   - If language is wrong, specify
   - Skills learn and improve

---

## FAQ

**Q: Do I need to activate these skills?**
A: No, they activate automatically when needed.

**Q: Will they slow down my workflow?**
A: Minimal overhead (~0.4s), but prevent major issues.

**Q: Can I disable specific skills?**
A: Yes, remove or rename the SKILL.md file.

**Q: Do they work offline?**
A: Yes, all logic is local (no API calls).

**Q: Are my code snippets sent anywhere?**
A: No, everything stays on your machine.

**Q: Can I add my own patterns?**
A: Yes, edit the SKILL.md files to customize.

---

## Next Steps

1. ✅ Skills installed
2. ✅ Integration guide read
3. → Start using Claude Code normally
4. → Skills will activate when needed
5. → Adapt and provide feedback

---

<div align="center">

**Happy coding with enhanced cognition! 🧠**

</div>