devforgeai 1.0.4 → 1.0.6

package/src/claude/scripts/devforgeai_cli/feedback/longitudinal.py

@@ -0,0 +1,115 @@
+"""
+Longitudinal feedback tracking (AC6)
+"""
+
+import json
+from pathlib import Path
+from typing import Dict, List, Any
+from datetime import datetime
+
+
+def correlate_feedback_across_stories(feedback_dir: Path, user_id: str) -> Dict[str, Any]:
+    """
+    Correlate feedback across stories for a user.
+
+    Returns:
+        Dict with 'timeline' list showing progression
+    """
+    all_feedback = []
+
+    for story_dir in feedback_dir.iterdir():
+        if not story_dir.is_dir():
+            continue
+
+        for feedback_file in story_dir.glob('*-retrospective.json'):
+            with open(feedback_file, 'r') as f:
+                feedback_data = json.load(f)
+                all_feedback.append(feedback_data)
+
+    # Sort by timestamp
+    all_feedback.sort(key=lambda x: x['timestamp'])
+
+    timeline = []
+    for fb in all_feedback:
+        timeline.append({
+            'timestamp': fb['timestamp'],
+            'story_id': fb['story_id'],
+            'workflow_type': fb['workflow_type'],
+            'success_status': fb['success_status'],
+        })
+
+    return {'timeline': timeline}
+
+
+def identify_improvement_trajectories(feedback_dir: Path, user_id: str) -> Dict[str, Any]:
+    """
+    Identify improvement trajectories over time.
+
+    Returns:
+        Dict with 'metrics' list showing trends
+    """
+    correlation = correlate_feedback_across_stories(feedback_dir, user_id)
+
+    # Extract confidence ratings over time (dev_success_01)
+    confidence_values = []
+
+    for story_dir in feedback_dir.iterdir():
+        if not story_dir.is_dir():
+            continue
+
+        for feedback_file in sorted(story_dir.glob('*-retrospective.json')):
+            with open(feedback_file, 'r') as f:
+                feedback_data = json.load(f)
+
+                for question in feedback_data.get('questions', []):
+                    if question.get('question_id', '').endswith('_01') and isinstance(question.get('response'), int):
+                        confidence_values.append(question['response'])
+
+    if len(confidence_values) < 2:
+        return {'metrics': []}
+
+    # Determine trend
+    trend = 'improving' if confidence_values[-1] >= confidence_values[0] else 'declining'
+
+    metrics = [{
+        'name': 'TDD confidence',
+        'trend': trend,
+        'start_value': confidence_values[0],
+        'end_value': confidence_values[-1],
+        'data_points': len(confidence_values)
+    }]
+
+    return {'metrics': metrics}
+
+
+def export_personal_journal(feedback_dir: Path, user_id: str) -> Path:
+    """
+    Export personal retrospective journal.
+
+    Returns:
+        Path to journal.md
+    """
+    correlation = correlate_feedback_across_stories(feedback_dir, user_id)
+    trajectories = identify_improvement_trajectories(feedback_dir, user_id)
+
+    user_dir = feedback_dir / user_id
+    user_dir.mkdir(parents=True, exist_ok=True)
+
+    journal_path = user_dir / 'journal.md'
+
+    content = "# Retrospective Journal\n\n"
+    content += f"**User:** {user_id}\n\n"
+    content += "## Timeline\n\n"
+
+    for entry in correlation['timeline']:
+        content += f"- **{entry['story_id']}** ({entry['timestamp'][:10]}) - {entry['workflow_type']} - {entry['success_status']}\n"
+
+    content += "\n## Improvement Trajectory\n\n"
+
+    for metric in trajectories.get('metrics', []):
+        content += f"- **{metric['name']}**: {metric['trend']} (from {metric['start_value']} to {metric['end_value']})\n"
+
+    with open(journal_path, 'w') as f:
+        f.write(content)
+
+    return journal_path

package/src/claude/scripts/devforgeai_cli/feedback/models.py

