x-ipe 1.0.24__py3-none-any.whl → 1.0.25__py3-none-any.whl

x_ipe/app.py

@@ -131,16 +131,35 @@ def _init_services(app):
     if not app.config.get('TESTING'):
         project_root = app.config.get('PROJECT_ROOT', '.')
         from x_ipe.services.uiux_feedback_service import UiuxFeedbackService
+        
+        # Read retention days from tools.json (default 7)
+        retention_days = 7
+        tools_json_path = Path(project_root) / 'x-ipe-docs' / 'config' / 'tools.json'
+        if tools_json_path.exists():
+            try:
+                import json
+                with open(tools_json_path) as f:
+                    tools_config = json.load(f)
+                    retention_days = tools_config.get('feedback_retention_days', 7)
+            except (json.JSONDecodeError, IOError):
+                pass
+        
         feedback_service = UiuxFeedbackService(project_root)
-        deleted = feedback_service.cleanup_old_feedback(days=7)
+        deleted = feedback_service.cleanup_old_feedback(days=retention_days)
         if deleted > 0:
-            print(f"[X-IPE] Cleaned up {deleted} old feedback entries")
+            print(f"[X-IPE] Cleaned up {deleted} old feedback entries (retention: {retention_days} days)")
 
 
 def _register_blueprints(app):
     """Register all Flask Blueprints."""
-    from x_ipe.routes import main_bp, settings_bp, project_bp, ideas_bp, tools_bp, proxy_bp
+    from x_ipe.routes import main_bp, settings_bp, project_bp, ideas_bp, tools_bp, proxy_bp, kb_bp
     from x_ipe.routes.uiux_feedback_routes import uiux_feedback_bp
+    from x_ipe.routes.tracing_routes import tracing_bp
+    from x_ipe.routes.quality_evaluation_routes import quality_evaluation_bp
+    
+    # Initialize tracing middleware (FEATURE-023)
+    from x_ipe.tracing.middleware import init_tracing_middleware
+    init_tracing_middleware(app)
     
     app.register_blueprint(main_bp)
     app.register_blueprint(settings_bp)
@@ -149,6 +168,9 @@ def _register_blueprints(app):
     app.register_blueprint(tools_bp)
     app.register_blueprint(proxy_bp)
     app.register_blueprint(uiux_feedback_bp)
+    app.register_blueprint(tracing_bp)
+    app.register_blueprint(quality_evaluation_bp)
+    app.register_blueprint(kb_bp)
 
 
 def _register_handlers():

x_ipe/handlers/terminal_handlers.py

@@ -11,6 +11,7 @@ Provides WebSocket handlers for:
 from flask import request
 
 from x_ipe.services import session_manager
+from x_ipe.tracing import x_ipe_tracing
 
 # Socket SID to Session ID mapping
 socket_to_session = {}
@@ -20,12 +21,14 @@ def register_terminal_handlers(socketio):
     """Register WebSocket event handlers for terminal."""
     
     @socketio.on('connect')
+    @x_ipe_tracing()
     def handle_connect():
         """Handle new WebSocket connection."""
         sid = request.sid
         print(f"[Terminal] Client connected: {sid}")
     
     @socketio.on('attach')
