skill-seekers 2.7.3__py3-none-any.whl

skill_seekers/cli/how_to_guide_builder.py

@@ -0,0 +1,1267 @@
+#!/usr/bin/env python3
+"""
+How-To Guide Builder (C3.3) - Build step-by-step guides from workflow examples
+
+Transforms multi-step test workflows (from C3.2) into educational "how to" guides with:
+- Step-by-step breakdowns
+- Prerequisites and setup requirements
+- Verification checkpoints
+- Troubleshooting sections
+- Complexity levels (beginner/intermediate/advanced)
+
+Usage:
+    # From test examples JSON
+    skill-seekers build-how-to-guides --input test_examples.json
+
+    # From directory (auto-extracts workflows)
+    skill-seekers build-how-to-guides tests/
+
+    # With AI enhancement
+    skill-seekers build-how-to-guides tests/ --enhance-with-ai
+
+Example workflow → guide transformation:
+    Input:  Multi-step test showing user registration + login + session
+    Output: "How To: Complete User Authentication" guide with:
+            - 5 discrete steps with explanations
+            - Prerequisites (database, email service)
+            - Verification points at each step
+            - Common pitfalls and troubleshooting
+            - Related guides suggestions
+"""
+
+import ast
+import hashlib
+import json
+import logging
+import re
+from collections import defaultdict
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Literal
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# DATA MODELS
+# ============================================================================
+
+
+@dataclass
+class PrerequisiteItem:
+    """Enhanced prerequisite with explanation (AI enhancement)"""
+
+    name: str
+    why: str  # Why this is needed
+    setup: str  # How to install/configure
+
+
+@dataclass
+class TroubleshootingItem:
+    """Enhanced troubleshooting with solutions (AI enhancement)"""
+
+    problem: str
+    symptoms: list[str] = field(default_factory=list)  # How to recognize this issue
+    solution: str = ""  # Step-by-step fix
+    diagnostic_steps: list[str] = field(default_factory=list)  # How to diagnose
+
+
+@dataclass
+class WorkflowStep:
+    """Single step in a workflow guide"""
+
+    step_number: int
+    code: str
+    description: str
+    expected_result: str | None = None
+    verification: str | None = None  # Assertion or checkpoint
+    setup_required: str | None = None
+    explanation: str | None = None  # Why this step matters
+    common_pitfall: str | None = None  # Warning for this step
+    common_variations: list[str] = field(default_factory=list)  # AI: Alternative approaches
+
+
+@dataclass
+class HowToGuide:
+    """Complete how-to guide generated from workflow(s)"""
+
+    guide_id: str
+    title: str
+    overview: str
+    complexity_level: Literal["beginner", "intermediate", "advanced"]
+
+    # Prerequisites
+    prerequisites: list[str] = field(default_factory=list)
+    required_imports: list[str] = field(default_factory=list)
+    required_fixtures: list[str] = field(default_factory=list)
+
+    # Content
+    workflows: list[dict] = field(default_factory=list)  # Source workflow examples
+    steps: list[WorkflowStep] = field(default_factory=list)
+
+    # Metadata
+    use_case: str = ""
+    tags: list[str] = field(default_factory=list)
+    estimated_time: str = "10 minutes"
+    source_files: list[str] = field(default_factory=list)
+
+    # Optional AI enhancement (basic)
+    common_pitfalls: list[str] = field(default_factory=list)
+    troubleshooting: dict[str, str] = field(default_factory=dict)
+    variations: list[str] = field(default_factory=list)
+    related_guides: list[str] = field(default_factory=list)
+
+    # AI enhancement (comprehensive - NEW)
+    prerequisites_detailed: list[PrerequisiteItem] = field(default_factory=list)
+    troubleshooting_detailed: list[TroubleshootingItem] = field(default_factory=list)
+    next_steps_detailed: list[str] = field(default_factory=list)
+    use_cases: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        result = asdict(self)
+        # Convert WorkflowStep objects to dicts
+        result["steps"] = [asdict(step) for step in self.steps]
+        return result
+
+
+@dataclass
+class GuideCollection:
+    """Collection of guides organized by category"""
+
+    total_guides: int
+    guides_by_complexity: dict[str, int]
+    guides_by_use_case: dict[str, list[HowToGuide]]
+    guides: list[HowToGuide]
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        return {
+            "total_guides": self.total_guides,
+            "guides_by_complexity": self.guides_by_complexity,
+            "guides_by_use_case": {
+                k: [g.to_dict() for g in v] for k, v in self.guides_by_use_case.items()
+            },
+            "guides": [g.to_dict() for g in self.guides],
+        }
+
+
+# ============================================================================
+# WORKFLOW ANALYZER
+# ============================================================================
+
+
+class WorkflowAnalyzer:
+    """Analyze workflow examples to extract steps and metadata"""
+
+    def analyze_workflow(self, workflow: dict) -> tuple[list[WorkflowStep], dict]:
+        """
+        Deep analysis of workflow structure.
+
+        Args:
+            workflow: TestExample dict from C3.2
+
+        Returns:
+            (steps, metadata) where metadata includes prerequisites, complexity, etc.
+        """
+        code = workflow.get("code", "")
+        language = workflow.get("language", "python").lower()
+
+        # Extract steps based on language
+        if language == "python":
+            steps = self._extract_steps_python(code, workflow)
+        else:
+            steps = self._extract_steps_heuristic(code, workflow)
+
+        # Detect prerequisites
+        metadata = self._detect_prerequisites(workflow)
+
+        # Find verification points
+        verifications = self._find_verification_points(code)
+
+        # Associate verifications with steps
+        for i, step in enumerate(steps):
+            if i < len(verifications):
+                step.verification = verifications[i]
+
+        # Calculate complexity
+        metadata["complexity_level"] = self._calculate_complexity(steps, workflow)
+        metadata["estimated_time"] = self._estimate_time(steps)
+
+        return steps, metadata
+
+    def _extract_steps_python(self, code: str, workflow: dict) -> list[WorkflowStep]:
+        """Extract steps from Python code using AST"""
+        steps = []
+
+        try:
+            tree = ast.parse(code)
+            statements = []
+
+            # Collect all statements
+            for node in ast.walk(tree):
+                if isinstance(node, (ast.Assign, ast.Expr, ast.Assert)):
+                    statements.append(node)
+
+            step_num = 1
+            for stmt in statements:
+                # Skip assertions for now (they're verifications)
+                if isinstance(stmt, ast.Assert):
+                    continue
+
+                # Get code for this statement
+                step_code = ast.get_source_segment(code, stmt)
+                if not step_code:
+                    continue
+
+                # Generate description from code
+                description = self._generate_step_description(stmt, step_code)
+
+                # Check if next statement is assertion (verification)
+                idx = statements.index(stmt)
+                verification = None
+                if idx + 1 < len(statements) and isinstance(statements[idx + 1], ast.Assert):
+                    verification = ast.get_source_segment(code, statements[idx + 1])
+
+                steps.append(
+                    WorkflowStep(
+                        step_number=step_num,
+                        code=step_code,
+                        description=description,
+                        verification=verification,
+                    )
+                )
+                step_num += 1
+
+        except SyntaxError:
+            # Fall back to heuristic method
+            return self._extract_steps_heuristic(code, workflow)
+
+        return steps
+
+    def _extract_steps_heuristic(self, code: str, _workflow: dict) -> list[WorkflowStep]:
+        """Extract steps using heuristics (for non-Python or invalid syntax)"""
+        steps = []
+        lines = code.split("\n")
+
+        current_step = []
+        step_num = 1
+
+        for line in lines:
+            line_stripped = line.strip()
+
+            # Skip empty lines and comments
+            if not line_stripped or line_stripped.startswith("#"):
+                if current_step:
+                    # End of current step
+                    step_code = "\n".join(current_step)
+                    description = self._infer_description_from_code(step_code)
+
+                    steps.append(
+                        WorkflowStep(
+                            step_number=step_num,
+                            code=step_code,
+                            description=description,
+                        )
+                    )
+                    step_num += 1
+                    current_step = []
+                continue
+
+            current_step.append(line)
+
+        # Add final step
+        if current_step:
+            step_code = "\n".join(current_step)
+            description = self._infer_description_from_code(step_code)
+            steps.append(
+                WorkflowStep(step_number=step_num, code=step_code, description=description)
+            )
+
+        return steps
+
+    def _generate_step_description(self, node: ast.AST, code: str) -> str:
+        """Generate human-readable description from AST node"""
+        if isinstance(node, ast.Assign):
+            targets = [self._get_name(t) for t in node.targets]
+            value_desc = self._describe_value(node.value)
+            return f"Assign {', '.join(targets)} = {value_desc}"
+
+        elif isinstance(node, ast.Expr):
+            if isinstance(node.value, ast.Call):
+                func_name = self._get_name(node.value.func)
+                return f"Call {func_name}()"
+
+        return code.split("\n")[0]  # First line as fallback
+
+    def _describe_value(self, node: ast.AST) -> str:
+        """Describe AST value node"""
+        if isinstance(node, ast.Call):
+            func_name = self._get_name(node.func)
+            return f"{func_name}(...)"
+        elif isinstance(node, ast.Constant):
+            return repr(node.value)
+        elif isinstance(node, ast.Name):
+            return node.id
+        return "value"
+
+    def _get_name(self, node: ast.AST) -> str:
+        """Extract name from AST node"""
+        if isinstance(node, ast.Name):
+            return node.id
+        elif isinstance(node, ast.Attribute):
+            return f"{self._get_name(node.value)}.{node.attr}"
+        elif isinstance(node, ast.Call):
+            return self._get_name(node.func)
+        return "unknown"
+
+    def _infer_description_from_code(self, code: str) -> str:
+        """Infer description from code using patterns"""
+        code = code.strip()
+
+        # Method call patterns
+        if "(" in code and ")" in code:
+            match = re.search(r"(\w+)\s*\(", code)
+            if match:
+                return f"Call {match.group(1)}()"
+
+        # Assignment patterns
+        if "=" in code and not code.startswith("assert"):
+            parts = code.split("=", 1)
+            var_name = parts[0].strip()
+            return f"Create {var_name}"
+
+        # Assertion patterns
+        if code.startswith("assert"):
+            return "Verify result"
+
+        return code.split("\n")[0]  # First line
+
+    def _detect_prerequisites(self, workflow: dict) -> dict:
+        """Detect prerequisites from workflow"""
+        metadata = {
+            "prerequisites": [],
+            "required_imports": [],
+            "required_fixtures": [],
+        }
+
+        # Get dependencies from workflow
+        dependencies = workflow.get("dependencies", [])
+        metadata["required_imports"] = dependencies
+
+        # Get setup code
+        setup_code = workflow.get("setup_code")
+        if setup_code:
+            metadata["prerequisites"].append("Setup code must be executed first")
+
+        # Check for common fixtures in test name or setup
+        test_name = workflow.get("test_name", "").lower()
+        if "database" in test_name or (setup_code and "database" in setup_code.lower()):
+            metadata["required_fixtures"].append("database")
+        if "api" in test_name or (setup_code and "api" in setup_code.lower()):
+            metadata["required_fixtures"].append("api_client")
+
+        return metadata
+
+    def _find_verification_points(self, code: str) -> list[str]:
+        """Find assertion statements in code"""
+        verifications = []
+
+        for line in code.split("\n"):
+            line_stripped = line.strip()
+            if line_stripped.startswith("assert"):
+                verifications.append(line_stripped)
+
+        return verifications
+
+    def _calculate_complexity(self, steps: list[WorkflowStep], workflow: dict) -> str:
+        """Calculate complexity level"""
+        num_steps = len(steps)
+
+        # Check for advanced patterns
+        code = workflow.get("code", "")
+        has_async = "async" in code or "await" in code
+        has_mock = "mock" in code.lower() or "patch" in code.lower()
+        has_error_handling = "try" in code or "except" in code
+
+        _complexity_score = workflow.get("complexity_score", 0.5)
+
+        # Determine level
+        if num_steps <= 3 and not has_async and not has_mock:
+            return "beginner"
+        elif num_steps >= 8 or has_async or has_error_handling:
+            return "advanced"
+        else:
+            return "intermediate"
+
+    def _estimate_time(self, steps: list[WorkflowStep]) -> str:
+        """Estimate time to complete guide"""
+        num_steps = len(steps)
+
+        if num_steps <= 3:
+            return "5 minutes"
+        elif num_steps <= 6:
+            return "10 minutes"
+        elif num_steps <= 10:
+            return "15 minutes"
+        else:
+            return "20 minutes"
+
+
+# ============================================================================
+# WORKFLOW GROUPER
+# ============================================================================
+
+
+class WorkflowGrouper:
+    """Group related workflows into coherent guides"""
+
+    def group_workflows(
+        self, workflows: list[dict], strategy: str = "ai-tutorial-group"
+    ) -> dict[str, list[dict]]:
+        """
+        Group workflows using specified strategy.
+
+        Args:
+            workflows: List of workflow examples
+            strategy: "ai-tutorial-group", "file-path", "test-name", "complexity"
+
+        Returns:
+            Dict mapping group name to list of workflows
+        """
+        if strategy == "ai-tutorial-group":
+            return self._group_by_ai_tutorial_group(workflows)
+        elif strategy == "file-path":
+            return self._group_by_file_path(workflows)
+        elif strategy == "test-name":
+            return self._group_by_test_name(workflows)
+        elif strategy == "complexity":
+            return self._group_by_complexity(workflows)
+        else:
+            # Default: AI tutorial group with fallback
+            groups = self._group_by_ai_tutorial_group(workflows)
+            if not groups or len(groups) == len(workflows):
+                # Fallback to file path if AI grouping didn't work well
+                groups = self._group_by_file_path(workflows)
+            return groups
+
+    def _group_by_ai_tutorial_group(self, workflows: list[dict]) -> dict[str, list[dict]]:
+        """Group by AI-generated tutorial_group (from C3.6 enhancement)"""
+        groups = defaultdict(list)
+        ungrouped = []
+
+        for workflow in workflows:
+            ai_analysis = workflow.get("ai_analysis", {})
+            tutorial_group = ai_analysis.get("tutorial_group")
+
+            if tutorial_group:
+                groups[tutorial_group].append(workflow)
+            else:
+                ungrouped.append(workflow)
+
+        # Put ungrouped workflows in individual guides
+        for workflow in ungrouped:
+            test_name = workflow.get("test_name", "Unknown")
+            # Clean test name for title
+            title = self._clean_test_name(test_name)
+            groups[title] = [workflow]
+
+        return dict(groups)
+
+    def _group_by_file_path(self, workflows: list[dict]) -> dict[str, list[dict]]:
+        """Group workflows from same test file"""
+        groups = defaultdict(list)
+
+        for workflow in workflows:
+            file_path = workflow.get("file_path", "")
+            # Extract meaningful name from file path
+            file_name = Path(file_path).stem if file_path else "Unknown"
+            # Remove test_ prefix
+            group_name = file_name.replace("test_", "").replace("_", " ").title()
+            groups[group_name].append(workflow)
+
+        return dict(groups)
+
+    def _group_by_test_name(self, workflows: list[dict]) -> dict[str, list[dict]]:
+        """Group by common test name prefixes"""
+        groups = defaultdict(list)
+
+        for workflow in workflows:
+            test_name = workflow.get("test_name", "")
+            # Extract prefix (e.g., test_auth_login → auth)
+            prefix = self._extract_prefix(test_name)
+            groups[prefix].append(workflow)
+
+        return dict(groups)
+
+    def _group_by_complexity(self, workflows: list[dict]) -> dict[str, list[dict]]:
+        """Group by complexity level"""
+        groups = {"Beginner": [], "Intermediate": [], "Advanced": []}
+
+        for workflow in workflows:
+            complexity_score = workflow.get("complexity_score", 0.5)
+
+            if complexity_score < 0.4:
+                groups["Beginner"].append(workflow)
+            elif complexity_score < 0.7:
+                groups["Intermediate"].append(workflow)
+            else:
+                groups["Advanced"].append(workflow)
+
+        # Remove empty groups
+        return {k: v for k, v in groups.items() if v}
+
+    def _clean_test_name(self, test_name: str) -> str:
+        """Clean test name to readable title"""
+        # Remove test_ prefix
+        name = test_name.replace("test_", "")
+        # Replace underscores with spaces
+        name = name.replace("_", " ")
+        # Title case
+        return name.title()
+
+    def _extract_prefix(self, test_name: str) -> str:
+        """Extract prefix from test name"""
+        # Remove test_ prefix
+        name = test_name.replace("test_", "")
+        # Get first part before underscore
+        parts = name.split("_")
+        if len(parts) > 1:
+            return parts[0].title()
+        return self._clean_test_name(test_name)
+
+
+# ============================================================================
+# GUIDE GENERATOR
+# ============================================================================
+
+
+class GuideGenerator:
+    """Generate markdown guides from workflow data"""
+
+    def generate_guide_markdown(self, guide: HowToGuide) -> str:
+        """
+        Generate complete markdown guide.
+
+        Args:
+            guide: HowToGuide object with all data
+
+        Returns:
+            Complete markdown string
+        """
+        sections = []
+
+        # Header
+        sections.append(self._create_header(guide))
+
+        # Overview
+        sections.append(self._create_overview(guide))
+
+        # Prerequisites
+        if guide.prerequisites or guide.required_imports or guide.required_fixtures:
+            sections.append(self._create_prerequisites(guide))
+
+        # Step-by-step guide
+        sections.append(self._create_steps_section(guide.steps))
+
+        # Complete example
+        sections.append(self._create_complete_example(guide))
+
+        # Troubleshooting (if available)
+        if guide.common_pitfalls or guide.troubleshooting:
+            sections.append(self._create_troubleshooting(guide))
+
+        # Next steps and related guides
+        sections.append(self._create_next_steps(guide))
+
+        # Footer
+        sections.append(self._create_footer(guide))
+
+        return "\n\n".join(sections)
+
+    def _create_header(self, guide: HowToGuide) -> str:
+        """Create guide header with metadata"""
+        lines = [f"# How To: {guide.title}"]
+        lines.append("")
+        lines.append(f"**Difficulty**: {guide.complexity_level.title()}")
+        lines.append(f"**Estimated Time**: {guide.estimated_time}")
+
+        if guide.tags:
+            lines.append(f"**Tags**: {', '.join(guide.tags)}")
+
+        return "\n".join(lines)
+
+    def _create_overview(self, guide: HowToGuide) -> str:
+        """Create overview section"""
+        return f"## Overview\n\n{guide.overview}"
+
+    def _create_prerequisites(self, guide: HowToGuide) -> str:
+        """Create prerequisites section"""
+        lines = ["## Prerequisites"]
+        lines.append("")
+
+        # Checklist format
+        if guide.prerequisites:
+            for prereq in guide.prerequisites:
+                lines.append(f"- [ ] {prereq}")
+            lines.append("")
+
+        # Required imports
+        if guide.required_imports:
+            lines.append("**Required Modules:**")
+            for imp in guide.required_imports:
+                lines.append(f"- `{imp}`")
+            lines.append("")
+
+        # Required fixtures
+        if guide.required_fixtures:
+            lines.append("**Required Fixtures:**")
+            for fixture in guide.required_fixtures:
+                lines.append(f"- `{fixture}` fixture")
+            lines.append("")
+
+        # Setup code if available
+        if guide.workflows and guide.workflows[0].get("setup_code"):
+            setup_code = guide.workflows[0]["setup_code"]
+            lines.append("**Setup Required:**")
+            lines.append("```python")
+            lines.append(setup_code)
+            lines.append("```")
+
+        return "\n".join(lines)
+
+    def _create_steps_section(self, steps: list[WorkflowStep]) -> str:
+        """Create step-by-step guide section"""
+        lines = ["## Step-by-Step Guide"]
+        lines.append("")
+
+        for step in steps:
+            lines.append(f"### Step {step.step_number}: {step.description}")
+            lines.append("")
+
+            # Explanation if available
+            if step.explanation:
+                lines.append(f"**What you're doing:** {step.explanation}")
+                lines.append("")
+
+            # Code
+            lines.append("```python")
+            lines.append(step.code)
+            lines.append("```")
+            lines.append("")
+
+            # Expected result
+            if step.expected_result:
+                lines.append(f"**Expected Result:** {step.expected_result}")
+                lines.append("")
+
+            # Verification checkpoint
+            if step.verification:
+                lines.append("**Verification:**")
+                lines.append("```python")
+                lines.append(step.verification)
+                lines.append("```")
+                lines.append("")
+
+            # Common pitfall warning
+            if step.common_pitfall:
+                lines.append(f"⚠️ **Common Pitfall:** {step.common_pitfall}")
+                lines.append("")
+
+        return "\n".join(lines)
+
+    def _create_complete_example(self, guide: HowToGuide) -> str:
+        """Create complete working example"""
+        lines = ["## Complete Example"]
+        lines.append("")
+        lines.append("```python")
+
+        # If we have workflows, use the first one's code
+        if guide.workflows:
+            workflow = guide.workflows[0]
+
+            # Add setup code if present
+            if workflow.get("setup_code"):
+                lines.append("# Setup")
+                lines.append(workflow["setup_code"])
+                lines.append("")
+
+            # Add main workflow code
+            lines.append("# Workflow")
+            lines.append(workflow.get("code", ""))
+        else:
+            # Combine all steps
+            for step in guide.steps:
+                lines.append(f"# Step {step.step_number}: {step.description}")
+                lines.append(step.code)
+                if step.verification:
+                    lines.append(step.verification)
+                lines.append("")
+
+        lines.append("```")
+        return "\n".join(lines)
+
+    def _create_troubleshooting(self, guide: HowToGuide) -> str:
+        """Create troubleshooting section"""
+        lines = ["## Troubleshooting"]
+        lines.append("")
+
+        # Common pitfalls
+        if guide.common_pitfalls:
+            lines.append("### Common Issues")
+            lines.append("")
+            for i, pitfall in enumerate(guide.common_pitfalls, 1):
+                lines.append(f"{i}. {pitfall}")
+            lines.append("")
+
+        # Specific troubleshooting
+        if guide.troubleshooting:
+            for problem, solution in guide.troubleshooting.items():
+                lines.append(f"### Problem: {problem}")
+                lines.append("")
+                lines.append(f"**Solution:** {solution}")
+                lines.append("")
+
+        return "\n".join(lines)
+
+    def _create_next_steps(self, guide: HowToGuide) -> str:
+        """Create next steps and related guides"""
+        lines = ["## Next Steps"]
+        lines.append("")
+
+        # Variations if available
+        if guide.variations:
+            lines.append("**Try these variations:**")
+            for variation in guide.variations:
+                lines.append(f"- {variation}")
+            lines.append("")
+
+        # Related guides
+        if guide.related_guides:
+            lines.append("## Related Guides")
+            lines.append("")
+            for related in guide.related_guides:
+                lines.append(f"- [{related}]")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    def _create_footer(self, guide: HowToGuide) -> str:
+        """Create guide footer with metadata"""
+        source_info = []
+        if guide.source_files:
+            source_info.append(f"Source: {', '.join(guide.source_files)}")
+        source_info.append(f"Complexity: {guide.complexity_level.title()}")
+        source_info.append(f"Last updated: {datetime.now().strftime('%Y-%m-%d')}")
+
+        return f"---\n\n*{' | '.join(source_info)}*"
+
+    def generate_index(self, guides: list[HowToGuide]) -> str:
+        """
+        Generate index/TOC markdown.
+
+        Args:
+            guides: List of all guides
+
+        Returns:
+            Index markdown string
+        """
+        lines = ["# How-To Guides Index"]
+        lines.append("")
+        lines.append(f"**Total Guides**: {len(guides)}")
+        lines.append(f"**Last Updated**: {datetime.now().strftime('%Y-%m-%d')}")
+        lines.append("")
+
+        # Group by use case
+        by_use_case = defaultdict(list)
+        for guide in guides:
+            use_case = guide.use_case or "Other"
+            by_use_case[use_case].append(guide)
+
+        lines.append("## By Use Case")
+        lines.append("")
+
+        for use_case in sorted(by_use_case.keys()):
+            case_guides = by_use_case[use_case]
+            lines.append(f"### {use_case} ({len(case_guides)} guides)")
+            for guide in sorted(case_guides, key=lambda g: g.complexity_level):
+                # Create filename from guide title
+                filename = guide.title.lower().replace(" ", "-").replace(":", "")
+                lines.append(
+                    f"- [How To: {guide.title}]({use_case.lower()}/{filename}.md) - {guide.complexity_level.title()}"
+                )
+            lines.append("")
+
+        # Group by difficulty
+        by_complexity = defaultdict(list)
+        for guide in guides:
+            by_complexity[guide.complexity_level].append(guide)
+
+        lines.append("## By Difficulty Level")
+        lines.append("")
+
+        for level in ["beginner", "intermediate", "advanced"]:
+            if level in by_complexity:
+                level_guides = by_complexity[level]
+                lines.append(f"### {level.title()} ({len(level_guides)} guides)")
+                for guide in sorted(level_guides, key=lambda g: g.title):
+                    lines.append(f"- {guide.title}")
+                lines.append("")
+
+        return "\n".join(lines)
+
+
+# ============================================================================
+# HOW-TO GUIDE BUILDER (Main Orchestrator)
+# ============================================================================
+
+
+class HowToGuideBuilder:
+    """Main orchestrator for building how-to guides from workflow examples"""
+
+    def __init__(self, enhance_with_ai: bool = True):
+        """
+        Initialize guide builder.
+
+        Args:
+            enhance_with_ai: Enable AI enhancement (requires C3.6 AI analysis in workflows)
+        """
+        self.enhance_with_ai = enhance_with_ai
+        self.analyzer = WorkflowAnalyzer()
+        self.grouper = WorkflowGrouper()
+        self.generator = GuideGenerator()
+
+    def build_guides_from_examples(
+        self,
+        examples: list[dict],
+        grouping_strategy: str = "ai-tutorial-group",
+        output_dir: Path | None = None,
+        enhance_with_ai: bool = True,
+        ai_mode: str = "auto",
+    ) -> GuideCollection:
+        """
+        Main entry point - build guides from workflow examples.
+
+        Args:
+            examples: List of TestExample dicts from C3.2
+            grouping_strategy: How to group workflows ("ai-tutorial-group", "file-path", etc.)
+            output_dir: Optional directory to save markdown files
+            enhance_with_ai: Enable comprehensive AI enhancement (default: True)
+            ai_mode: AI enhancement mode - "auto", "api", "local", or "none"
+
+        Returns:
+            GuideCollection with all generated guides
+        """
+        logger.info(f"Building how-to guides from {len(examples)} examples...")
+
+        # Initialize AI enhancer if requested
+        enhancer = None
+        if enhance_with_ai and ai_mode != "none":
+            try:
+                from .guide_enhancer import GuideEnhancer
+
+                enhancer = GuideEnhancer(mode=ai_mode)
+                logger.info(f"✨ AI enhancement enabled (mode: {enhancer.mode})")
+            except Exception as e:
+                logger.warning(f"⚠️  AI enhancement unavailable: {e}")
+                logger.info("📝 Falling back to basic guide generation")
+
+        # Filter to workflow examples only
+        workflows = self._extract_workflow_examples(examples)
+        logger.info(f"Found {len(workflows)} workflow examples")
+
+        if not workflows:
+            logger.warning("No workflow examples found!")
+            return GuideCollection(
+                total_guides=0,
+                guides_by_complexity={},
+                guides_by_use_case={},
+                guides=[],
+            )
+
+        # Group workflows
+        grouped_workflows = self.grouper.group_workflows(workflows, grouping_strategy)
+        logger.info(f"Grouped into {len(grouped_workflows)} guide categories")
+
+        # Build guides
+        guides = []
+        for title, workflow_group in grouped_workflows.items():
+            guide = self._create_guide(title, workflow_group, enhancer)
+            guides.append(guide)
+
+        # Create collection
+        collection = self._create_collection(guides)
+
+        # Save to files if output directory provided
+        if output_dir:
+            self._save_guides_to_files(collection, output_dir)
+
+        logger.info(f"✅ Generated {len(guides)} how-to guides")
+        return collection
+
+    def _extract_workflow_examples(self, examples: list[dict]) -> list[dict]:
+        """Filter to workflow category only"""
+        return [ex for ex in examples if ex.get("category") == "workflow"]
+
+    def _create_guide(self, title: str, workflows: list[dict], enhancer=None) -> HowToGuide:
+        """
+        Generate single guide from workflow(s).
+
+        Args:
+            title: Guide title
+            workflows: List of related workflow examples
+            enhancer: Optional GuideEnhancer instance for AI enhancement
+
+        Returns:
+            Complete HowToGuide object
+        """
+        # Use first workflow as primary
+        primary_workflow = workflows[0]
+
+        # Analyze workflow to extract steps
+        steps, metadata = self.analyzer.analyze_workflow(primary_workflow)
+
+        # Generate guide ID
+        guide_id = hashlib.md5(title.encode()).hexdigest()[:12]
+
+        # Extract use case from AI analysis or title
+        use_case = title
+        if primary_workflow.get("ai_analysis"):
+            use_case = primary_workflow["ai_analysis"].get("tutorial_group", title)
+
+        # Determine overview
+        overview = self._generate_overview(primary_workflow, workflows)
+
+        # Extract tags
+        tags = primary_workflow.get("tags", [])
+
+        # Extract source files
+        source_files = [w.get("file_path", "") for w in workflows]
+        source_files = [
+            f"{Path(f).name}:{w.get('line_start', 0)}"
+            for f, w in zip(source_files, workflows, strict=False)
+        ]
+
+        # Create guide
+        guide = HowToGuide(
+            guide_id=guide_id,
+            title=title,
+            overview=overview,
+            complexity_level=metadata.get("complexity_level", "intermediate"),
+            prerequisites=metadata.get("prerequisites", []),
+            required_imports=metadata.get("required_imports", []),
+            required_fixtures=metadata.get("required_fixtures", []),
+            workflows=workflows,
+            steps=steps,
+            use_case=use_case,
+            tags=tags,
+            estimated_time=metadata.get("estimated_time", "10 minutes"),
+            source_files=source_files,
+        )
+
+        # Add AI enhancements if enhancer is available
+        if enhancer:
+            self._enhance_guide_with_ai(guide, primary_workflow.get("ai_analysis", {}), enhancer)
+        elif self.enhance_with_ai and primary_workflow.get("ai_analysis"):
+            # Fallback to old enhancement method (basic)
+            self._enhance_guide_with_ai_basic(guide, primary_workflow["ai_analysis"])
+
+        return guide
+
+    def _generate_overview(self, primary_workflow: dict, _all_workflows: list[dict]) -> str:
+        """Generate guide overview"""
+        # Try to get explanation from AI analysis
+        if primary_workflow.get("ai_analysis"):
+            explanation = primary_workflow["ai_analysis"].get("explanation")
+            if explanation:
+                return explanation
+
+        # Fallback to description
+        description = primary_workflow.get("description", "")
+        if description:
+            return description
+
+        # Final fallback
+        return f"Learn how to use {primary_workflow.get('test_name', 'this feature')} in your code."
+
+    def _enhance_guide_with_ai(self, guide: HowToGuide, _ai_analysis: dict, enhancer):
+        """
+        Comprehensively enhance guide with AI using GuideEnhancer.
+
+        Applies all 5 enhancements:
+        1. Step descriptions - Natural language explanations        2. Troubleshooting - Diagnostic flows + solutions
+        3. Prerequisites - Why needed + setup
+        4. Next steps - Related guides, variations
+        5. Use cases - Real-world scenarios
+
+        Args:
+            guide: HowToGuide object to enhance
+            ai_analysis: AI analysis data from C3.6 (for context)
+            enhancer: GuideEnhancer instance
+        """
+        # Prepare guide data for enhancer
+        guide_data = {
+            "title": guide.title,
+            "steps": [{"description": step.description, "code": step.code} for step in guide.steps],
+            "language": "python",  # TODO: Detect from code
+            "prerequisites": guide.prerequisites,
+            "description": guide.overview,
+        }
+
+        # Call enhancer to get all 5 enhancements
+        enhanced_data = enhancer.enhance_guide(guide_data)
+
+        # Apply step enhancements
+        if "step_enhancements" in enhanced_data:
+            for enhancement in enhanced_data["step_enhancements"]:
+                idx = enhancement.step_index
+                if 0 <= idx < len(guide.steps):
+                    guide.steps[idx].explanation = enhancement.explanation
+                    guide.steps[idx].common_variations = enhancement.variations
+
+        # Apply detailed prerequisites
+        if "prerequisites_detailed" in enhanced_data:
+            guide.prerequisites_detailed = enhanced_data["prerequisites_detailed"]
+
+        # Apply troubleshooting
+        if "troubleshooting_detailed" in enhanced_data:
+            guide.troubleshooting_detailed = enhanced_data["troubleshooting_detailed"]
+
+        # Apply next steps
+        if "next_steps_detailed" in enhanced_data:
+            guide.next_steps_detailed = enhanced_data["next_steps_detailed"]
+
+        # Apply use cases
+        if "use_cases" in enhanced_data:
+            guide.use_cases = enhanced_data["use_cases"]
+
+        logger.info(f"✨ Enhanced guide '{guide.title}' with comprehensive AI improvements")
+
+    def _enhance_guide_with_ai_basic(self, guide: HowToGuide, ai_analysis: dict):
+        """
+        Basic enhancement using pre-computed AI analysis from C3.6.
+
+        This is a fallback when GuideEnhancer is not available.
+
+        Args:
+            guide: HowToGuide object to enhance
+            ai_analysis: AI analysis data from C3.6
+        """
+        # Add best practices as variations
+        best_practices = ai_analysis.get("best_practices", [])
+        guide.variations = best_practices
+
+        # Add common mistakes as pitfalls
+        common_mistakes = ai_analysis.get("common_mistakes", [])
+        guide.common_pitfalls = common_mistakes
+
+        # Add related examples as related guides
+        related_examples = ai_analysis.get("related_examples", [])
+        guide.related_guides = [f"How To: {ex}" for ex in related_examples]
+
+        # Enhance step explanations
+        for step in guide.steps:
+            # Add explanation to steps based on best practices
+            if best_practices and step.step_number <= len(best_practices):
+                step.explanation = best_practices[step.step_number - 1]
+
+    def _create_collection(self, guides: list[HowToGuide]) -> GuideCollection:
+        """Create GuideCollection from guides"""
+        # Count by complexity
+        by_complexity = defaultdict(int)
+        for guide in guides:
+            by_complexity[guide.complexity_level] += 1
+
+        # Group by use case
+        by_use_case = defaultdict(list)
+        for guide in guides:
+            use_case = guide.use_case or "Other"
+            by_use_case[use_case].append(guide)
+
+        return GuideCollection(
+            total_guides=len(guides),
+            guides_by_complexity=dict(by_complexity),
+            guides_by_use_case=dict(by_use_case),
+            guides=guides,
+        )
+
+    def _save_guides_to_files(self, collection: GuideCollection, output_dir: Path):
+        """Save guides to markdown files"""
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        logger.info(f"Saving guides to {output_dir}...")
+
+        # Save individual guides
+        for use_case, guides in collection.guides_by_use_case.items():
+            # Create use case directory
+            use_case_dir = output_dir / use_case.lower().replace(" ", "-")
+            use_case_dir.mkdir(parents=True, exist_ok=True)
+
+            for guide in guides:
+                # Generate filename from title
+                filename = guide.title.lower().replace(" ", "-").replace(":", "") + ".md"
+                file_path = use_case_dir / filename
+
+                # Generate and save markdown
+                markdown = self.generator.generate_guide_markdown(guide)
+                file_path.write_text(markdown, encoding="utf-8")
+
+        # Save index
+        index_markdown = self.generator.generate_index(collection.guides)
+        (output_dir / "index.md").write_text(index_markdown, encoding="utf-8")
+
+        logger.info(f"✅ Saved {collection.total_guides} guides + index to {output_dir}")
+
+
+# ============================================================================
+# CLI INTERFACE
+# ============================================================================
+
+
+def main():
+    """CLI entry point for how-to guide builder"""
+    import argparse
+    import sys
+
+    parser = argparse.ArgumentParser(
+        description="Build how-to guides from workflow test examples (C3.3)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # From test examples JSON (C3.2 output)
+  skill-seekers build-how-to-guides --input test_examples.json
+
+  # From directory (extracts workflows)
+  skill-seekers build-how-to-guides tests/
+
+  # Custom grouping strategy
+  skill-seekers build-how-to-guides tests/ --group-by file-path
+
+  # Custom output directory
+  skill-seekers build-how-to-guides tests/ --output tutorials/
+
+  # Without AI enhancement
+  skill-seekers build-how-to-guides tests/ --no-ai
+
+Grouping Strategies:
+  - ai-tutorial-group: Use AI-generated tutorial groups (default, best)
+  - file-path: Group by source test file
+  - test-name: Group by test name patterns
+  - complexity: Group by difficulty level
+""",
+    )
+
+    parser.add_argument(
+        "input",
+        nargs="?",
+        help="Input: directory with test files OR test_examples.json file",
+    )
+
+    parser.add_argument(
+        "--input",
+        dest="input_file",
+        help="Input JSON file with test examples (from C3.2)",
+    )
+
+    parser.add_argument(
+        "--output",
+        default="output/codebase/tutorials",
+        help="Output directory for generated guides (default: output/codebase/tutorials)",
+    )
+
+    parser.add_argument(
+        "--group-by",
+        choices=["ai-tutorial-group", "file-path", "test-name", "complexity"],
+        default="ai-tutorial-group",
+        help="Grouping strategy (default: ai-tutorial-group)",
+    )
+
+    parser.add_argument("--no-ai", action="store_true", help="Disable AI enhancement")
+
+    parser.add_argument(
+        "--json-output",
+        action="store_true",
+        help="Output JSON summary instead of markdown files",
+    )
+
+    args = parser.parse_args()
+
+    # Determine input source
+    input_path = args.input or args.input_file
+
+    if not input_path:
+        parser.print_help()
+        print("\n❌ Error: No input provided")
+        print("   Provide either a directory or --input JSON file")
+        sys.exit(1)
+
+    input_path = Path(input_path)
+
+    # Load examples
+    examples = []
+
+    if input_path.is_file() and input_path.suffix == ".json":
+        # Load from JSON file
+        logger.info(f"Loading examples from {input_path}...")
+        with open(input_path) as f:
+            data = json.load(f)
+            if isinstance(data, dict) and "examples" in data:
+                examples = data["examples"]
+            elif isinstance(data, list):
+                examples = data
+            else:
+                print(f"❌ Error: Invalid JSON format in {input_path}")
+                sys.exit(1)
+
+    elif input_path.is_dir():
+        # Extract from directory using test example extractor
+        print("⚠️  Directory input requires test example extractor")
+        print("   Please use test_examples.json output from C3.2")
+        print(f"   Or run: skill-seekers extract-test-examples {input_path} --json > examples.json")
+        sys.exit(1)
+
+    else:
+        print(f"❌ Error: Input path not found: {input_path}")
+        sys.exit(1)
+
+    # Build guides
+    builder = HowToGuideBuilder(enhance_with_ai=not args.no_ai)
+    output_dir = Path(args.output) if not args.json_output else None
+
+    collection = builder.build_guides_from_examples(
+        examples, grouping_strategy=args.group_by, output_dir=output_dir
+    )
+
+    # Output results
+    if args.json_output:
+        # JSON output
+        print(json.dumps(collection.to_dict(), indent=2))
+    else:
+        # Summary
+        print()
+        print("=" * 60)
+        print("HOW-TO GUIDES GENERATED")
+        print("=" * 60)
+        print()
+        print(f"Total Guides: {collection.total_guides}")
+        print()
+        print("By Complexity:")
+        for level, count in collection.guides_by_complexity.items():
+            print(f"  - {level.title()}: {count} guides")
+        print()
+        print("By Use Case:")
+        for use_case, guides in collection.guides_by_use_case.items():
+            print(f"  - {use_case}: {len(guides)} guides")
+        print()
+        if output_dir:
+            print(f"📁 Output directory: {output_dir}")
+            print(f"📄 Index file: {output_dir}/index.md")
+            print()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()