code-finder 0.1.0__py3-none-any.whl

claude_context/question_generator.py

@@ -0,0 +1,800 @@
+"""
+Question Generator: Auto-generate context-seeking questions from synthesis templates.
+
+This module bridges the gap between what templates need and what questions should be asked
+in interactive mode to gather that information.
+
+Key features:
+- Template-driven question generation
+- Project type detection (API client, ML framework, CLI tool, etc.)
+- Adaptive questions based on codebase structure
+- README-aware question customization
+"""
+
+from typing import List, Dict, Optional, Tuple, Set
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+import re
+
+
+class QuestionPriority(Enum):
+    """Priority levels for questions in the discovery flow."""
+    CRITICAL = "critical"  # Must ask these first (purpose, users)
+    HIGH = "high"  # Architecture, key features
+    MEDIUM = "medium"  # Implementation patterns
+    LOW = "low"  # Nice-to-have details
+
+
+class ProjectType(Enum):
+    """Detected project types based on codebase analysis."""
+    API_CLIENT = "api_client"  # HTTP client libraries
+    ML_FRAMEWORK = "ml_framework"  # Machine learning frameworks
+    WEB_FRAMEWORK = "web_framework"  # Web servers/APIs
+    CLI_TOOL = "cli_tool"  # Command-line tools
+    DATA_PIPELINE = "data_pipeline"  # Data processing/ETL
+    LIBRARY = "library"  # General purpose library
+    APPLICATION = "application"  # Standalone application
+    UNKNOWN = "unknown"  # Cannot determine
+
+
+class QuestionFocus(Enum):
+    """Question focus: user-facing vs technical deep-dive."""
+    USER_FOCUSED = "user_focused"  # Quickstart, install, examples
+    TECHNICAL = "technical"  # Architecture, internals, patterns
+
+
+@dataclass
+class GeneratedQuestion:
+    """A question auto-generated from template requirements."""
+    text: str
+    priority: QuestionPriority
+    section_target: str  # Which template section this helps populate
+    evidence_sources: List[str]  # Where to look for answers (README, code, etc.)
+    rationale: str  # Why this question matters
+
+
+def detect_project_type(repository_path: str, readme_content: Optional[str] = None) -> ProjectType:
+    """
+    Detect project type from repository structure and README content.
+    
+    Uses multiple signals:
+    1. README keywords and descriptions (most reliable)
+    2. File structure patterns
+    3. Common import patterns
+    4. Package naming conventions
+    
+    Args:
+        repository_path: Path to repository root
+        readme_content: Optional README content (if already loaded)
+        
+    Returns:
+        Detected ProjectType
+    """
+    repo_path = Path(repository_path)
+    
+    # Signal scores for each type
+    scores: Dict[ProjectType, int] = {ptype: 0 for ptype in ProjectType}
+    
+    # 1. Analyze README (highest weight: 5 points per match)
+    if readme_content:
+        readme_lower = readme_content.lower()
+        
+        # API Client indicators
+        if any(phrase in readme_lower for phrase in [
+            "api client", "client library", "rest client", "http client",
+            "client for", "sdk for", "provides access to"
+        ]):
+            scores[ProjectType.API_CLIENT] += 5
+        
+        # ML Framework indicators
+        if any(phrase in readme_lower for phrase in [
+            "machine learning", "deep learning", "neural network",
+            "training", "inference", "model", "dataset", "pytorch", "tensorflow"
+        ]):
+            scores[ProjectType.ML_FRAMEWORK] += 5
+        
+        # Web Framework indicators
+        if any(phrase in readme_lower for phrase in [
+            "web framework", "rest api", "web server", "http server",
+            "api endpoints", "routes", "fastapi", "flask", "django"
+        ]):
+            scores[ProjectType.WEB_FRAMEWORK] += 5
+        
+        # CLI Tool indicators
+        if any(phrase in readme_lower for phrase in [
+            "command line", "cli tool", "command-line interface",
+            "terminal", "shell", "commands"
+        ]):
+            scores[ProjectType.CLI_TOOL] += 5
+        
+        # Data Pipeline indicators
+        if any(phrase in readme_lower for phrase in [
+            "data pipeline", "etl", "data processing", "workflow",
+            "data transformation", "airflow", "dagster"
+        ]):
+            scores[ProjectType.DATA_PIPELINE] += 5
+    
+    # 2. Analyze file structure (medium weight: 2 points per match)
+    if repo_path.exists():
+        # Look for characteristic files
+        file_patterns = {
+            ProjectType.API_CLIENT: [
+                "**/client.py", "**/api_client.py", "**/*_client.py",
+                "**/http_client.py", "**/rest_client.py"
+            ],
+            ProjectType.ML_FRAMEWORK: [
+                "**/model.py", "**/models.py", "**/trainer.py",
+                "**/training.py", "**/dataset.py", "**/datasets.py"
+            ],
+            ProjectType.WEB_FRAMEWORK: [
+                "**/app.py", "**/routes.py", "**/views.py",
+                "**/api.py", "**/endpoints.py", "**/server.py"
+            ],
+            ProjectType.CLI_TOOL: [
+                "**/cli.py", "**/commands.py", "**/__main__.py",
+                "**/main.py", "**/console.py"
+            ],
+            ProjectType.DATA_PIPELINE: [
+                "**/pipeline.py", "**/dag.py", "**/workflow.py",
+                "**/etl.py", "**/tasks.py"
+            ],
+        }
+        
+        for proj_type, patterns in file_patterns.items():
+            for pattern in patterns:
+                matches = list(repo_path.glob(pattern))
+                if matches:
+                    scores[proj_type] += 2
+                    break  # Count each pattern type once
+    
+    # 3. Analyze package/project name (low weight: 1 point)
+    project_name = repo_path.name.lower()
+    
+    if "client" in project_name or "sdk" in project_name:
+        scores[ProjectType.API_CLIENT] += 1
+    if "cli" in project_name or "cmd" in project_name:
+        scores[ProjectType.CLI_TOOL] += 1
+    if "api" in project_name or "server" in project_name:
+        scores[ProjectType.WEB_FRAMEWORK] += 1
+    
+    # 4. Determine winner
+    max_score = max(scores.values())
+    
+    if max_score == 0:
+        return ProjectType.UNKNOWN
+    
+    # Get type with highest score
+    detected_type = max(scores.items(), key=lambda x: x[1])[0]
+    
+    # If score is very low and it's LIBRARY, mark as UNKNOWN
+    if detected_type == ProjectType.LIBRARY and max_score < 3:
+        return ProjectType.UNKNOWN
+    
+    return detected_type
+
+
+class TemplateQuestionGenerator:
+    """
+    Generates targeted questions from synthesis template specifications.
+    
+    The key insight: Template instructions tell us WHAT content we need.
+    We can reverse-engineer QUESTIONS that will gather that content.
+    
+    Now with adaptive question generation based on project type detection!
+    """
+    
+    # Mapping of instruction keywords to question templates (BASE PATTERNS)
+    INSTRUCTION_PATTERNS = {
+        # Purpose and Problem
+        "purpose": {
+            "questions": [
+                "What is the main purpose of this project according to the README or documentation?",
+                "What specific problem does this codebase solve?",
+            ],
+            "priority": QuestionPriority.CRITICAL,
+            "sources": ["README*", "docs/", "**/__init__.py"]
+        },
+        
+        # Target Audience
+        "target audience": {
+            "questions": [
+                "Who is the intended audience or user base for this project?",
+                "What types of developers or organizations would use this?",
+            ],
+            "priority": QuestionPriority.CRITICAL,
+            "sources": ["README*", "docs/", "CONTRIBUTING*"]
+        },
+        
+        # Use Cases
+        "use case": {
+            "questions": [
+                "What are the primary use cases for this project as described in documentation?",
+                "What real-world problems can users solve with this?",
+            ],
+            "priority": QuestionPriority.CRITICAL,
+            "sources": ["README*", "docs/examples/", "examples/"]
+        },
+        
+        # Key Features
+        "key feature": {
+            "questions": [
+                "What are the key features or capabilities highlighted in the README?",
+                "What makes this project unique or different from alternatives?",
+            ],
+            "priority": QuestionPriority.HIGH,
+            "sources": ["README*", "docs/", "CHANGELOG*"]
+        },
+        
+        # Architecture
+        "architecture": {
+            "questions": [
+                "What is the high-level architecture of this system?",
+                "What are the main components and how do they relate?",
+            ],
+            "priority": QuestionPriority.HIGH,
+            "sources": ["docs/architecture/", "README*", "**/__init__.py"]
+        },
+        
+        # Components
+        "component": {
+            "questions": [
+                "What are the core components or modules in this codebase?",
+                "How are components organized and what are their responsibilities?",
+            ],
+            "priority": QuestionPriority.HIGH,
+            "sources": ["src/", "lib/", "**/__init__.py"]
+        },
+        
+        # API/Interface
+        "api": {
+            "questions": [
+                "What are the main public APIs or interfaces provided?",
+                "How do users interact with this library programmatically?",
+            ],
+            "priority": QuestionPriority.MEDIUM,
+            "sources": ["README*", "docs/api/", "**/__init__.py"]
+        },
+        
+        # Authentication
+        "authentication": {
+            "questions": [
+                "What authentication mechanisms are supported?",
+                "How do users configure authentication?",
+            ],
+            "priority": QuestionPriority.MEDIUM,
+            "sources": ["README*", "docs/", "**/auth*"]
+        },
+        
+        # Installation
+        "installation": {
+            "questions": [
+                "How do users install this project?",
+                "What are the dependencies and requirements?",
+            ],
+            "priority": QuestionPriority.MEDIUM,
+            "sources": ["README*", "setup.py", "pyproject.toml", "requirements.txt"]
+        },
+    }
+    
+    # Type-specific question patterns (ADAPTIVE PATTERNS)
+    TYPE_SPECIFIC_PATTERNS = {
+        ProjectType.API_CLIENT: {
+            "client": {
+                "questions": [
+                    "What API or service does this client library connect to?",
+                    "How do users initialize and configure the client?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*", "**/client.py"]
+            },
+            "authentication": {
+                "questions": [
+                    "What authentication methods does this client support?",
+                    "How do users provide API credentials?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*", "**/auth*"]
+            },
+            "resources": {
+                "questions": [
+                    "What API resources or endpoints are available through this client?",
+                    "What operations can users perform with this client?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*", "**/*.py"]
+            },
+        },
+        ProjectType.ML_FRAMEWORK: {
+            "models": {
+                "questions": [
+                    "What types of machine learning models does this framework support?",
+                    "What model architectures are provided or supported?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*", "**/model*.py"]
+            },
+            "training": {
+                "questions": [
+                    "What training capabilities does this framework provide?",
+                    "How do users train models with this framework?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*", "**/train*.py", "**/trainer.py"]
+            },
+            "inference": {
+                "questions": [
+                    "How does model inference work in this framework?",
+                    "What inference APIs or methods are provided?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*", "**/infer*.py", "**/predict*.py"]
+            },
+        },
+        ProjectType.WEB_FRAMEWORK: {
+            "endpoints": {
+                "questions": [
+                    "What types of web APIs or endpoints does this framework help create?",
+                    "How do developers define routes or endpoints?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*", "**/routes.py", "**/api.py"]
+            },
+            "middleware": {
+                "questions": [
+                    "What middleware or request handling features are provided?",
+                    "How does request/response processing work?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*", "**/middleware.py"]
+            },
+        },
+        ProjectType.CLI_TOOL: {
+            "commands": {
+                "questions": [
+                    "What commands does this CLI tool provide?",
+                    "How do users invoke the main functionality?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*", "**/cli.py", "**/commands.py"]
+            },
+            "options": {
+                "questions": [
+                    "What command-line options and arguments are available?",
+                    "What configuration can users control via CLI flags?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*", "**/cli.py"]
+            },
+        },
+        ProjectType.DATA_PIPELINE: {
+            "pipeline": {
+                "questions": [
+                    "What data processing pipelines or workflows does this support?",
+                    "How do users define and run data pipelines?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*", "**/pipeline.py", "**/dag.py"]
+            },
+            "transforms": {
+                "questions": [
+                    "What data transformation capabilities are provided?",
+                    "How does data flow through the pipeline?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*", "**/transform*.py"]
+            },
+        },
+    }
+    
+    # User-focused question patterns (for README best practices)
+    USER_FOCUSED_PATTERNS = {
+        ProjectType.API_CLIENT: {
+            "summary": {
+                "questions": [
+                    "What is the one-sentence summary of this project from the README?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*"]
+            },
+            "install": {
+                "questions": [
+                    "What is the exact installation command shown in the README?",
+                    "What are the system requirements mentioned in the README (Python version, OS)?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*"]
+            },
+            "quickstart": {
+                "questions": [
+                    "What is the minimal working code example in the README?",
+                    "What code examples are provided in the README for basic usage?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*"]
+            },
+            "auth_practical": {
+                "questions": [
+                    "How do users provide authentication credentials according to the README?",
+                    "What is the recommended way to handle API keys mentioned in README?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*"]
+            },
+            "configuration": {
+                "questions": [
+                    "What configuration options or environment variables are documented?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*", ".env.example"]
+            },
+        },
+        ProjectType.ML_FRAMEWORK: {
+            "summary": {
+                "questions": [
+                    "What is the one-sentence description of this ML framework from the README?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*"]
+            },
+            "install": {
+                "questions": [
+                    "What is the installation command shown in the README?",
+                    "What hardware requirements are mentioned (GPU, CPU, memory)?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*"]
+            },
+            "quickstart": {
+                "questions": [
+                    "What is the basic training or inference example shown in the README?",
+                    "What minimal code example is provided for getting started?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*", "examples/"]
+            },
+            "models": {
+                "questions": [
+                    "What pretrained models or checkpoints are available according to README?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*"]
+            },
+        },
+        ProjectType.CLI_TOOL: {
+            "summary": {
+                "questions": [
+                    "What is the one-sentence description of this CLI tool from the README?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*"]
+            },
+            "install": {
+                "questions": [
+                    "What is the installation command for this CLI tool?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*"]
+            },
+            "quickstart": {
+                "questions": [
+                    "What is the most basic command users would run according to README?",
+                    "What common commands are shown in the README examples?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*"]
+            },
+            "configuration": {
+                "questions": [
+                    "What CLI flags or configuration options are documented?",
+                ],
+                "priority": QuestionPriority.HIGH,
+                "sources": ["README*"]
+            },
+        },
+        ProjectType.WEB_FRAMEWORK: {
+            "summary": {
+                "questions": [
+                    "What is the one-sentence description of this framework from the README?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*"]
+            },
+            "install": {
+                "questions": [
+                    "What is the installation command shown in the README?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*"]
+            },
+            "quickstart": {
+                "questions": [
+                    "What is the minimal 'Hello World' example shown in the README?",
+                    "How do users create and run a basic server according to examples?",
+                ],
+                "priority": QuestionPriority.CRITICAL,
+                "sources": ["README*", "examples/"]
+            },
+        },
+    }
+    
+    def generate_user_focused_questions(
+        self,
+        repository_path: str,
+        readme_content: Optional[str] = None,
+        project_type: Optional[ProjectType] = None,
+        max_questions: int = 10
+    ) -> List[GeneratedQuestion]:
+        """
+        Generate user-focused questions following README best practices.
+        
+        Prioritizes: Quickstart > Installation > Usage > Architecture
+        Focus: Getting users to success in 10 minutes
+        
+        Args:
+            repository_path: Path to repository
+            readme_content: Optional README content
+            project_type: Optional pre-detected project type
+            max_questions: Maximum questions to generate
+            
+        Returns:
+            List of user-focused questions prioritized for first-time users
+        """
+        # Detect project type if not provided
+        if project_type is None:
+            project_type = detect_project_type(repository_path, readme_content)
+        
+        questions: List[GeneratedQuestion] = []
+        
+        # Get user-focused patterns for this project type
+        if project_type in self.USER_FOCUSED_PATTERNS:
+            patterns = self.USER_FOCUSED_PATTERNS[project_type]
+            
+            for pattern_name, config in patterns.items():
+                for question_text in config["questions"]:
+                    questions.append(
+                        GeneratedQuestion(
+                            text=question_text,
+                            priority=config["priority"],
+                            section_target=pattern_name.title(),
+                            evidence_sources=config["sources"],
+                            rationale=f"User-focused README: {pattern_name}"
+                        )
+                    )
+        
+        # Deduplicate and sort by priority
+        seen = set()
+        unique = []
+        for q in questions:
+            if q.text not in seen:
+                seen.add(q.text)
+                unique.append(q)
+        
+        priority_order = {
+            QuestionPriority.CRITICAL: 0,
+            QuestionPriority.HIGH: 1,
+            QuestionPriority.MEDIUM: 2,
+            QuestionPriority.LOW: 3,
+        }
+        unique.sort(key=lambda q: priority_order[q.priority])
+        
+        return unique[:max_questions]
+    
+    def generate_questions_from_template(
+        self, 
+        template_spec: Dict,
+        repository_path: Optional[str] = None,
+        readme_content: Optional[str] = None,
+        max_questions: int = 15,
+        project_type: Optional[ProjectType] = None,
+        focus: QuestionFocus = QuestionFocus.TECHNICAL
+    ) -> List[GeneratedQuestion]:
+        """
+        Generate prioritized questions from a synthesis template.
+        
+        NOW WITH ADAPTIVE QUESTION GENERATION based on project type!
+        NOW WITH USER-FOCUSED option for README best practices!
+        
+        Args:
+            template_spec: The synthesis template configuration
+            repository_path: Path to repository for project type detection
+            readme_content: Optional README content for better detection
+            max_questions: Maximum number of questions to generate
+            project_type: Optional pre-detected project type (skips detection)
+            focus: USER_FOCUSED (quickstart first) or TECHNICAL (architecture first)
+            
+        Returns:
+            List of questions, sorted by priority and adapted to project type
+        """
+        generated_questions: List[GeneratedQuestion] = []
+        
+        # Detect project type if not provided
+        if project_type is None and repository_path:
+            project_type = detect_project_type(repository_path, readme_content)
+        
+        # Choose pattern set based on focus
+        if focus == QuestionFocus.USER_FOCUSED:
+            # Use user-focused patterns (installation, quickstart, examples)
+            all_patterns = dict(self.INSTRUCTION_PATTERNS)
+            
+            if project_type and project_type in self.USER_FOCUSED_PATTERNS:
+                user_patterns = self.USER_FOCUSED_PATTERNS[project_type]
+                all_patterns.update(user_patterns)
+                
+                print(f"🔍 Detected project type: {project_type.value}")
+                print(f"   Using USER-FOCUSED question mode (quickstart first)")
+                print(f"   Added {len(user_patterns)} user-focused question patterns")
+        else:
+            # Use technical patterns (architecture, internals)
+            all_patterns = dict(self.INSTRUCTION_PATTERNS)
+            
+            if project_type and project_type in self.TYPE_SPECIFIC_PATTERNS:
+                type_patterns = self.TYPE_SPECIFIC_PATTERNS[project_type]
+                all_patterns.update(type_patterns)
+                
+                print(f"🔍 Detected project type: {project_type.value}")
+                print(f"   Using TECHNICAL question mode (architecture first)")
+                print(f"   Added {len(type_patterns)} technical question patterns")
+        
+        for section in template_spec.get("sections", []):
+            if not section.get("enabled", True):
+                continue
+                
+            section_name = section.get("name", "")
+            instructions = section.get("instructions", "").lower()
+            
+            # Match instruction patterns to generate relevant questions
+            for pattern, config in all_patterns.items():
+                if pattern in instructions:
+                    for question_text in config["questions"]:
+                        generated_questions.append(
+                            GeneratedQuestion(
+                                text=question_text,
+                                priority=config["priority"],
+                                section_target=section_name,
+                                evidence_sources=config["sources"],
+                                rationale=f"Needed for {section_name} section: {pattern} (type: {project_type.value if project_type else 'generic'})"
+                            )
+                        )
+        
+        # Remove duplicates while preserving order
+        seen = set()
+        unique_questions = []
+        for q in generated_questions:
+            if q.text not in seen:
+                seen.add(q.text)
+                unique_questions.append(q)
+        
+        # Sort by priority (critical first)
+        priority_order = {
+            QuestionPriority.CRITICAL: 0,
+            QuestionPriority.HIGH: 1,
+            QuestionPriority.MEDIUM: 2,
+            QuestionPriority.LOW: 3,
+        }
+        unique_questions.sort(key=lambda q: priority_order[q.priority])
+        
+        return unique_questions[:max_questions]
+    
+    def create_question_flow(
+        self, 
+        template_spec: Dict,
+        repository_path: Optional[str] = None,
+        readme_content: Optional[str] = None
+    ) -> Dict[str, List[GeneratedQuestion]]:
+        """
+        Create a structured question flow with phases.
+        
+        NOW WITH ADAPTIVE QUESTIONS based on project type!
+        
+        Returns:
+            Dictionary with phases: "context", "architecture", "implementation"
+        """
+        all_questions = self.generate_questions_from_template(
+            template_spec, 
+            repository_path=repository_path,
+            readme_content=readme_content
+        )
+        
+        flow = {
+            "context": [],  # CRITICAL priority questions
+            "architecture": [],  # HIGH priority questions  
+            "implementation": [],  # MEDIUM/LOW priority questions
+        }
+        
+        for q in all_questions:
+            if q.priority == QuestionPriority.CRITICAL:
+                flow["context"].append(q)
+            elif q.priority == QuestionPriority.HIGH:
+                flow["architecture"].append(q)
+            else:
+                flow["implementation"].append(q)
+        
+        return flow
+
+
+def suggest_next_question(
+    qa_history: List[Tuple[str, str]], 
+    template_spec: Dict,
+    current_phase: Optional[str] = None
+) -> Optional[str]:
+    """
+    Suggest the next question to ask based on history and template needs.
+    
+    Args:
+        qa_history: List of (question, answer) tuples asked so far
+        template_spec: The synthesis template
+        current_phase: Current exploration phase
+        
+    Returns:
+        Suggested question text or None if all covered
+    """
+    generator = TemplateQuestionGenerator()
+    flow = generator.create_question_flow(template_spec)
+    
+    asked_questions = {q for q, _ in qa_history}
+    
+    # Determine current phase
+    if current_phase is None:
+        if len(qa_history) < 3:
+            current_phase = "context"
+        elif len(qa_history) < 8:
+            current_phase = "architecture"
+        else:
+            current_phase = "implementation"
+    
+    # Find first unanswered question in current phase
+    for question in flow.get(current_phase, []):
+        if question.text not in asked_questions:
+            return question.text
+    
+    # Move to next phase if current phase complete
+    phase_order = ["context", "architecture", "implementation"]
+    current_idx = phase_order.index(current_phase)
+    
+    for next_phase in phase_order[current_idx + 1:]:
+        for question in flow[next_phase]:
+            if question.text not in asked_questions:
+                return question.text
+    
+    return None  # All questions covered
+
+
+def generate_context_discovery_questions(project_type: str = "general") -> List[str]:
+    """
+    Generate essential context discovery questions for any project.
+    
+    These questions should be asked FIRST before any code-specific questions.
+    """
+    base_questions = [
+        "What is the main purpose of this project according to the README or documentation?",
+        "What problem does this codebase solve for its users?",
+        "Who is the target audience for this project?",
+        "What are the primary use cases mentioned in the documentation?",
+    ]
+    
+    type_specific = {
+        "api_client": [
+            "What API or service does this client library connect to?",
+            "What are the main API resources or endpoints available?",
+        ],
+        "ml_framework": [
+            "What type of machine learning models or tasks does this support?",
+            "What are the key training or inference capabilities?",
+        ],
+        "web_framework": [
+            "What type of web applications is this framework designed for?",
+            "What are the core web development features provided?",
+        ],
+        "cli_tool": [
+            "What commands or workflows does this CLI tool support?",
+            "What tasks can users automate with this tool?",
+        ],
+    }
+    
+    questions = base_questions.copy()
+    if project_type in type_specific:
+        questions.extend(type_specific[project_type])
+    
+    return questions
+