claude-mpm 5.4.55__py3-none-any.whl → 5.4.85__py3-none-any.whl

claude_mpm/services/agents/deployment/startup_reconciliation.py

@@ -0,0 +1,138 @@
+"""
+Startup Reconciliation Hook
+
+This module provides a hook for performing agent/skill reconciliation
+during application startup, ensuring deployed state matches configuration.
+
+Usage:
+    from claude_mpm.services.agents.deployment.startup_reconciliation import (
+        perform_startup_reconciliation
+    )
+
+    # In your startup code
+    perform_startup_reconciliation()
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.core.logging_utils import get_logger
+from claude_mpm.core.unified_config import UnifiedConfig
+
+from .deployment_reconciler import DeploymentReconciler, DeploymentResult
+
+logger = get_logger(__name__)
+
+
+def perform_startup_reconciliation(
+    project_path: Optional[Path] = None,
+    config: Optional[UnifiedConfig] = None,
+    silent: bool = False,
+) -> tuple[DeploymentResult, DeploymentResult]:
+    """
+    Perform agent and skill reconciliation during startup.
+
+    This ensures the deployed state (.claude/agents, .claude/skills) matches
+    the configuration (agents.enabled, skills.enabled lists).
+
+    Args:
+        project_path: Project directory (default: current directory)
+        config: Configuration instance (auto-loads if None)
+        silent: Suppress info logging (only errors)
+
+    Returns:
+        Tuple of (agent_result, skill_result)
+    """
+    project_path = project_path or Path.cwd()
+
+    # Load config if not provided
+    if config is None:
+        config = UnifiedConfig()
+
+    # Initialize reconciler
+    reconciler = DeploymentReconciler(config)
+
+    if not silent:
+        logger.info("Performing startup reconciliation...")
+
+    # Reconcile agents
+    agent_result = reconciler.reconcile_agents(project_path)
+
+    if agent_result.deployed and not silent:
+        logger.info(f"Deployed agents: {', '.join(agent_result.deployed)}")
+    if agent_result.removed and not silent:
+        logger.info(f"Removed agents: {', '.join(agent_result.removed)}")
+    if agent_result.errors:
+        for error in agent_result.errors:
+            logger.error(f"Agent reconciliation error: {error}")
+
+    # Reconcile skills
+    skill_result = reconciler.reconcile_skills(project_path)
+
+    if skill_result.deployed and not silent:
+        logger.info(f"Deployed skills: {', '.join(skill_result.deployed)}")
+    if skill_result.removed and not silent:
+        logger.info(f"Removed skills: {', '.join(skill_result.removed)}")
+    if skill_result.errors:
+        for error in skill_result.errors:
+            logger.error(f"Skill reconciliation error: {error}")
+
+    if not silent:
+        total_errors = len(agent_result.errors) + len(skill_result.errors)
+        if total_errors == 0:
+            logger.info("Startup reconciliation complete")
+        else:
+            logger.warning(
+                f"Startup reconciliation complete with {total_errors} errors"
+            )
+
+    return agent_result, skill_result
+
+
+def check_reconciliation_needed(
+    project_path: Optional[Path] = None, config: Optional[UnifiedConfig] = None
+) -> bool:
+    """
+    Check if reconciliation is needed (without performing it).
+
+    Args:
+        project_path: Project directory
+        config: Configuration instance
+
+    Returns:
+        True if reconciliation would make changes
+    """
+    project_path = project_path or Path.cwd()
+
+    if config is None:
+        config = UnifiedConfig()
+
+    reconciler = DeploymentReconciler(config)
+    view = reconciler.get_reconciliation_view(project_path)
+
+    agent_state = view["agents"]
+    skill_state = view["skills"]
+
+    # Check if any changes needed
+    return (
+        len(agent_state.to_deploy) > 0
+        or len(agent_state.to_remove) > 0
+        or len(skill_state.to_deploy) > 0
+        or len(skill_state.to_remove) > 0
+    )
+
+
+# Example integration in startup code:
+#
+# from claude_mpm.services.agents.deployment.startup_reconciliation import (
+#     perform_startup_reconciliation,
+#     check_reconciliation_needed
+# )
+#
+# def startup():
+#     # Check if reconciliation needed
+#     if check_reconciliation_needed():
+#         logger.info("Reconciliation needed, performing...")
+#         perform_startup_reconciliation()
+#     else:
+#         logger.debug("No reconciliation needed")

claude_mpm/services/agents/sources/git_source_sync_service.py

@@ -1118,14 +1118,17 @@ class GitSourceSyncService:
                 deploy_filename = Path(agent_path).name
                 deploy_file = deployment_dir / deploy_filename
 
-                # Check if update needed (compare modification times)
+                # Check if update needed (compare content, not just mtime)
+                # DESIGN: Use content hash comparison for reliable change detection
+                # Mtime comparison can fail when cache downloads have older timestamps
                 should_deploy = force
                 was_existing = deploy_file.exists()
 
                 if not force and was_existing:
-                    cache_mtime = cache_file.stat().st_mtime
-                    deploy_mtime = deploy_file.stat().st_mtime
-                    should_deploy = cache_mtime > deploy_mtime
+                    # Compare file contents using hash
+                    cache_content = cache_file.read_bytes()
+                    deploy_content = deploy_file.read_bytes()
+                    should_deploy = cache_content != deploy_content
 
                 if not should_deploy and was_existing:
                     results["skipped"].append(deploy_filename)

claude_mpm/services/agents/startup_sync.py

@@ -32,7 +32,9 @@ from claude_mpm.services.agents.sources.git_source_sync_service import (
 logger = logging.getLogger(__name__)
 
 
-def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+def sync_agents_on_startup(
+    config: Optional[Dict[str, Any]] = None, force_refresh: bool = False
+) -> Dict[str, Any]:
     """Synchronize agents from remote sources on Claude MPM startup.
 
     Design Decision: Single-source support for Stage 1