@@ -0,0 +1,67 @@
+"""
+Data models for feedback system
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Any
+from datetime import datetime
+
+
+@dataclass
+class Question:
+    """Represents a single feedback question"""
+    question_id: str
+    question_text: str
+    response_type: str  # 'rating', 'multiple_choice', 'open_text'
+    scale: Optional[str] = None  # For rating questions (e.g., "1-5")
+    options: Optional[List[str]] = None  # For multiple choice
+    response: Optional[Any] = None
+    skip: bool = False
+
+    def __post_init__(self):
+        """Validate question configuration"""
+        if self.response_type == 'rating' and self.scale is None:
+            raise ValueError(f"Rating question {self.question_id} must have scale")
+
+        if self.response_type == 'multiple_choice' and (self.options is None or len(self.options) < 2):
+            raise ValueError(f"Multiple choice question {self.question_id} must have at least 2 options")
+
+
+@dataclass
+class FeedbackSession:
+    """Represents a complete feedback session"""
+    feedback_id: str
+    timestamp: str  # ISO 8601
+    story_id: str
+    epic_id: Optional[str] = None
+    workflow_type: str = ''  # 'dev', 'qa', 'orchestrate', 'release', etc.
+    success_status: str = ''  # 'success', 'failed', 'partial'
+    questions: List[dict] = field(default_factory=list)
+    metadata: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization"""
+        return {
+            'feedback_id': self.feedback_id,
+            'timestamp': self.timestamp,
+            'story_id': self.story_id,
+            'epic_id': self.epic_id,
+            'workflow_type': self.workflow_type,
+            'success_status': self.success_status,
+            'questions': self.questions,
+            'metadata': self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'FeedbackSession':
+        """Create FeedbackSession from dictionary"""
+        return cls(
+            feedback_id=data['feedback_id'],
+            timestamp=data['timestamp'],
+            story_id=data['story_id'],
+            epic_id=data.get('epic_id'),
+            workflow_type=data.get('workflow_type', ''),
+            success_status=data.get('success_status', ''),
+            questions=data.get('questions', []),
+            metadata=data.get('metadata', {}),
+        )

package/src/claude/scripts/devforgeai_cli/feedback/question_router.py

@@ -0,0 +1,236 @@
+"""
+Context-aware question routing
+
+Routes questions based on workflow type and success/failure status.
+"""
+
+import yaml
+from pathlib import Path
+from typing import List, Dict, Any
+
+from .models import Question
+
+
+def load_question_bank(bank_path: Path = None) -> Dict[str, Any]:
+    """
+    Load question bank from YAML file.
+
+    Args:
+        bank_path: Path to questions.yaml file
+
+    Returns:
+        Dict with workflow questions
+    """
+    if bank_path is None:
+        # Default path
+        bank_path = Path(__file__).parent.parent.parent.parent.parent / 'devforgeai' / 'feedback' / 'questions.yaml'
+
+    if not bank_path.exists():
+        # Return minimal default question bank
+        return _get_default_question_bank()
+
+    with open(bank_path, 'r') as f:
+        question_bank = yaml.safe_load(f)
+
+    return question_bank
+
+
+def get_context_aware_questions(workflow_type: str, success_status: str) -> List[Question]:
+    """
+    Get context-aware questions based on workflow and status.
+
+    Args:
+        workflow_type: 'dev', 'qa', 'orchestrate', 'release', etc.
+        success_status: 'success', 'failed', 'partial'
+
+    Returns:
+        List of 4-6 Question objects
+    """
+    question_bank = load_question_bank()
+
+    workflows = question_bank.get('workflows', {})
+    workflow_config = workflows.get(workflow_type, {})
+
+    # Determine question set based on success status
+    if success_status == 'failed':
+        question_list = workflow_config.get('failure_questions', [])
+    else:
+        question_list = workflow_config.get('success_questions', [])
+
+    # Convert to Question objects
+    questions = []
+    for q_data in question_list[:6]:  # Limit to 6 questions
+        question = Question(
+            question_id=q_data['id'],
+            question_text=q_data['text'],
+            response_type=q_data['type'],
+            scale=q_data.get('scale'),
+            options=q_data.get('options'),
+        )
+        questions.append(question)
+
+    return questions
+
+
+def _get_default_question_bank() -> Dict[str, Any]:
+    """
+    Return default question bank (used when questions.yaml doesn't exist).
+
+    Returns:
+        Dict with minimal question bank
+    """
+    return {
+        'workflows': {
+            'dev': {
+                'success_questions': [
+                    {
+                        'id': 'dev_success_01',
+                        'text': 'How confident do you feel about the TDD workflow?',
+                        'type': 'rating',
+                        'scale': '1-5'
+                    },
+                    {
+                        'id': 'dev_success_02',
+                        'text': 'Which phase was most challenging?',
+                        'type': 'multiple_choice',
+                        'options': ['Red', 'Green', 'Refactor', 'Integration']
+                    },
+                    {
+                        'id': 'dev_success_03',
+                        'text': 'What could we improve about the development workflow?',
+                        'type': 'open_text'
+                    },
+                    {
+                        'id': 'dev_success_04',
+                        'text': 'How well did the framework guide you?',
+                        'type': 'rating',
+                        'scale': '1-5'
+                    },
+                ],
+                'failure_questions': [
+                    {
+                        'id': 'dev_failure_01',
+                        'text': 'What blocked you from completing the story?',
+                        'type': 'open_text'
+                    },
+                    {
+                        'id': 'dev_failure_02',
+                        'text': 'What would help you complete this in the future?',
+                        'type': 'open_text'
+                    },
+                    {
+                        'id': 'dev_failure_03',
+                        'text': 'How clear were the error messages?',
+                        'type': 'rating',
+                        'scale': '1-5'
+                    },
+                ]
+            },
+            'qa': {
+                'success_questions': [
+                    {
+                        'id': 'qa_success_01',
+                        'text': 'How clear were the quality metrics?',
+                        'type': 'rating',
+                        'scale': '1-5'
+                    },
+                    {
+                        'id': 'qa_success_02',
+                        'text': 'What could improve the validation process?',
+                        'type': 'open_text'
+                    },
+                    {
+                        'id': 'qa_success_03',
+                        'text': 'Were coverage thresholds reasonable?',
+                        'type': 'multiple_choice',
+                        'options': ['Too strict', 'Just right', 'Too lenient']
+                    },
+                ],
+                'failure_questions': [
+                    {
+                        'id': 'qa_failure_01',
+                        'text': 'What made the quality check fail?',
+                        'type': 'open_text'
+                    },
+                    {
+                        'id': 'qa_failure_02',
+                        'text': 'How can we make quality requirements clearer?',
+                        'type': 'open_text'
+                    },
+                    {
+                        'id': 'qa_failure_03',
+                        'text': 'How helpful were the failure messages?',
+                        'type': 'rating',
+                        'scale': '1-5'
+                    },
+                ]
+            },
+            'orchestrate': {
+                'success_questions': [
+                    {
+                        'id': 'orchestrate_success_01',
+                        'text': 'How smooth was the full workflow integration?',
+                        'type': 'rating',
+                        'scale': '1-5'
+                    },
+                    {
+                        'id': 'orchestrate_success_02',
+                        'text': 'Which phase had the most friction?',
+                        'type': 'multiple_choice',
+                        'options': ['Dev', 'QA', 'Release', 'None']
+                    },
+                    {
+                        'id': 'orchestrate_success_03',
+                        'text': 'What could improve the orchestration workflow?',
+                        'type': 'open_text'
+                    },
+                ],
+                'failure_questions': [
+                    {
+                        'id': 'orchestrate_failure_01',
+                        'text': 'At which phase did the workflow fail?',
+                        'type': 'multiple_choice',
+                        'options': ['Dev', 'QA', 'Release']
+                    },
+                    {
+                        'id': 'orchestrate_failure_02',
+                        'text': 'What would have helped prevent this failure?',
+                        'type': 'open_text'
+                    },
+                    {
+                        'id': 'orchestrate_failure_03',
+                        'text': 'How well did the framework communicate the issue?',
+                        'type': 'rating',
+                        'scale': '1-5'
+                    },
+                ]
+            },
+            'release': {
+                'success_questions': [
+                    {
+                        'id': 'release_success_01',
+                        'text': 'How confident are you in the deployment?',
+                        'type': 'rating',
+                        'scale': '1-5'
+                    },
+                    {
+                        'id': 'release_success_02',
+                        'text': 'What could improve the release process?',
+                        'type': 'open_text'
+                    },
+                ],
+                'failure_questions': [
+                    {
+                        'id': 'release_failure_01',
+                        'text': 'What caused the release to fail?',
+                        'type': 'open_text'
+                    },
+                    {
+                        'id': 'release_failure_02',
+                        'text': 'How can we make releases more reliable?',
+                        'type': 'open_text'
+                    },
+                ]
+            }
+        }
+    }

package/src/claude/scripts/devforgeai_cli/feedback/retrospective.py

@@ -0,0 +1,233 @@
+"""
+Retrospective conversation core module
+
+Handles triggering retrospectives, capturing feedback, and managing feedback sessions.
+"""
+
+import json
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+from .models import Question, FeedbackSession
+from .question_router import get_context_aware_questions
+
+
+def trigger_retrospective(workflow_type: str, operation_result: Dict[str, Any]) -> List[Question]:
+    """
+    Trigger retrospective conversation after operation completion.
+
+    Args:
+        workflow_type: Type of workflow ('dev', 'qa', 'orchestrate', etc.)
+        operation_result: Dict with keys 'status', 'story_id', optional 'failure_reason'
+
+    Returns:
+        List of Question objects (4-6 questions)
+    """
+    success_status = operation_result.get('status', 'success')
+
+    # Get context-aware questions based on workflow and status
+    questions = get_context_aware_questions(workflow_type, success_status)
+
+    return questions
+
+
+def capture_feedback(
+    responses: List[Dict[str, Any]],
+    story_id: str,
+    workflow_type: str,
+    success_status: str,
+    feedback_dir: Optional[Path] = None,
+    epic_id: Optional[str] = None,
+    allow_skip: bool = True,
+) -> Dict[str, Any]:
+    """
+    Capture and store feedback responses.
+
+    Args:
+        responses: List of dicts with 'question_id', 'response', 'skip'
+        story_id: Story ID (e.g., 'STORY-001')
+        workflow_type: Workflow type
+        success_status: 'success', 'failed', or 'partial'
+        feedback_dir: Directory to store feedback (default: devforgeai/feedback)
+        epic_id: Optional epic ID
+        allow_skip: Whether to allow full skip (all questions skipped)
+
+    Returns:
+        Dict with 'status' ('recorded' or 'skipped'), 'feedback_id', 'file_path', 'message'
+    """
+    # Check if all skipped
+    all_skipped = all(r.get('skip', False) for r in responses)
+
+    if all_skipped and allow_skip:
+        return {
+            'status': 'skipped',
+            'message': 'No problem, thanks for using DevForgeAI!'
+        }
+
+    # Validate minimum responses (at least 2 of 5 substantive responses)
+    substantive_responses = [
+        r for r in responses
+        if not r.get('skip', False) and r.get('response') and len(str(r['response'])) > 10
+    ]
+
+    if len(substantive_responses) < 2 and len(responses) >= 5:
+        raise ValueError("At least 2 of 5 questions must have substantive responses (>10 chars)")
+
+    # Generate feedback ID and timestamp
+    feedback_id = f"fb-{uuid.uuid4()}"
+    timestamp = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')
+
+    # Calculate metadata
+    total_questions = len(responses)
+    answered = sum(1 for r in responses if not r.get('skip', False))
+    skipped = total_questions - answered
+
+    metadata = {
+        'duration_seconds': 0,  # Would be calculated in real implementation
+        'total_questions': total_questions,
+        'answered': answered,
+        'skipped': skipped,
+    }
+
+    # Create feedback session
+    feedback_session = FeedbackSession(
+        feedback_id=feedback_id,
+        timestamp=timestamp,
+        story_id=story_id,
+        epic_id=epic_id,
+        workflow_type=workflow_type,
+        success_status=success_status,
+        questions=responses,
+        metadata=metadata,
+    )
+
+    # Determine feedback directory
+    if feedback_dir is None:
+        feedback_dir = Path.cwd() / 'devforgeai' / 'feedback'
+
+    # Create story-specific directory
+    story_feedback_dir = feedback_dir / story_id
+    story_feedback_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate filename with timestamp
+    filename = f"{timestamp[:10]}-retrospective.json"
+    file_path = story_feedback_dir / filename
+
+    # Write feedback to JSON file
+    with open(file_path, 'w') as f:
+        json.dump(feedback_session.to_dict(), f, indent=2)
+
+    return {
+        'status': 'recorded',
+        'feedback_id': feedback_id,
+        'file_path': str(file_path),
+        'message': '✅ Feedback recorded'
+    }
+
+
+def is_skip_selected(user_response: str) -> bool:
+    """
+    Check if user selected to skip feedback.
+
+    Args:
+        user_response: User's response text
+
+    Returns:
+        True if user wants to skip, False otherwise
+    """
+    skip_phrases = [
+        'skip',
+        'no thanks',
+        'not now',
+        'later',
+        'decline',
+    ]
+
+    response_lower = user_response.lower().strip()
+
+    return any(phrase in response_lower for phrase in skip_phrases)
+
+
+def save_in_progress_state(
+    story_id: str,
+    responses: List[Dict[str, Any]],
+    workflow_type: str,
+    feedback_dir: Path,
+) -> Path:
+    """
+    Save in-progress feedback state (for network loss recovery).
+
+    Args:
+        story_id: Story ID
+        responses: Partial responses completed so far
+        workflow_type: Workflow type
+        feedback_dir: Feedback directory
+
+    Returns:
+        Path to saved state file
+    """
+    story_feedback_dir = feedback_dir / story_id
+    story_feedback_dir.mkdir(parents=True, exist_ok=True)
+
+    state_data = {
+        'story_id': story_id,
+        'workflow_type': workflow_type,
+        'responses': responses,
+        'status': 'in_progress',
+        'timestamp': datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z'),
+    }
+
+    state_file = story_feedback_dir / f"{state_data['timestamp'][:19]}-in-progress.json"
+
+    with open(state_file, 'w') as f:
+        json.dump(state_data, f, indent=2)
+
+    return state_file
+
+
+def resume_feedback(story_id: str, feedback_dir: Path) -> Optional[Dict[str, Any]]:
+    """
+    Resume in-progress feedback session.
+
+    Args:
+        story_id: Story ID
+        feedback_dir: Feedback directory
+
+    Returns:
+        In-progress state data if found, None otherwise
+    """
+    story_feedback_dir = feedback_dir / story_id
+
+    if not story_feedback_dir.exists():
+        return None
+
+    # Find in-progress files
+    in_progress_files = list(story_feedback_dir.glob('*-in-progress.json'))
+
+    if not in_progress_files:
+        return None
+
+    # Load most recent
+    most_recent = sorted(in_progress_files)[-1]
+
+    with open(most_recent, 'r') as f:
+        state_data = json.load(f)
+
+    return state_data
+
+
+def detect_rapid_sequence(last_feedback_time: datetime, threshold_seconds: int = 30) -> bool:
+    """
+    Detect if commands are being run in rapid sequence.
+
+    Args:
+        last_feedback_time: Timestamp of last feedback
+        threshold_seconds: Threshold in seconds (default: 30)
+
+    Returns:
+        True if rapid sequence detected, False otherwise
+    """
+    time_since_last = datetime.now(timezone.utc) - last_feedback_time
+    return time_since_last.total_seconds() < threshold_seconds