+    @x_ipe_tracing()
     def handle_attach(data):
         """
         Handle session attachment.
@@ -75,6 +78,7 @@ def register_terminal_handlers(socketio):
             socketio.emit('error', {'message': 'Failed to attach terminal session'}, room=sid)
     
     @socketio.on('disconnect')
+    @x_ipe_tracing()
     def handle_disconnect():
         """Handle WebSocket disconnection - keep session alive."""
         try:
@@ -91,6 +95,7 @@ def register_terminal_handlers(socketio):
             print(f"[Terminal] Error in disconnect handler: {e}")
     
     @socketio.on('input')
+    @x_ipe_tracing()
     def handle_input(data):
         """Forward input to PTY."""
         try:
@@ -105,6 +110,7 @@ def register_terminal_handlers(socketio):
             print(f"[Terminal] Error in input handler: {e}")
     
     @socketio.on('resize')
+    @x_ipe_tracing()
     def handle_resize(data):
         """Handle terminal resize."""
         try:

x_ipe/handlers/voice_handlers.py

@@ -14,6 +14,7 @@ from flask import request
 from flask_socketio import emit
 
 from x_ipe.services.voice_input_service_v2 import VoiceInputService, is_voice_command
+from x_ipe.tracing import x_ipe_tracing
 
 # Global voice service instance
 voice_service = None
@@ -35,6 +36,7 @@ def register_voice_handlers(socketio):
         print("[Voice] No ALIBABA_SPEECH_API_KEY found, voice input disabled")
     
     @socketio.on('voice_start')
+    @x_ipe_tracing()
     def handle_voice_start(data=None):
         """Handle voice recording start request."""
         global voice_service
@@ -77,6 +79,7 @@ def register_voice_handlers(socketio):
             emit('voice_error', {'message': str(e)})
     
     @socketio.on('voice_audio')
+    @x_ipe_tracing()
     def handle_voice_audio(data):
         """Handle incoming audio chunk from client."""
         global voice_service
@@ -103,6 +106,7 @@ def register_voice_handlers(socketio):
             emit('voice_error', {'message': f'Audio error: {e}'})
     
     @socketio.on('voice_stop')
+    @x_ipe_tracing()
     def handle_voice_stop(data=None):
         """Handle voice recording stop request - finalize and get transcription."""
         global voice_service
@@ -151,6 +155,7 @@ def register_voice_handlers(socketio):
             emit('voice_error', {'message': str(e)})
     
     @socketio.on('voice_cancel')
+    @x_ipe_tracing()
     def handle_voice_cancel(data=None):
         """Handle voice recording cancel request - abort without transcription."""
         global voice_service

x_ipe/resources/copilot-instructions.md

@@ -65,7 +65,7 @@
 
 | Task Type | Skill | Category | Next Task | Human Review (default) |
 |-----------|-------|----------|-----------|------------------------|
-| Ideation | `task-type-ideation` | ideation-stage | Idea Mockup OR Idea to Architecture | No |
+| Ideation | `x-ipe-task-based-ideation` | ideation-stage | Idea Mockup OR Idea to Architecture | No |
 | Idea Mockup | `task-type-idea-mockup` | ideation-stage | Requirement Gathering | No |
 | Idea to Architecture | `task-type-idea-to-architecture` | ideation-stage | Requirement Gathering | No |
 | Share Idea | `task-type-share-idea` | Standalone | - | Yes |
@@ -151,15 +151,28 @@ Always follow:
 ### Creating, Updating, or Validating X-IPE Skills
 
 **When:** Creating a new skill, updating an existing skill, or validating skill structure
-**Then:** Always use the `x-ipe-skill-creator` skill
+**Then:** Always use the `x-ipe-skill-creator-v3` skill
 
 ```
-1. Load skill: `x-ipe-skill-creator`
+1. Load skill: `x-ipe-skill-creator-v3`
 2. Follow the skill creation process defined in the skill
 3. Use appropriate template based on skill type:
-   - Task Type → templates/task-type-skill.md
-   - Skill Category → templates/skill-category-skill.md
-   - Tool Skill → TBD
+   - Task Type → templates/x-ipe-task-based.md
+   - Tool Skill → templates/x-ipe-tool.md
+   - Workflow Orchestration → templates/x-ipe-workflow-orchestration.md
+   - Meta Skill → templates/x-ipe-meta.md
 4. Validate against skill-creator checklist before completing
 ```
 
+### Capturing Lessons for Skill Improvement
+
+**When:** A skill execution has problems, human provides feedback, or agent observes suboptimal behavior
+**Then:** Use the `lesson-learned` skill
+
+```
+1. Load skill: `lesson-learned`
+2. Follow the lesson capture process
+3. Lessons are stored in x-ipe-docs/skill-meta/{skill}/lesson-learned.md
+4. Next time skill is updated, lessons will be incorporated
+```
+

x_ipe/resources/skills/lesson-learned/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: lesson-learned
+description: Capture issues and feedback for skill improvement. Use when a skill execution had problems, human provides feedback, or agent observes suboptimal behavior. Triggers on requests like "capture lesson", "record issue", "this skill failed", "improve this skill". Records lessons in x-ipe-docs/skill-meta/{skill}/lesson-learned.md for future skill updates.
+---
+
+# Lesson Learned
+
+Capture issues and feedback to improve skills over time.
+
+## Purpose
+
+This skill captures issues, errors, and feedback for specific skills by:
+1. Identifying which skill had the issue
+2. Analyzing what went wrong
+3. Documenting the correct behavior (ground truth)
+4. Recording a structured lesson for future skill updates
+
+---
+
+## Important Notes
+
+- **Manual trigger only** (for now) - human must say "capture lesson" or similar
+- Lessons are stored per-skill in `x-ipe-docs/skill-meta/{skill-name}/lesson-learned.md`
+- Lessons are consumed by `x-ipe-skill-creator` when updating skills
+- Ground truth is critical - always capture what the correct output should be
+
+---
+
+## Execution Flow
+
+| Step | Action | Output |
+|------|--------|--------|
+| 1 | Identify skill | Skill name that had the issue |
+| 2 | Gather context | Task ID, scenario, inputs |
+| 3 | Document issue | Observed vs expected behavior |
+| 4 | Capture ground truth | Correct output (after manual fix) |
+| 5 | Propose improvement | Suggested AC or instruction change |
+| 6 | Save lesson | lesson-learned.md updated |
+
+---
+
+## Execution Procedure
+
+### Step 1: Identify Skill
+
+Determine which skill had the issue:
+
+```
+1. Ask: "Which skill had the issue?"
+   - If context clear: extract skill name
+   - If unclear: ask user to specify
+   
+2. Verify skill exists:
+   - Check .github/skills/{skill-name}/
+   - If not exists: abort with error
+   
+3. Check/create skill-meta folder:
+   - If x-ipe-docs/skill-meta/{skill-name}/ not exists: create it
+```
+
+### Step 2: Gather Context
+
+Collect information about when the issue occurred:
+
+```yaml
+context:
+  task_id: "{TASK-ID if available}"
+  scenario: "{What was being done}"
+  inputs: "{What inputs were provided to the skill}"
+  skill_version: "{Current skill version if known}"
+```
+
+### Step 3: Document Issue
+
+Record what went wrong:
+
+```yaml
+observed_behavior: |
+  {What the skill actually did}
+  - Include actual output if available
+  - Include error messages if any
+  
+expected_behavior: |
+  {What the skill should have done}
+  - Be specific about correct behavior
+```
+
+### Step 4: Capture Ground Truth
+
+**Critical step** - This becomes the test case for validation:
+
+```
+1. Ask: "What should the correct output look like?"
+
+2. If human provides correction:
+   - Record exactly as provided
+   
+3. If human fixed output manually:
+   - Reference the fixed file path
+   - Record the key differences
+   
+4. If unclear:
+   - Ask clarifying questions
+   - Do NOT proceed without ground truth
+```
+
+### Step 5: Propose Improvement
+
+Suggest how to improve the skill:
+
+| Improvement Type | When to Use | Target |
+|------------------|-------------|--------|
+| `new_ac` | Issue reveals missing requirement | Add to skill-meta acceptance_criteria |
+| `update_ac` | Existing AC is incomplete | Modify specific AC |
+| `update_instruction` | Skill procedure unclear | SKILL.md section |
+| `add_example` | Edge case not covered | references/examples.md |
+
+### Step 6: Save Lesson
+
+Append to or create lesson-learned.md:
+
+```
+1. Read template: x-ipe-docs/skill-meta/templates/lesson-learned.md
+2. Generate unique lesson ID: LL-{NNN}
+3. Create lesson entry with:
+   - status: raw
+   - All gathered information
+4. Append to x-ipe-docs/skill-meta/{skill-name}/lesson-learned.md
+5. If file didn't exist: create with YAML frontmatter
+```
+
+---
+
+## Definition of Done
+
+| Checkpoint | Required |
+|------------|----------|
+| Skill identified and verified | Yes |
+| Context documented | Yes |
+| Issue described (observed vs expected) | Yes |
+| Ground truth captured | Yes |
+| Improvement proposed | Yes |
+| Lesson saved to lesson-learned.md | Yes |
+
+---
+
+## Patterns
+
+### Pattern: Error During Execution
+
+**When:** Skill threw an error or failed
+**Then:**
+```
+1. Capture error message/stack trace
+2. Document what operation caused the error
+3. Record expected behavior: "Should complete without error"
+4. Propose: update_instruction to handle edge case
+```
+
+### Pattern: Wrong Output Format
+
+**When:** Skill produced output but format was wrong
+**Then:**
+```
+1. Save actual output (or screenshot/snippet)
+2. Show expected format
+3. Record ground truth with correct format
+4. Propose: new_ac for format validation
+```
+
+### Pattern: Missing Content
+
+**When:** Skill output was incomplete
+**Then:**
+```
+1. List what was missing
+2. Provide complete expected content
+3. Record ground truth with all content
+4. Propose: update_ac to require missing content
+```
+
+### Pattern: Human Feedback
+
+**When:** Human says "this is wrong" or provides feedback
+**Then:**
+```
+1. Ask: "What specifically is wrong?"
+2. Ask: "What should it be instead?"
+3. Record feedback as ground truth
+4. Propose improvement based on feedback
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why Bad | Do Instead |
+|--------------|---------|------------|
+| Recording without ground truth | Can't generate valid tests | Always capture correct output |
+| Vague issue description | Hard to fix skill | Be specific about observed vs expected |
+| Not linking to task ID | Lose context | Always include TASK-ID if available |
+| Skipping severity | Can't prioritize | Always assign critical/major/minor/enhancement |
+
+---
+
+## Example
+
+See [references/examples.md](references/examples.md) for execution examples.

x_ipe/resources/skills/lesson-learned/references/examples.md

@@ -0,0 +1,238 @@
+# Lesson Learned Examples
+
+## Example 1: Skill Error During Execution
+
+**Trigger:** "The technical design skill failed with an error"
+
+```
+Step 1: Identify Skill
+→ skill_name: task-type-technical-design
+→ Verified: .github/skills/task-type-technical-design/ exists
+→ Created: x-ipe-docs/skill-meta/task-type-technical-design/
+
+Step 2: Gather Context
+→ context:
+    task_id: TASK-150
+    scenario: Creating technical design for FEATURE-025
+    inputs: feature_id=FEATURE-025
+
+Step 3: Document Issue
+→ observed_behavior: |
+    Skill threw error at step 3:
+    "KeyError: 'acceptance_criteria' not found in specification.md"
+    
+→ expected_behavior: |
+    Skill should handle missing acceptance_criteria gracefully
+    or use feature requirements as fallback.
+
+Step 4: Capture Ground Truth
+→ ground_truth: |
+    When specification.md lacks acceptance_criteria section:
+    1. Log warning: "No acceptance_criteria found"
+    2. Fall back to requirements from feature-board
+    3. Continue with design using requirements as criteria
+
+Step 5: Propose Improvement
+→ proposed_improvement:
+    type: update_instruction
+    target: "Execution Procedure Step 3"
+    description: "Add fallback handling for missing acceptance_criteria"
+    
+→ proposed_ac:
+    should:
+      - id: AC-NEW
+        description: "Handles missing specification sections gracefully"
+        test_method: error_handling
+        expected: "Falls back to feature requirements without error"
+
+Step 6: Save Lesson
+→ Created: x-ipe-docs/skill-meta/task-type-technical-design/lesson-learned.md
+→ Added lesson: LL-001
+→ status: raw
+```
+
+---
+
+## Example 2: Wrong Output Format
+
+**Trigger:** "The requirement gathering output doesn't follow the template"
+
+```
+Step 1: Identify Skill
+→ skill_name: task-type-requirement-gathering
+→ Verified exists
+
+Step 2: Gather Context
+→ context:
+    task_id: TASK-155
+    scenario: Gathering requirements for new feature request
+    inputs: User request about "add dark mode support"
+
+Step 3: Document Issue
+→ observed_behavior: |
+    Output file requirement-details.md:
+    - Missing "Constraints" section
+    - "Success Criteria" section has wrong format (bullets instead of checkboxes)
+    - No version header
+    
+→ expected_behavior: |
+    Output should match template exactly:
+    - All sections present
+    - Checkboxes for success criteria (- [ ] format)
+    - Version header at top
+
+Step 4: Capture Ground Truth
+→ ground_truth: |
+    Correct requirement-details.md structure:
+    
+    # Requirement: {title}
+    > Version: 1.0.0
+    > Status: Draft
+    
+    ## Overview
+    {description}
+    
+    ## Success Criteria
+    - [ ] Criterion 1
+    - [ ] Criterion 2
+    
+    ## Constraints
+    - Constraint 1
+    - Constraint 2
+
+Step 5: Propose Improvement
+→ proposed_improvement:
+    type: new_ac
+    target: acceptance_criteria.must
+    description: "Require template structure validation"
+    
+→ proposed_ac:
+    must:
+      - id: AC-NEW
+        description: "Output follows requirement-details.md template structure"
+        test_method: structure_validation
+        expected: "All sections present, correct formatting"
+
+Step 6: Save Lesson
+→ Updated: lesson-learned.md
+→ Added lesson: LL-002
+→ severity: major
+→ status: raw
+```
+
+---
+
+## Example 3: Human Feedback
+
+**Trigger:** "This technical design is missing error handling - please capture that as a lesson"
+
+```
+Step 1: Identify Skill
+→ Inferred from context: task-type-technical-design
+→ Confirmed with user
+
+Step 2: Gather Context
+→ context:
+    task_id: TASK-160
+    scenario: Technical design for API integration feature
+    inputs: FEATURE-030
+
+Step 3: Document Issue
+→ observed_behavior: |
+    Technical design document has no Error Handling section.
+    
+→ expected_behavior: |
+    Technical design should include Error Handling section
+    documenting expected exceptions and recovery strategies.
+
+Step 4: Capture Ground Truth
+→ Asked: "What should the Error Handling section contain?"
+→ Human response: "List of expected exceptions, recovery strategies, fallback behaviors"
+
+→ ground_truth: |
+    Technical design must include ## Error Handling section with:
+    - Table of expected exceptions
+    - Recovery strategy for each
+    - Fallback behaviors
+    - Logging requirements
+    
+    Example:
+    | Exception | Recovery | Fallback |
+    |-----------|----------|----------|
+    | ConnectionError | Retry 3x | Use cached data |
+    | TimeoutError | Retry with backoff | Return partial result |
+
+Step 5: Propose Improvement
+→ proposed_improvement:
+    type: new_ac
+    target: acceptance_criteria.should
+    description: "Require Error Handling section in technical design"
+    
+→ proposed_ac:
+    should:
+      - id: AC-NEW
+        description: "Includes Error Handling section with exception table"
+        test_method: section_exists
+        expected: "Error Handling section with exception/recovery/fallback table"
+
+Step 6: Save Lesson
+→ Updated: lesson-learned.md
+→ Added lesson: LL-003
+→ severity: major
+→ source: human_feedback
+→ status: raw
+```
+
+---
+
+## Example 4: Edge Case Not Covered
+
+**Trigger:** "The feature breakdown skill didn't handle a feature with no acceptance criteria"
+
+```
+Step 1: Identify Skill
+→ skill_name: task-type-feature-breakdown
+
+Step 2: Gather Context
+→ context:
+    task_id: TASK-165
+    scenario: Breaking down requirement into features
+    inputs: requirement-details.md with 3 user stories but no AC
+
+Step 3: Document Issue
+→ observed_behavior: |
+    Skill assumed acceptance criteria existed.
+    Created features with empty AC section.
+    
+→ expected_behavior: |
+    Skill should derive AC from user stories when none provided.
+    Or flag to user that AC are missing and need to be defined.
+
+Step 4: Capture Ground Truth
+→ ground_truth: |
+    When requirement has no explicit acceptance criteria:
+    1. Check for user stories
+    2. If user stories exist: derive AC from "Given/When/Then" if present
+    3. If no derivable AC: ask user "No acceptance criteria found. 
+       Please provide AC for: {feature_name}"
+    4. Do not proceed with empty AC
+
+Step 5: Propose Improvement
+→ proposed_improvement:
+    type: add_example
+    target: references/examples.md
+    description: "Add example for handling missing acceptance criteria"
+
+→ proposed_ac:
+    must:
+      - id: AC-NEW
+        description: "Handles missing acceptance criteria appropriately"
+        test_method: edge_case_handling
+        expected: "Derives from user stories OR prompts user"
+
+Step 6: Save Lesson
+→ Created: lesson-learned.md for task-type-feature-breakdown
+→ Added lesson: LL-001
+→ severity: major
+→ status: raw
+```