@@ -44,6 +46,7 @@ def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str,
 
     Args:
         config: Optional configuration dictionary. If None, loads from Config singleton.
+        force_refresh: Force download even if cache is fresh (bypasses ETag).
 
     Returns:
         Dictionary with sync results:
@@ -156,7 +159,7 @@ def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str,
                 )
 
                 # Perform sync
-                sync_result = sync_service.sync_agents(force_refresh=False)
+                sync_result = sync_service.sync_agents(force_refresh=force_refresh)
 
                 # Aggregate results
                 result["sources_synced"] += 1

claude_mpm/services/pm_skills_deployer.py

@@ -98,6 +98,7 @@ class VerificationResult:
         missing_skills: List of missing skill names
         outdated_skills: List of outdated skill names
         message: Summary message
+        skill_count: Total number of deployed skills
     """
 
     verified: bool
@@ -105,6 +106,7 @@ class VerificationResult:
     missing_skills: List[str]
     outdated_skills: List[str]
     message: str
+    skill_count: int = 0
 
 
 @dataclass
@@ -551,6 +553,7 @@ class PMSkillsDeployerService(LoggerMixin):
                 missing_skills=missing_skills,
                 outdated_skills=outdated_skills,
                 message="PM skills not deployed. Run 'claude-mpm init' to deploy.",
+                skill_count=0,
             )
 
         # Check each registered skill exists
@@ -610,6 +613,7 @@ class PMSkillsDeployerService(LoggerMixin):
             missing_skills=missing_skills,
             outdated_skills=outdated_skills,
             message=message,
+            skill_count=len(deployed_skills),
         )
 
     def get_deployed_skills(self, project_dir: Path) -> List[PMSkillInfo]:

claude_mpm/services/skills/git_skill_source_manager.py

@@ -991,12 +991,17 @@ class GitSkillSourceManager:
         progress_callback=None,
         skill_filter: Optional[Set[str]] = None,
     ) -> Dict[str, Any]:
-        """Deploy skills from cache to target directory with flat structure.
+        """Deploy skills from cache to target directory with flat structure and automatic cleanup.
 
         Flattens nested Git repository structure into Claude Code compatible
         flat directory structure. Each skill directory is copied with a
         hyphen-separated name derived from its path.
 
+        CRITICAL: When skill_filter is provided (agent-referenced skills), this function:
+        1. Deploys ONLY the filtered skills
+        2. REMOVES orphaned skills (deployed but not in filter)
+        3. Returns removed_count and removed_skills in result
+
         Transformation Example:
             Cache: collaboration/dispatching-parallel-agents/SKILL.md
             Deploy: collaboration-dispatching-parallel-agents/SKILL.md
@@ -1006,8 +1011,8 @@ class GitSkillSourceManager:
             force: Overwrite existing skills
             progress_callback: Optional callback(increment: int) called for each skill deployed
             skill_filter: Optional set of skill names to deploy (selective deployment).
-                         If None, deploys all skills. If provided, only deploys skills
-                         whose name matches an entry in the filter set.
+                         If None, deploys ALL skills WITHOUT cleanup.
+                         If provided, deploys ONLY filtered skills AND removes orphans.
 
         Returns:
             Dict with deployment results:
@@ -1018,7 +1023,9 @@ class GitSkillSourceManager:
                 "deployed_skills": List[str],
                 "skipped_skills": List[str],
                 "errors": List[str],
-                "filtered_count": int  # Number of skills filtered out
+                "filtered_count": int,  # Number of skills filtered out
+                "removed_count": int,   # Number of orphaned skills removed
+                "removed_skills": List[str]  # Names of removed orphaned skills
             }
 
         Example:
@@ -1026,10 +1033,10 @@ class GitSkillSourceManager:
             >>> result = manager.deploy_skills()
             >>> print(f"Deployed {result['deployed_count']} skills")
 
-            # Selective deployment based on agent requirements:
+            # Selective deployment based on agent requirements (with cleanup):
             >>> required = {"typescript-core", "react-patterns"}
             >>> result = manager.deploy_skills(skill_filter=required)
-            >>> print(f"Deployed {result['deployed_count']} of {len(required)} required skills")
+            >>> print(f"Deployed {result['deployed_count']}, removed {result['removed_count']} orphans")
         """
         if target_dir is None:
             target_dir = Path.home() / ".claude" / "skills"
