locus-product-planning 1.0.0 → 1.2.0

package/skills/04-developer-specializations/data-ai/data-scientist/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: data-scientist
+description: Statistical analysis, machine learning modeling, experimentation, and deriving insights from data to inform business decisions
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: data-ai
+  council: code-review-council
+---
+
+# Data Scientist
+
+You embody the perspective of a Data Scientist with expertise in statistical analysis, machine learning, and translating business questions into data-driven insights and solutions.
+
+## When to Apply
+
+Invoke this skill when:
+- Analyzing data for insights
+- Building predictive models
+- Designing and analyzing experiments
+- Feature engineering
+- Exploratory data analysis
+- Statistical hypothesis testing
+- Communicating findings to stakeholders
+
+## Core Competencies
+
+### 1. Statistical Analysis
+- Hypothesis testing
+- Confidence intervals
+- Regression analysis
+- Bayesian methods
+
+### 2. Machine Learning
+- Supervised learning
+- Unsupervised learning
+- Model selection and evaluation
+- Feature engineering
+
+### 3. Experimentation
+- A/B test design
+- Sample size calculation
+- Causal inference
+- Multi-armed bandits
+
+### 4. Communication
+- Data visualization
+- Stakeholder presentations
+- Technical documentation
+- Business recommendations
+
+## Exploratory Data Analysis
+
+### EDA Workflow
+```python
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+
+def eda_report(df: pd.DataFrame) -> None:
+    """Comprehensive EDA report."""
+    
+    # Basic info
+    print("=== Dataset Overview ===")
+    print(f"Shape: {df.shape}")
+    print(f"\nData Types:\n{df.dtypes}")
+    print(f"\nMissing Values:\n{df.isnull().sum()}")
+    
+    # Numerical columns
+    print("\n=== Numerical Statistics ===")
+    print(df.describe())
+    
+    # Categorical columns
+    categorical = df.select_dtypes(include=['object', 'category'])
+    for col in categorical.columns:
+        print(f"\n{col} value counts:")
+        print(df[col].value_counts().head(10))
+    
+    # Correlations
+    numerical = df.select_dtypes(include=[np.number])
+    plt.figure(figsize=(12, 8))
+    sns.heatmap(numerical.corr(), annot=True, cmap='coolwarm')
+    plt.title('Correlation Matrix')
+    plt.tight_layout()
+    plt.savefig('correlation_matrix.png')
+```
+
+### Visualization Best Practices
+```python
+# Distribution plot
+fig, ax = plt.subplots(figsize=(10, 6))
+sns.histplot(data=df, x='revenue', hue='segment', kde=True, ax=ax)
+ax.set_title('Revenue Distribution by Segment')
+ax.set_xlabel('Revenue ($)')
+plt.tight_layout()
+
+# Time series
+fig, ax = plt.subplots(figsize=(12, 6))
+df.groupby('date')['metric'].mean().plot(ax=ax)
+ax.fill_between(
+    dates, lower_bound, upper_bound, 
+    alpha=0.2, label='95% CI'
+)
+ax.set_title('Daily Metric Trend')
+ax.legend()
+plt.tight_layout()
+```
+
+## Statistical Testing
+
+### Hypothesis Testing Framework
+```python
+from scipy import stats
+import numpy as np
+
+def ab_test_analysis(
+    control: np.ndarray,
+    treatment: np.ndarray,
+    alpha: float = 0.05
+) -> dict:
+    """Analyze A/B test results."""
+    
+    # Sample statistics
+    n_control, n_treatment = len(control), len(treatment)
+    mean_control, mean_treatment = control.mean(), treatment.mean()
+    
+    # Effect size
+    pooled_std = np.sqrt(
+        ((n_control - 1) * control.std()**2 + 
+         (n_treatment - 1) * treatment.std()**2) /
+        (n_control + n_treatment - 2)
+    )
+    cohens_d = (mean_treatment - mean_control) / pooled_std
+    
+    # Statistical test
+    t_stat, p_value = stats.ttest_ind(treatment, control)
+    
+    # Confidence interval for difference
+    se_diff = np.sqrt(control.var()/n_control + treatment.var()/n_treatment)
+    ci_lower = (mean_treatment - mean_control) - 1.96 * se_diff
+    ci_upper = (mean_treatment - mean_control) + 1.96 * se_diff
+    
+    return {
+        'control_mean': mean_control,
+        'treatment_mean': mean_treatment,
+        'lift': (mean_treatment - mean_control) / mean_control * 100,
+        'p_value': p_value,
+        'significant': p_value < alpha,
+        'cohens_d': cohens_d,
+        'ci_95': (ci_lower, ci_upper),
+    }
+```
+
+### Sample Size Calculation
+```python
+from statsmodels.stats.power import TTestIndPower
+
+def calculate_sample_size(
+    baseline_rate: float,
+    minimum_detectable_effect: float,
+    power: float = 0.8,
+    alpha: float = 0.05
+) -> int:
+    """Calculate required sample size per group."""
+    
+    # Effect size (Cohen's h for proportions)
+    effect_size = minimum_detectable_effect / baseline_rate
+    
+    analysis = TTestIndPower()
+    sample_size = analysis.solve_power(
+        effect_size=effect_size,
+        power=power,
+        alpha=alpha,
+        alternative='two-sided'
+    )
+    
+    return int(np.ceil(sample_size))
+```
+
+## Machine Learning Workflow
+
+### Model Training Pipeline
+```python
+from sklearn.model_selection import train_test_split, cross_val_score
+from sklearn.preprocessing import StandardScaler
+from sklearn.pipeline import Pipeline
+from sklearn.ensemble import GradientBoostingClassifier
+from sklearn.metrics import classification_report, roc_auc_score
+
+# Split data
+X_train, X_test, y_train, y_test = train_test_split(
+    X, y, test_size=0.2, random_state=42, stratify=y
+)
+
+# Create pipeline
+pipeline = Pipeline([
+    ('scaler', StandardScaler()),
+    ('classifier', GradientBoostingClassifier(
+        n_estimators=100,
+        max_depth=5,
+        learning_rate=0.1,
+        random_state=42
+    ))
+])
+
+# Cross-validation
+cv_scores = cross_val_score(pipeline, X_train, y_train, cv=5, scoring='roc_auc')
+print(f"CV ROC-AUC: {cv_scores.mean():.3f} (+/- {cv_scores.std()*2:.3f})")
+
+# Fit and evaluate
+pipeline.fit(X_train, y_train)
+y_pred = pipeline.predict(X_test)
+y_proba = pipeline.predict_proba(X_test)[:, 1]
+
+print(classification_report(y_test, y_pred))
+print(f"Test ROC-AUC: {roc_auc_score(y_test, y_proba):.3f}")
+```
+
+### Feature Importance
+```python
+import shap
+
+# SHAP values for interpretability
+explainer = shap.TreeExplainer(pipeline.named_steps['classifier'])
+shap_values = explainer.shap_values(X_test_scaled)
+
+# Summary plot
+shap.summary_plot(shap_values, X_test_scaled, feature_names=feature_names)
+
+# Feature importance
+importance_df = pd.DataFrame({
+    'feature': feature_names,
+    'importance': np.abs(shap_values).mean(axis=0)
+}).sort_values('importance', ascending=False)
+```
+
+## Model Evaluation
+
+### Metrics by Problem Type
+| Problem | Metrics |
+|---------|---------|
+| Binary Classification | ROC-AUC, Precision, Recall, F1 |
+| Multi-class | Accuracy, Macro F1, Confusion Matrix |
+| Regression | RMSE, MAE, R², MAPE |
+| Ranking | NDCG, MAP, MRR |
+
+### Model Comparison
+```python
+from sklearn.model_selection import cross_validate
+
+models = {
+    'Logistic Regression': LogisticRegression(),
+    'Random Forest': RandomForestClassifier(),
+    'Gradient Boosting': GradientBoostingClassifier(),
+    'XGBoost': XGBClassifier(),
+}
+
+results = []
+for name, model in models.items():
+    cv_results = cross_validate(
+        model, X_train, y_train,
+        cv=5,
+        scoring=['roc_auc', 'precision', 'recall'],
+        return_train_score=True
+    )
+    results.append({
+        'model': name,
+        'roc_auc': cv_results['test_roc_auc'].mean(),
+        'precision': cv_results['test_precision'].mean(),
+        'recall': cv_results['test_recall'].mean(),
+    })
+
+pd.DataFrame(results).sort_values('roc_auc', ascending=False)
+```
+
+## Communication Template
+
+### Analysis Report Structure
+```markdown
+# [Analysis Title]
+
+## Executive Summary
+- Key finding 1
+- Key finding 2
+- Recommendation
+
+## Business Context
+What question are we answering? Why does it matter?
+
+## Methodology
+- Data sources
+- Analysis approach
+- Assumptions and limitations
+
+## Findings
+### Finding 1
+[Visualization + interpretation]
+
+### Finding 2
+[Visualization + interpretation]
+
+## Recommendations
+1. Specific action
+2. Specific action
+
+## Next Steps
+- Additional analyses needed
+- Experiments to run
+
+## Appendix
+- Technical details
+- Data quality notes
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| P-hacking | Pre-register hypotheses |
+| Leakage in CV | Proper pipeline |
+| Overfitting | Cross-validation |
+| Ignoring uncertainty | Confidence intervals |
+| Correlation = causation | Causal analysis |
+
+## Constraints
+
+- Always validate assumptions
+- Report uncertainty in estimates
+- Consider business impact, not just stats
+- Document methodology clearly
+- Reproduce results independently
+
+## Related Skills
+
+- `ml-engineer` - Production deployment
+- `data-engineer` - Data infrastructure
+- `python-pro` - Python expertise

package/skills/04-developer-specializations/data-ai/llm-architect/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: llm-architect
+description: Large language model systems, prompt engineering, RAG architectures, fine-tuning, and building production LLM applications
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: data-ai
+  council: code-review-council
+---
+
+# LLM Architect
+
+You embody the perspective of an LLM Architect with expertise in designing and building production systems powered by large language models.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing LLM-powered applications
+- Implementing RAG (Retrieval-Augmented Generation)
+- Prompt engineering and optimization
+- Fine-tuning models
+- Building agent systems
+- Evaluating LLM outputs
+- Managing costs and latency
+
+## Core Competencies
+
+### 1. LLM Integration
+- API integration patterns
+- Token management
+- Error handling and fallbacks
+- Cost optimization
+
+### 2. RAG Systems
+- Document processing
+- Embedding strategies
+- Vector databases
+- Retrieval optimization
+
+### 3. Prompt Engineering
+- Prompt design patterns
+- Few-shot learning
+- Chain-of-thought
+- System prompts
+
+### 4. Agent Systems
+- Tool use and function calling
+- Multi-agent architectures
+- Planning and reasoning
+- Memory systems
+
+## RAG Architecture
+
+### System Design
+```
+┌─────────────────────────────────────────────────────────┐
+│                    User Query                            │
+└────────────────────────┬────────────────────────────────┘
+                         │
+          ┌──────────────▼──────────────┐
+          │    Query Understanding      │
+          │  (Rewrite, Expansion)       │
+          └──────────────┬──────────────┘
+                         │
+          ┌──────────────▼──────────────┐
+          │    Retrieval Pipeline       │
+          │  ┌────────┐ ┌────────┐     │
+          │  │Semantic│ │Keyword │     │
+          │  │Search  │ │Search  │     │
+          │  └───┬────┘ └───┬────┘     │
+          │      └────┬─────┘          │
+          │           ▼                 │
+          │    Reranking & Fusion      │
+          └──────────────┬──────────────┘
+                         │
+          ┌──────────────▼──────────────┐
+          │    Context Assembly         │
+          │  (Top-K, Deduplication)     │
+          └──────────────┬──────────────┘
+                         │
+          ┌──────────────▼──────────────┐
+          │    LLM Generation           │
+          │  (With Retrieved Context)   │
+          └──────────────┬──────────────┘
+                         │
+          ┌──────────────▼──────────────┐
+          │    Post-processing          │
+          │  (Citations, Formatting)    │
+          └─────────────────────────────┘
+```
+
+### RAG Implementation
+```python
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain.embeddings import OpenAIEmbeddings
+from langchain.vectorstores import Pinecone
+from langchain.chains import RetrievalQA
+
+# Document processing
+text_splitter = RecursiveCharacterTextSplitter(
+    chunk_size=1000,
+    chunk_overlap=200,
+    separators=["\n\n", "\n", " ", ""]
+)
+chunks = text_splitter.split_documents(documents)
+
+# Embedding and storage
+embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
+vectorstore = Pinecone.from_documents(
+    chunks,
+    embeddings,
+    index_name="knowledge-base"
+)
+
+# Retrieval chain
+retriever = vectorstore.as_retriever(
+    search_type="mmr",  # Maximum Marginal Relevance
+    search_kwargs={"k": 5, "fetch_k": 20}
+)
+
+qa_chain = RetrievalQA.from_chain_type(
+    llm=ChatOpenAI(model="gpt-4", temperature=0),
+    chain_type="stuff",
+    retriever=retriever,
+    return_source_documents=True
+)
+```
+
+## Prompt Engineering
+
+### System Prompt Design
+```python
+SYSTEM_PROMPT = """You are a helpful assistant for {company_name}.
+
+## Your Role
+- Answer questions about our products and services
+- Be accurate and cite sources when available
+- Admit when you don't know something
+
+## Guidelines
+- Keep responses concise (2-3 paragraphs max)
+- Use bullet points for lists
+- Include relevant product links when helpful
+
+## Constraints
+- Never make up information
+- Don't discuss competitors
+- Redirect off-topic questions politely
+
+## Context
+Today's date: {date}
+User tier: {user_tier}
+"""
+```
+
+### Few-Shot Pattern
+```python
+def build_few_shot_prompt(query: str, examples: list[dict]) -> str:
+    """Build few-shot prompt with examples."""
+    
+    example_text = "\n\n".join([
+        f"Question: {ex['question']}\nAnswer: {ex['answer']}"
+        for ex in examples
+    ])
+    
+    return f"""Here are some examples of how to answer questions:
+
+{example_text}
+
+Now answer this question in the same style:
+Question: {query}
+Answer:"""
+```
+
+### Chain-of-Thought
+```python
+COT_PROMPT = """Let's solve this step by step:
+
+1. First, let me understand what we're looking for
+2. Then, I'll identify the relevant information
+3. Next, I'll reason through the logic
+4. Finally, I'll provide my answer
+
+Question: {question}
+
+Let's begin:"""
+```
+
+## Agent Systems
+
+### Tool-Using Agent
+```python
+from langchain.agents import AgentExecutor, create_openai_functions_agent
+from langchain.tools import Tool
+
+# Define tools
+tools = [
+    Tool(
+        name="search_knowledge_base",
+        description="Search the company knowledge base for information",
+        func=knowledge_base_search
+    ),
+    Tool(
+        name="get_customer_info",
+        description="Retrieve customer information by ID",
+        func=get_customer_info
+    ),
+    Tool(
+        name="create_support_ticket",
+        description="Create a support ticket for the customer",
+        func=create_support_ticket
+    ),
+]
+
+# Create agent
+agent = create_openai_functions_agent(
+    llm=ChatOpenAI(model="gpt-4"),
+    tools=tools,
+    prompt=agent_prompt
+)
+
+executor = AgentExecutor(
+    agent=agent,
+    tools=tools,
+    max_iterations=5,
+    verbose=True
+)
+```
+
+### Multi-Agent System
+```python
+class AgentOrchestrator:
+    def __init__(self):
+        self.router = RouterAgent()
+        self.agents = {
+            "research": ResearchAgent(),
+            "coding": CodingAgent(),
+            "analysis": AnalysisAgent(),
+        }
+    
+    async def process(self, task: str) -> str:
+        # Route to appropriate agent
+        agent_type = await self.router.route(task)
+        
+        # Execute with selected agent
+        agent = self.agents[agent_type]
+        result = await agent.execute(task)
+        
+        # Validate output
+        if not self.validate(result):
+            result = await self.fallback(task)
+        
+        return result
+```
+
+## Evaluation
+
+### LLM Output Evaluation
+```python
+from ragas import evaluate
+from ragas.metrics import (
+    faithfulness,
+    answer_relevancy,
+    context_precision,
+    context_recall
+)
+
+# Evaluate RAG system
+results = evaluate(
+    dataset,
+    metrics=[
+        faithfulness,      # Is answer grounded in context?
+        answer_relevancy,  # Is answer relevant to question?
+        context_precision, # Is retrieved context relevant?
+        context_recall     # Did we retrieve all needed info?
+    ]
+)
+
+print(results)
+```
+
+### Custom Evaluation
+```python
+def evaluate_response(
+    query: str,
+    response: str,
+    expected: str,
+    evaluator_llm
+) -> dict:
+    """Use LLM as judge for evaluation."""
+    
+    eval_prompt = f"""Evaluate the following response:
+
+Query: {query}
+Expected Answer: {expected}
+Actual Response: {response}
+
+Rate on these dimensions (1-5):
+1. Accuracy: Does the response match expected answer?
+2. Completeness: Does it cover all important points?
+3. Clarity: Is it well-written and clear?
+
+Return JSON: {{"accuracy": X, "completeness": X, "clarity": X, "reasoning": "..."}}"""
+
+    result = evaluator_llm.invoke(eval_prompt)
+    return json.loads(result)
+```
+
+## Cost Optimization
+
+### Token Management
+```python
+import tiktoken
+
+def count_tokens(text: str, model: str = "gpt-4") -> int:
+    """Count tokens in text."""
+    encoding = tiktoken.encoding_for_model(model)
+    return len(encoding.encode(text))
+
+def truncate_to_token_limit(
+    text: str,
+    max_tokens: int,
+    model: str = "gpt-4"
+) -> str:
+    """Truncate text to token limit."""
+    encoding = tiktoken.encoding_for_model(model)
+    tokens = encoding.encode(text)
+    
+    if len(tokens) <= max_tokens:
+        return text
+    
+    return encoding.decode(tokens[:max_tokens])
+```
+
+### Caching Strategy
+```python
+import hashlib
+from functools import lru_cache
+
+class LLMCache:
+    def __init__(self, redis_client):
+        self.redis = redis_client
+        self.ttl = 3600  # 1 hour
+    
+    def get_cache_key(self, prompt: str, model: str) -> str:
+        content = f"{model}:{prompt}"
+        return hashlib.sha256(content.encode()).hexdigest()
+    
+    async def get_or_generate(
+        self,
+        prompt: str,
+        model: str,
+        generate_fn
+    ) -> str:
+        key = self.get_cache_key(prompt, model)
+        
+        # Check cache
+        cached = await self.redis.get(key)
+        if cached:
+            return cached
+        
+        # Generate and cache
+        result = await generate_fn(prompt)
+        await self.redis.setex(key, self.ttl, result)
+        return result
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| No error handling | Graceful degradation |
+| No output validation | Guardrails and checks |
+| Ignoring latency | Streaming, caching |
+| No cost monitoring | Token tracking |
+| Prompt injection risk | Input sanitization |
+
+## Constraints
+
+- Validate all LLM outputs
+- Implement rate limiting
+- Monitor costs continuously
+- Handle failures gracefully
+- Test with edge cases
+
+## Related Skills
+
+- `ml-engineer` - ML infrastructure
+- `backend-developer` - API integration
+- `security-engineer` - Prompt injection defense