@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skills/framework-critical-thinking/references/producer_critic_orchestrator.md

@@ -0,0 +1,333 @@
+# Producer-Critic Orchestrator
+
+## Purpose
+
+The Producer-Critic Orchestrator implements the Generate-Critique-Refine pattern for iterative improvement of AI outputs. It coordinates multiple specialized agents to produce higher quality results through structured feedback loops.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Master Agent (Orchestrator)                   │
+└──────────────┬──────────────────────────────────────┬───────────┘
+               │                                      │
+               ▼                                      ▼
+┌────────────────────────┐              ┌────────────────────────┐
+│     Producer Agent     │              │      Critic Agent      │
+│                        │              │                        │
+│  - Generates initial   │─────────────►│  - Evaluates quality   │
+│    output              │              │  - Identifies errors   │
+│  - Incorporates        │◄─────────────│  - Suggests            │
+│    feedback            │   critique   │    improvements        │
+└────────────────────────┘              └────────────────────────┘
+               ▲                                      │
+               │                                      ▼
+               │                         ┌────────────────────────┐
+               │                         │   Refinement Decision  │
+               └─────────────────────────│                        │
+                  (if needs refinement)  │  - Satisfactory?       │
+                                         │  - Budget exhausted?   │
+                                         │  - Max iterations?     │
+                                         └────────────────────────┘
+```
+
+## Components
+
+### Master Agent (Orchestrator)
+
+Coordinates the overall process:
+
+```python
+class ProducerCriticOrchestrator:
+    def __init__(self, config):
+        self.producer = ProducerAgent(config['producer'])
+        self.critic = CriticAgent(config['critic'])
+        self.max_iterations = config.get('max_iterations', 3)
+        self.refinement_budget = config.get('budget', 5)
+        self.satisfaction_threshold = config.get('threshold', 0.8)
+
+    async def generate(self, task, context):
+        iteration = 0
+        history = []
+
+        # Initial generation
+        current_output = await self.producer.generate(task, context)
+
+        while iteration < self.max_iterations:
+            # Get critique
+            critique = await self.critic.evaluate(current_output, task)
+
+            history.append({
+                'iteration': iteration,
+                'output': current_output,
+                'critique': critique
+            })
+
+            # Check if satisfactory
+            if critique['satisfactory']:
+                break
+
+            # Check budget
+            if self.refinement_budget <= 0:
+                break
+
+            # Refine
+            current_output = await self.producer.refine(
+                current_output,
+                critique,
+                context
+            )
+            self.refinement_budget -= 1
+            iteration += 1
+
+        return {
+            'final_output': current_output,
+            'iterations': iteration + 1,
+            'history': history,
+            'was_refined': iteration > 0
+        }
+```
+
+### Producer Agent
+
+Responsible for generation and refinement:
+
+```python
+class ProducerAgent:
+    def __init__(self, config):
+        self.model = config['model']
+        self.temperature = config.get('temperature', 0.7)
+
+    async def generate(self, task, context):
+        prompt = self.build_generation_prompt(task, context)
+        return await self.model.generate(prompt, temperature=self.temperature)
+
+    async def refine(self, current_output, critique, context):
+        refinement_prompt = f"""
+Original task: {context['task']}
+
+Current output:
+{current_output}
+
+Critique:
+{critique['feedback']}
+
+Issues identified:
+{critique['issues']}
+
+Please refine the output addressing all identified issues.
+Maintain the strengths while fixing the weaknesses.
+"""
+        return await self.model.generate(
+            refinement_prompt,
+            temperature=self.temperature * 0.9  # Slightly lower for refinement
+        )
+```
+
+### Critic Agent
+
+Evaluates outputs and provides structured feedback:
+
+```python
+class CriticAgent:
+    def __init__(self, config):
+        self.model = config['model']
+        self.evaluation_criteria = config.get('criteria', [
+            'accuracy', 'completeness', 'clarity', 'relevance'
+        ])
+
+    async def evaluate(self, output, task):
+        critique_prompt = f"""
+Evaluate the following output for the given task.
+
+Task: {task}
+
+Output to evaluate:
+{output}
+
+Provide evaluation in this format:
+1. Overall assessment: (satisfactory/needs improvement)
+2. Scores (0-10):
+   - Accuracy:
+   - Completeness:
+   - Clarity:
+   - Relevance:
+3. Strengths:
+4. Issues identified:
+5. Specific improvement suggestions:
+
+Evaluation:
+"""
+
+        evaluation = await self.model.generate(critique_prompt)
+        parsed = self.parse_evaluation(evaluation)
+
+        return {
+            'satisfactory': parsed['overall'] == 'satisfactory',
+            'scores': parsed['scores'],
+            'average_score': sum(parsed['scores'].values()) / len(parsed['scores']),
+            'strengths': parsed['strengths'],
+            'issues': parsed['issues'],
+            'feedback': parsed['suggestions']
+        }
+```
+
+## Refinement Strategies
+
+### 1. Full Regeneration
+
+Discard current output and generate fresh with critique as context.
+
+**When to use:** Major structural issues or fundamental errors
+
+```python
+def full_regenerate(task, critique_history):
+    context = synthesize_critiques(critique_history)
+    return generate_with_enhanced_context(task, context)
+```
+
+### 2. Targeted Revision
+
+Keep valid portions, only revise problematic sections.
+
+**When to use:** Localized errors or specific improvements needed
+
+```python
+def targeted_revision(output, critique):
+    issues = critique['issues']
+    for issue in issues:
+        if issue['location']:  # If issue has specific location
+            output = revise_section(output, issue)
+    return output
+```
+
+### 3. Progressive Enhancement
+
+Build upon previous output incrementally.
+
+**When to use:** Minor improvements needed
+
+```python
+def progressive_enhancement(output, critique):
+    enhancements = critique['suggestions']
+    for enhancement in enhancements:
+        output = apply_enhancement(output, enhancement)
+    return output
+```
+
+## Budget Management
+
+Control computational cost:
+
+```python
+class RefinementBudget:
+    def __init__(self, max_tokens, max_time, max_iterations):
+        self.max_tokens = max_tokens
+        self.max_time = max_time
+        self.max_iterations = max_iterations
+        self.used_tokens = 0
+        self.start_time = time.now()
+        self.iterations = 0
+
+    def can_continue(self):
+        if self.iterations >= self.max_iterations:
+            return False, "Max iterations reached"
+
+        if self.used_tokens >= self.max_tokens:
+            return False, "Token budget exhausted"
+
+        elapsed = time.now() - self.start_time
+        if elapsed >= self.max_time:
+            return False, "Time budget exhausted"
+
+        return True, "Can continue"
+
+    def consume(self, tokens_used):
+        self.used_tokens += tokens_used
+        self.iterations += 1
+```
+
+## Early Stopping Conditions
+
+Stop refinement when:
+
+```python
+STOP_CONDITIONS = {
+    'satisfactory': lambda s: s['average_score'] >= SATISFACTION_THRESHOLD,
+    'diminishing_returns': lambda h: score_improvement(h) < 0.05,
+    'oscillation': lambda h: detect_oscillation(h),
+    'budget_exhausted': lambda b: b.can_continue()[0] == False
+}
+```
+
+## Usage Patterns
+
+### Pattern 1: Quality-First
+
+Maximize quality regardless of cost:
+
+```python
+config = {
+    'max_iterations': 5,
+    'budget': 10,
+    'threshold': 0.9,
+    'stop_on_satisfaction': True
+}
+```
+
+### Pattern 2: Budget-Constrained
+
+Best quality within budget:
+
+```python
+config = {
+    'max_iterations': 3,
+    'budget': 5,
+    'threshold': 0.8,
+    'early_stop': True
+}
+```
+
+### Pattern 3: Fast Iteration
+
+Quick improvements, accept "good enough":
+
+```python
+config = {
+    'max_iterations': 2,
+    'budget': 3,
+    'threshold': 0.7,
+    'parallel_critiques': True
+}
+```
+
+## Evaluation Metrics
+
+Track orchestration effectiveness:
+
+- **Refinement Success Rate:** % of iterations that improve score
+- **Average Iterations:** Mean iterations before satisfaction or stop
+- **Quality Improvement:** Score delta from initial to final
+- **Cost Efficiency:** Quality gain per token spent
+- **Satisfaction Rate:** % of tasks reaching threshold
+
+## Best Practices
+
+1. **Start with strict criteria** and relax based on performance
+2. **Log all critiques** for post-hoc analysis and pattern detection
+3. **Vary temperatures** between generation and refinement
+4. **Set hard limits** to prevent infinite loops
+5. **Parallelize critiques** when multiple critics available
+6. **Cache successful patterns** for similar future tasks
+
+## Common Pitfalls
+
+- **Over-refinement:** Excessive iterations with diminishing returns
+- **Critique drift:** Critic becomes increasingly harsh over iterations
+- **Oscillation:** Alternating between two imperfect solutions
+- **Budget explosion:** Underestimating computational cost
+
+---
+
+**Sources:**
+- [Self-Refine: Iterative Refinement with Self-Feedback](https://arxiv.org/abs/2303.17651)

package/skills/skills/framework-critical-thinking/references/reasoning_router.md

@@ -0,0 +1,235 @@
+# Reasoning Router
+
+## Purpose
+
+The Reasoning Router analyzes task characteristics and automatically selects the optimal reasoning method (CoT, ToT, GoT, or Self-Consistency) based on complexity, structure, and criticality of the task.
+
+## Decision Matrix
+
+### Selection Criteria
+
+| Factor | CoT | ToT-BFS | ToT-DFS | GoT | Self-Consistency |
+|--------|-----|---------|---------|-----|------------------|
+| **Complexity** | Low | High | High | Very High | Medium |
+| **Path Count** | Single | Multiple | Multiple | Interconnected | Single |
+| **Backtracking** | No | Yes | Yes | Yes | No |
+| **Exploration** | Linear | Breadth | Depth | Graph | Parallel |
+| **Cost** | Low | High | High | Very High | Medium |
+| **Latency** | Fast | Slow | Slow | Very Slow | Medium |
+
+### Selection Algorithm
+
+```
+function select_reasoning_method(problem):
+    complexity_score = analyze_complexity(problem)
+    path_diversity = estimate_path_count(problem)
+    criticality = assess_criticality(problem)
+    interconnectivity = check_interconnections(problem)
+
+    if criticality == HIGH and path_diversity == SINGLE:
+        return SELF_CONSISTENCY
+
+    if interconnectivity == HIGH:
+        return GRAPH_OF_THOUGHTS
+
+    if path_diversity == MULTIPLE:
+        if requires_deep_exploration(problem):
+            return TREE_OF_THOUGHTS_DFS
+        else:
+            return TREE_OF_THOUGHTS_BFS
+
+    return CHAIN_OF_THOUGHT
+```
+
+## Implementation
+
+### Complexity Analysis
+
+```python
+def analyze_complexity(problem):
+    factors = {
+        'step_count': estimate_reasoning_steps(problem),
+        'domain_knowledge': assess_domain_requirements(problem),
+        'ambiguity_level': detect_ambiguity(problem),
+        'constraint_density': count_constraints(problem)
+    }
+
+    # Weighted scoring
+    score = (
+        factors['step_count'] * 0.3 +
+        factors['domain_knowledge'] * 0.2 +
+        factors['ambiguity_level'] * 0.3 +
+        factors['constraint_density'] * 0.2
+    )
+
+    if score < 0.3:
+        return COMPLEXITY.LOW
+    elif score < 0.7:
+        return COMPLEXITY.MEDIUM
+    else:
+        return COMPLEXITY.HIGH
+```
+
+### Method Configurations
+
+#### Chain-of-Thought (CoT)
+
+**Use when:**
+- Straightforward arithmetic or logic
+- Single solution path
+- Well-defined problem space
+- Low ambiguity
+
+**Template:**
+```
+Let's solve this step by step:
+1. [First step with explanation]
+2. [Second step with explanation]
+...
+Therefore, [final answer]
+```
+
+#### Tree-of-Thoughts - BFS (ToT-BFS)
+
+**Use when:**
+- Multiple viable approaches exist
+- Need to compare alternatives at each step
+- Problem requires exploration of options
+
+**Configuration:**
+```python
+ToTConfig(
+    branching_factor=3,        # Number of candidates per step
+    beam_width=2,              # Keep top N candidates
+    max_depth=5,               # Maximum reasoning depth
+    search_algorithm='BFS',
+    evaluation_criteria='progress_toward_goal'
+)
+```
+
+#### Tree-of-Thoughts - DFS (ToT-DFS)
+
+**Use when:**
+- Deep reasoning chains needed
+- Early decisions strongly influence outcome
+- Problem has hierarchical structure
+
+**Configuration:**
+```python
+ToTConfig(
+    branching_factor=2,
+    max_depth=10,
+    search_algorithm='DFS',
+    backtrack_threshold=0.3,   # Backtrack if score below this
+    evaluation_criteria='path_viability'
+)
+```
+
+#### Graph-of-Thoughts (GoT)
+
+**Use when:**
+- Interconnected reasoning required
+- Thoughts can merge or aggregate
+- Non-linear problem structure
+
+**Configuration:**
+```python
+GoTConfig(
+    node_types=['premise', 'inference', 'conclusion'],
+    edge_types=['supports', 'contradicts', 'aggregates'],
+    aggregation_functions=['sum', 'max', 'graph_attention'],
+    max_nodes=50
+)
+```
+
+#### Self-Consistency
+
+**Use when:**
+- High-stakes decisions
+- Single answer required
+- Need confidence estimation
+
+**Configuration:**
+```python
+SelfConsistencyConfig(
+    sample_count=10,           # Number of reasoning paths
+    temperature=0.7,           # Variation in sampling
+    aggregation_method='majority_vote',
+    confidence_threshold=0.8
+)
+```
+
+## Usage Examples
+
+### Example 1: Simple Math Problem
+
+**Problem:** "What is 25 * 48?"
+
+**Analysis:**
+- Complexity: Low (single arithmetic operation)
+- Path diversity: Single
+- Criticality: Low
+
+**Selection:** Chain-of-Thought
+
+**Reasoning:**
+```
+25 * 48 = 25 * (50 - 2)
+        = 25 * 50 - 25 * 2
+        = 1250 - 50
+        = 1200
+```
+
+### Example 2: Game of 24
+
+**Problem:** "Make 24 using 4, 9, 10, 13"
+
+**Analysis:**
+- Complexity: High (multiple operations needed)
+- Path diversity: Multiple (different operation combinations)
+- Criticality: Medium
+
+**Selection:** Tree-of-Thoughts (BFS)
+
+**Exploration:**
+```
+Level 0: [4, 9, 10, 13]
+Level 1: [(4+9), 10, 13], [(13-9), 4, 10], [(10*4), 9, 13], ...
+Level 2: ... continue until 24 reached or max depth
+```
+
+### Example 3: Complex Planning
+
+**Problem:** "Plan a 5-day trip to Japan considering budget, weather, and preferences"
+
+**Analysis:**
+- Complexity: Very High
+- Interconnectivity: High (decisions affect each other)
+- Multiple constraints
+
+**Selection:** Graph-of-Thoughts
+
+**Graph Structure:**
+- Nodes: Destinations, activities, accommodations, transport
+- Edges: Temporal dependencies, budget constraints, preferences
+
+## Best Practices
+
+1. **Start Simple:** Default to CoT unless complexity indicators are present
+2. **Monitor Performance:** Track success rates per method for your domain
+3. **Adaptive Switching:** Allow runtime method switching if initial choice underperforms
+4. **Budget Awareness:** Consider computational cost vs accuracy trade-offs
+5. **Hybrid Approaches:** Combine methods (e.g., ToT with Self-Consistency for final answer)
+
+## Common Pitfalls
+
+- **Over-engineering:** Using ToT for simple problems wastes compute
+- **Under-exploring:** Using CoT for complex multi-path problems leads to dead ends
+- **Fixed Configuration:** Not adapting parameters to problem specifics
+- **Ignoring Latency:** ToT/GoT may be too slow for real-time applications
+
+---
+
+**Sources:**
+- [Tree of Thoughts: Deliberate Problem Solving with Large Language Models](https://arxiv.org/abs/2305.10601)
+- [Chain-of-Thought Prompting Elicits Reasoning in Large Language Models](https://arxiv.org/abs/2201.11903)

package/skills/skills/framework-critical-thinking/references/reasoning_validator.md

@@ -0,0 +1,97 @@
+# Reasoning Validator
+
+## Purpose
+
+The Reasoning Validator provides logical consistency checking and structural validation for reasoning chains to detect contradictions, gaps, and logical fallacies.
+
+## Validation Types
+
+### 1. Logical Consistency Checks
+
+Verify that the reasoning does not contain contradictions.
+
+```python
+class LogicalConsistencyChecker:
+    def check(self, reasoning_chain):
+        issues = []
+        contradictions = self.find_contradictions(reasoning_chain)
+        issues.extend(contradictions)
+        return {'valid': len(issues) == 0, 'issues': issues}
+
+    def find_contradictions(self, chain):
+        contradictions = []
+        statements = extract_statements(chain)
+        for i, stmt1 in enumerate(statements):
+            for stmt2 in statements[i+1:]:
+                if self.are_contradictory(stmt1, stmt2):
+                    contradictions.append({
+                        'type': 'contradiction',
+                        'statement1': stmt1,
+                        'statement2': stmt2
+                    })
+        return contradictions
+```
+
+### 2. Structural Completeness
+
+Verify that the reasoning has all necessary components.
+
+```python
+class StructuralValidator:
+    REQUIRED_COMPONENTS = [
+        'problem_statement',
+        'initial_assumptions',
+        'reasoning_steps',
+        'intermediate_conclusions',
+        'final_conclusion'
+    ]
+
+    def validate(self, reasoning_chain):
+        missing = []
+        for component in self.REQUIRED_COMPONENTS:
+            if not self.has_component(reasoning_chain, component):
+                missing.append(component)
+        return {'complete': len(missing) == 0, 'missing_components': missing}
+```
+
+### 3. Fallacy Detection
+
+Identify common logical fallacies.
+
+```python
+class FallacyDetector:
+    FALLACY_PATTERNS = {
+        'circular_reasoning': {
+            'check': lambda chain: chain['conclusion'] in chain['premises']
+        },
+        'false_dichotomy': {
+            'check': self.check_false_dichotomy
+        },
+        'hasty_generalization': {
+            'check': self.check_generalization
+        }
+    }
+
+    def detect(self, reasoning_chain):
+        detected = []
+        for fallacy_name, pattern in self.FALLACY_PATTERNS.items():
+            if pattern['check'](reasoning_chain):
+                detected.append({'type': fallacy_name})
+        return {'has_fallacies': len(detected) > 0, 'fallacies': detected}
+```
+
+## Usage Example
+
+```python
+validator = ReasoningValidator()
+result = validator.validate(reasoning_chain)
+
+if not result['valid']:
+    for rec in result['recommendations']:
+        print(f"Fix: {rec['action']}")
+```
+
+---
+
+**Sources:**
+- [Logical Reasoning in AI Systems](https://www.emergentmind.com/topics/logical-reasoning)