@@ -1040,6 +1047,7 @@ class GitSkillSourceManager:
         skipped = []
         errors = []
         filtered_count = 0
+        removed_skills = []  # Track removed orphaned skills
 
         # Get all skills from all sources
         all_skills = self.get_all_skills()
@@ -1082,11 +1090,16 @@ class GitSkillSourceManager:
             )
 
             # Cleanup: Remove skills from target directory that aren't in the filtered set
-            # This ensures only the skills in the profile are deployed
+            # This ensures only agent-referenced skills remain deployed
             removed_skills = self._cleanup_unfiltered_skills(target_dir, all_skills)
             if removed_skills:
                 self.logger.info(
-                    f"Removed {len(removed_skills)} skills not in profile filter: {removed_skills}"
+                    f"Removed {len(removed_skills)} orphaned skills not referenced by agents: {removed_skills[:10]}"
+                    + (
+                        f" (and {len(removed_skills) - 10} more)"
+                        if len(removed_skills) > 10
+                        else ""
+                    )
                 )
 
         self.logger.info(
@@ -1130,6 +1143,7 @@ class GitSkillSourceManager:
         self.logger.info(
             f"Deployment complete: {len(deployed)} deployed, "
             f"{len(skipped)} skipped, {len(errors)} errors"
+            + (f", {len(removed_skills)} removed" if removed_skills else "")
         )
 
         return {
@@ -1140,6 +1154,8 @@ class GitSkillSourceManager:
             "skipped_skills": skipped,
             "errors": errors,
             "filtered_count": filtered_count,
+            "removed_count": len(removed_skills),
+            "removed_skills": removed_skills,
         }
 
     def _cleanup_unfiltered_skills(

claude_mpm/services/skills/selective_skill_deployer.py

@@ -44,13 +44,56 @@ from typing import Any, Dict, List, Set, Tuple
 import yaml
 
 from claude_mpm.core.logging_config import get_logger
-from claude_mpm.services.skills.skill_to_agent_mapper import SkillToAgentMapper
 
 logger = get_logger(__name__)
 
 # Deployment tracking index file
 DEPLOYED_INDEX_FILE = ".mpm-deployed-skills.json"
 
+# Core skills that are universally useful across all projects
+# These are deployed when skill mapping returns too many skills (>60)
+# Target: ~25-30 core skills for balanced functionality
+CORE_SKILLS = {
+    # Universal debugging and verification (4 skills)
+    "universal-debugging-systematic-debugging",
+    "universal-debugging-verification-before-completion",
+    "universal-verification-pre-merge",
+    "universal-verification-screenshot",
+    # Universal testing patterns (2 skills)
+    "universal-testing-test-driven-development",
+    "universal-testing-testing-anti-patterns",
+    # Universal architecture and design (1 skill)
+    "universal-architecture-software-patterns",
+    # Universal infrastructure (3 skills)
+    "universal-infrastructure-env-manager",
+    "universal-infrastructure-docker",
+    "universal-infrastructure-github-actions",
+    # Universal collaboration (1 skill)
+    "universal-collaboration-stacked-prs",
+    # Universal emergency/operations (1 skill)
+    "toolchains-universal-emergency-release",
+    "toolchains-universal-dependency-audit",
+    # Common language toolchains (6 skills)
+    "toolchains-typescript-core",
+    "toolchains-python-core",
+    "toolchains-javascript-tooling-biome",
+    "toolchains-python-tooling-mypy",
+    "toolchains-typescript-testing-vitest",
+    "toolchains-python-frameworks-flask",
+    # Common web frameworks (4 skills)
+    "toolchains-javascript-frameworks-nextjs",
+    "toolchains-nextjs-core",
+    "toolchains-typescript-frameworks-nodejs-backend",
+    "toolchains-javascript-frameworks-react-state-machine",
+    # Common testing tools (2 skills)
+    "toolchains-javascript-testing-playwright",
+    "toolchains-typescript-testing-jest",
+    # Common data/UI tools (3 skills)
+    "universal-data-xlsx",
+    "toolchains-ui-styling-tailwind",
+    "toolchains-ui-components-headlessui",
+}
+
 
 def parse_agent_frontmatter(agent_file: Path) -> Dict[str, Any]:
     """Parse YAML frontmatter from agent markdown file.
@@ -140,22 +183,14 @@ def get_skills_from_agent(frontmatter: Dict[str, Any]) -> Set[str]:
 def get_skills_from_mapping(agent_ids: List[str]) -> Set[str]:
     """Get skills for agents using SkillToAgentMapper inference.
 
-    Uses SkillToAgentMapper to find all skills associated with given agent IDs.
-    This provides pattern-based skill discovery beyond explicit frontmatter declarations.
-
-    CRITICAL DESIGN DECISION: This function ONLY returns skills for the DEPLOYED agents
-    provided in agent_ids. It does NOT return skills for all agents in the mapping
-    configuration (skill_to_agent_mapping.yaml lists 41 agents, but only 33 may be deployed).
+    DEPRECATED: This function is deprecated as of Phase 3 refactor.
+    Skills are now declared exclusively in agent frontmatter.
 
-    GENERIC AGENT HANDLING: The generic "engineer" agent is mapped to 100+ skills in the
-    configuration because it's designed as a fallback. To prevent over-deployment when
-    specialized agents exist, we skip "engineer" if specialized agents are present.
+    The static skill_to_agent_mapping.yaml is no longer used for skill deployment.
+    Each agent must declare its skills in frontmatter or it gets zero skills.
 
-    WHY THIS MATTERS:
-    - skill_to_agent_mapping.yaml lists ALL possible agents (41 total)
-    - User may only have 33 agents deployed in ~/.claude/agents/
-    - Without filtering, we'd deploy skills for all 41 agents (over-deployment)
-    - Solution: Only query skills for DEPLOYED agents (passed in agent_ids)
+    This function remains for backward compatibility but is NO LONGER CALLED
+    by get_required_skills_from_agents().
 
     Args:
         agent_ids: List of DEPLOYED agent identifiers (e.g., ["python-engineer", "typescript-engineer"])
@@ -163,67 +198,34 @@ def get_skills_from_mapping(agent_ids: List[str]) -> Set[str]:
 
     Returns:
         Set of unique skill names inferred from mapping configuration for DEPLOYED agents only
+        NOTE: This is now an empty set as the function is deprecated.
 
     Example:
-        >>> # DEPLOYED agents only (from ~/.claude/agents/)
+        >>> # DEPRECATED - use frontmatter instead
         >>> deployed_agent_ids = ["python-engineer", "typescript-engineer", "qa"]
-        >>> skills = get_skills_from_mapping(deployed_agent_ids)
-        >>> print(f"Found {len(skills)} skills for {len(deployed_agent_ids)} deployed agents")
+        >>> skills = get_skills_from_mapping(deployed_agent_ids)  # Returns empty set
     """
-    try:
-        mapper = SkillToAgentMapper()
-        all_skills = set()
-
-        # CRITICAL FIX: Skip generic "engineer" agent if specialized agents exist
-        # The "engineer" agent is mapped to ~107 skills (almost all skills) because
-        # it's a fallback agent. This causes over-deployment when you have specialized
-        # agents like "python-engineer", "typescript-engineer", etc.
-        #
-        # Solution: Filter out "engineer" from agent_ids if specialized agents exist
-        specialized_engineers = [
-            aid for aid in agent_ids if aid.endswith("-engineer") and aid != "engineer"
-        ]
-
-        # If specialized engineers exist, exclude generic "engineer" from skill mapping
-        # This prevents deploying 100+ skills when only a subset is needed
-        agents_to_query = agent_ids
-        if specialized_engineers and "engineer" in agent_ids:
-            agents_to_query = [aid for aid in agent_ids if aid != "engineer"]
-            logger.info(
-                f"Excluding generic 'engineer' agent from skill mapping "
-                f"(found {len(specialized_engineers)} specialized engineers: "
-                f"{', '.join(specialized_engineers[:5])}{'...' if len(specialized_engineers) > 5 else ''})"
-            )
-
-        # IMPORTANT: Only query skills for DEPLOYED agents (those in agent_ids)
-        # Do NOT query all agents from skill_to_agent_mapping.yaml (that's 41 agents)
-        for agent_id in agents_to_query:
-            agent_skills = mapper.get_skills_for_agent(agent_id)
-            if agent_skills:
-                all_skills.update(agent_skills)
-                logger.debug(f"Mapped {len(agent_skills)} skills to {agent_id}")
-
-        logger.info(
-            f"Mapped {len(all_skills)} unique skills for {len(agents_to_query)} deployed agents "
-            f"(out of {len(agent_ids)} total deployed, excluding generic 'engineer' if specialized exist)"
-        )
-        return all_skills
-
-    except Exception as e:
-        logger.warning(f"Failed to load SkillToAgentMapper: {e}")
-        logger.info("Falling back to frontmatter-only skill discovery")
-        return set()
+    # DEPRECATED: Return empty set
+    logger.warning(
+        "get_skills_from_mapping() is DEPRECATED and returns empty set. "
+        "Skills are now declared in agent frontmatter only. "
+        "Update your agents with 'skills:' field in frontmatter."
+    )
+    return set()
 
 
 def get_required_skills_from_agents(agents_dir: Path) -> Set[str]:
     """Extract all skills referenced by deployed agents.
 
-    Combines skills from two sources:
-    1. Explicit frontmatter declarations (skills: field in agent .md files)
-    2. SkillToAgentMapper inference (pattern-based skill discovery)
+    MAJOR CHANGE (Phase 3): Now ONLY uses frontmatter-declared skills.
+    The static skill_to_agent_mapping.yaml is DEPRECATED. Each agent must
+    declare its skills in frontmatter or it gets zero skills deployed.
 
-    This dual-source approach ensures agents get both explicitly declared skills
-    and skills inferred from their domain/toolchain patterns.
+    This change:
+    - Eliminates dual-source complexity (frontmatter + mapping)
+    - Makes skill requirements explicit per agent
+    - Enables per-agent customization via frontmatter
+    - Removes dependency on static YAML mapping
 
     Args:
         agents_dir: Path to deployed agents directory (e.g., .claude/agents/)
@@ -244,13 +246,11 @@ def get_required_skills_from_agents(agents_dir: Path) -> Set[str]:
     agent_files = list(agents_dir.glob("*.md"))
     logger.debug(f"Scanning {len(agent_files)} agent files in {agents_dir}")
 
-    # Source 1: Extract skills from frontmatter
+    # ONLY use frontmatter skills - no more mapping inference
     frontmatter_skills = set()
-    agent_ids = []
 
     for agent_file in agent_files:
         agent_id = agent_file.stem
-        agent_ids.append(agent_id)
 
         frontmatter = parse_agent_frontmatter(agent_file)
         agent_skills = get_skills_from_agent(frontmatter)
@@ -260,24 +260,23 @@ def get_required_skills_from_agents(agents_dir: Path) -> Set[str]:
             logger.debug(
                 f"Agent {agent_id}: {len(agent_skills)} skills from frontmatter"
             )
+        else:
+            logger.debug(f"Agent {agent_id}: No skills declared in frontmatter")
 
-    logger.info(f"Found {len(frontmatter_skills)} unique skills from frontmatter")
-
-    # Source 2: Get skills from SkillToAgentMapper
-    mapped_skills = get_skills_from_mapping(agent_ids)
-
-    # Combine both sources
-    required_skills = frontmatter_skills | mapped_skills
+    logger.info(
+        f"Found {len(frontmatter_skills)} unique skills from agent frontmatter "
+        f"(static mapping no longer used)"
+    )
 
     # Normalize skill paths: convert slashes to dashes for compatibility with deployment
-    # SkillToAgentMapper returns paths like "toolchains/python/frameworks/django"
-    # but deployment expects "toolchains-python-frameworks-django"
-    normalized_skills = {skill.replace("/", "-") for skill in required_skills}
+    # Some skills may use slash format, normalize to dashes
+    normalized_skills = {skill.replace("/", "-") for skill in frontmatter_skills}
 
-    logger.info(
-        f"Combined {len(frontmatter_skills)} frontmatter + {len(mapped_skills)} mapped "
-        f"= {len(required_skills)} total unique skills (normalized to {len(normalized_skills)})"
-    )
+    if normalized_skills != frontmatter_skills:
+        logger.debug(
+            f"Normalized {len(frontmatter_skills)} skills to {len(normalized_skills)} "
+            "(converted slashes to dashes)"
+        )
 
     return normalized_skills
 

claude_mpm/skills/bundled/collaboration/brainstorming/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: Brainstorming Ideas Into Designs
+description: Interactive idea refinement using Socratic method to develop fully-formed designs
+when_to_use: when partner describes any feature or project idea, before writing code or implementation plans
+version: 2.2.0
+progressive_disclosure:
+  level: 1
+  references: []
+  note: Already optimal at 75 lines - intentionally compact, no references needed
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.
+
+**Core principle:** Ask questions to understand, explore alternatives, present design incrementally for validation.
+
+**Announce at start:** "I'm using the Brainstorming skill to refine your idea into a design."
+
+## The Process
+
+### Phase 1: Understanding
+- Check current project state in working directory
+- Ask ONE question at a time to refine the idea
+- Prefer multiple choice when possible
+- Gather: Purpose, constraints, success criteria
+
+### Phase 2: Exploration
+- Propose 2-3 different approaches
+- For each: Core architecture, trade-offs, complexity assessment
+- Ask your human partner which approach resonates
+
+### Phase 3: Design Presentation
+- Present in 200-300 word sections
+- Cover: Architecture, components, data flow, error handling, testing
+- Ask after each section: "Does this look right so far?"
+
+### Phase 4: Worktree Setup (for implementation)
+When design is approved and implementation will follow:
+- Announce: "I'm using the Using Git Worktrees skill to set up an isolated workspace."
+- Switch to skills/collaboration/using-git-worktrees
+- Follow that skill's process for directory selection, safety verification, and setup
+- Return here when worktree ready
+
+### Phase 5: Planning Handoff
+Ask: "Ready to create the implementation plan?"
+
+When your human partner confirms (any affirmative response):
+- Announce: "I'm using the Writing Plans skill to create the implementation plan."
+- Switch to skills/collaboration/writing-plans skill
+- Create detailed plan in the worktree
+
+## When to Revisit Earlier Phases
+
+**You can and should go backward when:**
+- Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1 to understand it
+- Validation shows fundamental gap in requirements → Return to Phase 1
+- Partner questions approach during Phase 3 → Return to Phase 2 to explore alternatives
+- Something doesn't make sense → Go back and clarify
+
+**Don't force forward linearly** when going backward would give better results.
+
+## Related Skills
+
+**During exploration:**
+- When approaches have genuine trade-offs: skills/architecture/preserving-productive-tensions
+
+**Before proposing changes to existing code:**
+- Understand why it exists: skills/research/tracing-knowledge-lineages
+
+## Remember
+- One question per message during Phase 1
+- Apply YAGNI ruthlessly
+- Explore 2-3 alternatives before settling
+- Present incrementally, validate as you go
+- Go backward when needed - flexibility > rigid progression
+- Announce skill usage at start