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

x_ipe/resources/skills/task-type-code-refactor-v2/references/refactoring-techniques.md

@@ -0,0 +1,373 @@
+# Refactoring Techniques Reference
+
+## Input Structure Definitions
+
+### refactoring_scope Structure
+```yaml
+refactoring_scope:
+  files: [<list of file paths>]
+  modules: [<list of module names>]
+  dependencies: [<identified dependencies>]
+  scope_expansion_log: [<log of scope expansions>]
+```
+
+### refactoring_suggestion Structure
+```yaml
+refactoring_suggestion:
+  summary: "<high-level description of suggested refactoring>"
+  goals:
+    - goal: "<specific improvement goal>"
+      priority: high | medium | low
+      rationale: "<why this goal matters>"
+      principle: "<SOLID | DRY | KISS | YAGNI | Modular Design | etc.>"
+  target_structure: "<description of desired structure after refactoring>"
+```
+
+### refactoring_principle Structure
+```yaml
+refactoring_principle:
+  primary_principles:
+    - principle: <SOLID | DRY | KISS | YAGNI | SoC | Modular Design | etc.>
+      rationale: "<why this principle applies>"
+      applications:
+        - area: "<code area>"
+          action: "<specific application>"
+  secondary_principles:
+    - principle: <name>
+      rationale: "<supporting rationale>"
+  constraints:
+    - constraint: "<what to avoid or preserve>"
+      reason: "<why this constraint exists>"
+```
+
+### code_quality_evaluated Structure (from Improve Code Quality)
+```yaml
+code_quality_evaluated:
+  requirements_alignment: { status: aligned, updates_made: [...] }
+  specification_alignment: { status: aligned, updates_made: [...] }
+  test_coverage: { status: sufficient, line_coverage: XX%, tests_added: N }
+  code_alignment:
+    status: aligned | needs_attention | critical
+    file_size_violations: [<files to split>]
+    solid_assessment: { srp, ocp, lsp, isp, dip }
+    kiss_assessment: { over_engineering, straightforward_logic, minimal_dependencies, clear_intent }
+    modular_design_assessment: { module_cohesion, module_coupling, single_entry_point, folder_structure, reusability, testability }
+    code_smells: [<smells to address>]
+  overall_quality_score: <1-10>
+```
+
+---
+
+## Detailed Execution Procedures
+
+### Step 1: Reflect on Context - Detail
+
+```
+1. FOR EACH file in scope:
+   - IDENTIFY associated requirements, features, tech specs
+   - BUILD context_map with all relationships
+
+2. REVIEW refactoring_suggestion:
+   - EXTRACT goals and priorities
+   - NOTE target_structure as end-state vision
+   - UNDERSTAND rationale for each goal
+
+3. REVIEW refactoring_principle:
+   - EXTRACT primary_principles and their applications
+   - NOTE constraints and preservation requirements
+   - MAP principles to specific code areas
+
+4. IDENTIFY impacts (docs, tests, downstream code)
+
+5. VALIDATE alignment:
+   - Suggestions align with code_quality_evaluated gaps?
+   - Principles applicable to identified problem areas?
+   - Constraints achievable with current codebase?
+```
+
+**Output:** context_map with code relationships and principle-to-code mapping
+
+### Step 2: Generate Refactoring Plan - Detail
+
+```
+1. ANALYZE current structure (sizes, smells, principle violations)
+
+2. DESIGN target structure per refactoring_suggestion.target_structure:
+   FOR EACH primary_principle in refactoring_principle:
+     - Apply principle to specific areas as defined in applications
+     - SOLID: Extract classes/modules for SRP violations
+     - DRY: Plan abstractions for duplications
+     - KISS: Plan simplifications
+     - YAGNI: Remove unused code
+     - SoC: Separate mixed concerns
+
+3. CREATE refactoring_plan with phases:
+   FOR EACH goal in refactoring_suggestion.goals (by priority):
+     - phase, name, changes (type/from/to/reason/principle_applied), risk, tests_affected
+     - ENSURE each change references the principle driving it
+
+4. VALIDATE plan against constraints:
+   FOR EACH constraint in refactoring_principle.constraints:
+     - VERIFY plan respects constraint
+     - IF violation → revise plan
+
+5. CREATE test_plan and doc_plan
+
+6. PRESENT plan to human:
+   "Refactoring Plan Summary:
+   - Goals: {goals_addressed}
+   - Principles Applied: {principle_list}
+   - Phases: {phase_count}
+   - Constraints Respected: {constraint_list}
+   
+   [Detailed phase breakdown...]"
+
+7. WAIT for human approval
+```
+
+### Step 3: Execute Refactoring - Detail
+
+```
+FOR EACH phase:
+  1. CREATE checkpoint: git commit -m "checkpoint: before phase {N}"
+  
+  2. FOR EACH change:
+     - Apply change following the principle_applied for this change
+     - VERIFY change aligns with constraint requirements
+     - Update imports and exports
+  
+  3. RUN tests immediately after each change
+  
+  4. IF tests fail:
+     - Import error → Fix import
+     - Behavior changed → REVERT to checkpoint, revise plan
+     - Legitimate update → Update test, document why
+  
+  5. LOG principle application:
+     "Applied {principle} to {area}: {action}"
+  
+  6. COMMIT: git commit -m "refactor({scope}): {description} [principle: {principle}]"
+  
+  7. LOG phase completion with principles applied
+```
+
+### Step 4: Update References - Detail
+
+```
+1. UPDATE technical designs:
+   - Update component list, file locations, import paths
+   - ADD to Design Change Log with date and summary
+
+2. UPDATE feature specifications (file references, code snippets)
+
+3. UPDATE requirements (implementation notes, file references)
+
+4. COMPILE references_updated with all paths
+```
+
+### Step 5: Validate and Complete - Detail
+
+```
+1. RUN final test suite (all must pass, coverage maintained/improved)
+
+2. VALIDATE against refactoring_suggestion.goals:
+   FOR EACH goal:
+     - VERIFY goal achieved
+     - NOTE if partially achieved or skipped
+
+3. VALIDATE against refactoring_principle:
+   FOR EACH primary_principle:
+     - VERIFY principle applied in specified areas
+     - VERIFY no new violations introduced
+   FOR EACH constraint:
+     - VERIFY constraint respected
+
+4. CALCULATE quality improvements:
+   - Run static analysis (before vs after)
+   - Score: readability, maintainability, testability, cohesion, coupling
+   - Calculate overall quality_score_before and quality_score_after
+
+5. VERIFY test coverage (if degraded → add tests before completing)
+
+6. COMPILE refactoring_summary:
+   - files_modified, files_created, files_deleted
+   - tests_updated
+   - principles_applied: [<list with application counts>]
+   - goals_achieved: [<from refactoring_suggestion>]
+
+7. PRESENT summary to human:
+   "Refactoring Complete
+   
+   Goals Achieved: {goal_list}
+   Principles Applied: {principle_list with counts}
+   Constraints Respected: {constraint_list}
+   
+   Quality: {before_score} → {after_score}
+   Coverage: {before}% → {after}%"
+
+8. WAIT for human approval
+
+9. CREATE final commit
+```
+
+---
+
+## Tracing Instrumentation
+
+**Action:** Ensure tracing instrumentation is preserved and applied to new code
+
+```
+1. CHECK existing tracing preservation:
+   - FOR EACH moved function:
+     - VERIFY @x_ipe_tracing decorator still attached
+     - VERIFY redact=[] parameters unchanged
+   - FOR EACH renamed function:
+     - VERIFY decorator remains attached
+
+2. IDENTIFY new code needing tracing:
+   - List all NEW public functions created during refactor
+   - List all functions that were SPLIT into multiple functions
+
+3. INVOKE tool-tracing-instrumentation skill:
+   - Target: All NEW files created during refactoring
+   - Target: All files with NEW public functions
+   - Example: "Add tracing to src/x_ipe/services/extracted_module.py"
+
+4. REVIEW and APPLY proposed decorators:
+   - Verify level assignments match original if function was moved
+   - Verify new functions get appropriate levels
+   - Apply decorators
+
+5. RE-RUN tests to ensure decorators work:
+   pytest tests/ -v
+
+6. UPDATE tracing_preserved and tracing_applied counts in summary
+```
+
+**Skip Conditions:**
+- Skip if project has no tracing infrastructure
+- Skip if refactoring only touched non-code files (docs, config)
+
+### Tracing Preservation Rules
+
+During refactoring, tracing instrumentation MUST be preserved:
+
+1. **When moving functions:**
+   - Keep existing `@x_ipe_tracing` decorators intact
+   - Preserve `redact=[]` parameters unchanged
+   - Update imports if decorator location changes
+
+2. **When splitting modules:**
+   - Each new module's public functions retain/get decorators
+   - Maintain consistent tracing levels (INFO for public, DEBUG for internal)
+
+3. **When renaming functions:**
+   - Decorator stays attached to function
+   - Consider if trace logs will now show new name (expected)
+
+4. **When adding new code during refactor:**
+   - Apply `@x_ipe_tracing` to new public functions
+   - Use `tool-tracing-instrumentation` skill if needed
+
+---
+
+## Safety Check Procedures
+
+### Prerequisite Chain Enforcement
+
+**Before executing this skill, verify the refactoring chain was followed:**
+
+```
+1. CHECK if refactoring_suggestion AND refactoring_principle exist:
+   - These attributes are ONLY produced by task-type-refactoring-analysis
+   
+2. IF refactoring_suggestion OR refactoring_principle is MISSING:
+   → ⛔ STOP execution of this skill
+   → LOG: "Missing prerequisite: task-type-refactoring-analysis not executed"
+   → REDIRECT: Load and execute `task-type-refactoring-analysis` skill first
+   → After completion, chain will auto-proceed through:
+     task-type-refactoring-analysis → task-type-improve-code-quality-before-refactoring → task-type-code-refactor-v2
+
+3. IF code_quality_evaluated is MISSING:
+   → ⛔ STOP execution of this skill
+   → LOG: "Missing prerequisite: task-type-improve-code-quality-before-refactoring not executed"
+   → REDIRECT: Load and execute `task-type-improve-code-quality-before-refactoring` skill first
+
+4. ONLY proceed to Execution Flow if ALL prerequisites are present
+```
+
+### Rollback Procedure
+
+**When:** Tests fail after change
+**Then:**
+```
+1. STOP immediately
+2. Analyze failure cause
+3. If behavior change: git revert to checkpoint
+4. If import issue: fix and retry
+5. If legitimate update: update test carefully
+```
+
+---
+
+## Output Structure Definition
+
+```yaml
+Output:
+  category: code-refactoring-stage
+  status: completed | blocked
+  next_task_type: null
+  require_human_review: Yes
+  auto_proceed: {from input Auto Proceed}
+  task_output_links: [<paths to refactored files>]
+  
+  # Dynamic attributes
+  refactoring_summary:
+    files_modified: <count>
+    files_created: <count>
+    files_deleted: <count>
+    tests_updated: <count>
+    principles_applied:
+      - principle: <SOLID | DRY | KISS | YAGNI | SoC | Modular Design>
+        application_count: <N>
+        areas: [<code areas where applied>]
+    goals_achieved:
+      - goal: "<from refactoring_suggestion>"
+        status: achieved | partially | skipped
+        notes: "<any relevant notes>"
+    constraints_respected: [<list of constraints verified>]
+    
+  code_quality_evaluated:
+    quality_score_before: <1-10>
+    quality_score_after: <1-10>
+    
+    # Code Alignment Improvements
+    code_alignment:
+      file_size_violations:
+        before: <count>
+        after: <count>
+        resolved: [<files that were split>]
+      solid_assessment:
+        before: { srp: status, ocp: status, ... }
+        after: { srp: status, ocp: status, ... }
+      kiss_assessment:
+        before: { over_engineering: status, ... }
+        after: { over_engineering: status, ... }
+      modular_design_assessment:
+        before: { module_cohesion: status, ... }
+        after: { module_cohesion: status, ... }
+      code_smells:
+        before: <count>
+        after: <count>
+        resolved: [<smells addressed>]
+    
+    test_coverage:
+      before: <XX%>
+      after: <XX%>
+      status: maintained | improved | degraded
+      
+    references_updated:
+      requirements: [<paths>]
+      specifications: [<paths>]
+      technical_designs: [<paths>]
+```

x_ipe/resources/skills/task-type-feature-breakdown/SKILL.md

@@ -153,72 +153,17 @@ Execute Feature Breakdown by following these steps in order:
 
 ### Step 2.5: Process Mockups
 
-**⚠️ MANDATORY CHECK - Auto-detect mockups if not provided:**
+**⚠️ MANDATORY CHECK - Auto-detect mockups if not provided**
 
-```
-BEFORE processing mockup_list:
-
-1. IF mockup_list is NOT provided or empty:
-   a. Check if requirement came from an Idea (look for idea folder reference)
-   b. IF idea folder exists:
-      - Scan: x-ipe-docs/ideas/{idea-folder}/mockups/
-      - IF mockups found → Auto-populate mockup_list from found files
-      - Notify: "Found {N} mockups in idea folder, processing..."
-   
-2. IF mockup_list is STILL empty after auto-detection:
-   - Log: "No mockups found - skipping mockup processing"
-   - Proceed to Step 3
-```
-
-**Action:** Copy mockups from source to feature folder and link them
+**Action:** Auto-detect mockups from idea folder, then copy to feature folders and link them.
 
-**When mockup_list is provided (or auto-detected):**
-
-```
-FOR EACH feature in identified_features:
-  1. Create mockups folder: x-ipe-docs/requirements/{FEATURE-ID}/mockups/
-  
-  2. FOR EACH mockup in mockup_list (that relates to this feature):
-     - Copy mockup file from mockup_list source
-     - Rename to: {mockup_name}.{original_extension}
-     - Save to: x-ipe-docs/requirements/{FEATURE-ID}/mockups/{mockup_name}.{ext}
-  
-  3. Record linked mockups for output
-```
-
-**File Operations:**
-```yaml
-# Example: Input mockup_list
-mockup_list:
-  - mockup_name: "main-dashboard"
-    mockup_list: "x-ipe-docs/ideas/Draft Idea - 01232026/mockup.html"
-  - mockup_name: "settings-panel"
-    mockup_list: "x-ipe-docs/ideas/Draft Idea - 01232026/mockups/settings.html"
-
-# Result: Files created
-x-ipe-docs/requirements/FEATURE-001/mockups/main-dashboard.html
-x-ipe-docs/requirements/FEATURE-001/mockups/settings-panel.html
-```
-
-**Linking Mockups:**
-1. Add mockup links to `x-ipe-docs/requirements/requirement-details.md` in "Linked Mockups" table
-2. Add mockup links to each `x-ipe-docs/requirements/{FEATURE-ID}/specification.md` in "Linked Mockups" table
-
-**Mockup List Format:**
-```markdown
-## Linked Mockups
-
-| Mockup Function Name | Mockup List |
-|---------------------|-------------|
-| main-dashboard | [main-dashboard.html](FEATURE-001/mockups/main-dashboard.html) |
-| settings-panel | [settings-panel.html](FEATURE-001/mockups/settings-panel.html) |
-```
+**Procedure:**
+1. If mockup_list empty → scan `x-ipe-docs/ideas/{idea-folder}/mockups/`
+2. If still empty → skip to Step 3
+3. Create `x-ipe-docs/requirements/{FEATURE-ID}/mockups/` for each feature
+4. Copy mockups, link in requirement-details.md and specification.md
 
-**Rules:**
-- If mockup_list is N/A or empty, skip this step
-- Use relative paths from the document location
-- Preserve original file extension when copying
-- Create mockups folder only if mockup_list has items
+**See:** [references/breakdown-guidelines.md](references/breakdown-guidelines.md) for detailed mockup processing procedures and examples.
 
 ---
 
@@ -227,101 +172,23 @@ x-ipe-docs/requirements/FEATURE-001/mockups/settings-panel.html
 **Action:** Create or update requirement-details file (or current active part)
 
 **Target File Determination:**
-```
-IF requirement-details-part-X.md files exist:
-  → Update the CURRENT ACTIVE PART (highest part number)
-  → Add Feature List section to that part
-ELSE:
-  → Update x-ipe-docs/requirements/requirement-details.md
-```
+- IF parts exist → Update CURRENT ACTIVE PART (highest part number)
+- ELSE → Update x-ipe-docs/requirements/requirement-details.md
 
-**Single File Structure (requirement-details.md):**
+**Feature List Table Format:**
 ```markdown
-# Requirement Summary
-
-> Requirement ID: REQ-XXX  
-> Created: MM-DD-YYYY  
-> Last Updated: MM-DD-YYYY
-
-## Overview
-[Brief description of the requirement/epic, 2-3 paragraphs]
-
-## Feature List
-
 | Feature ID | Feature Title | Version | Brief Description | Feature Dependency |
 |------------|---------------|---------|-------------------|-------------------|
-| FEATURE-001 | User Authentication | v1.0 | JWT-based user authentication with login, logout, token refresh | None |
-| FEATURE-002 | User Profile | v1.0 | User profile management and settings | FEATURE-001 |
-
----
-
-## Feature Details
-
-### FEATURE-001: User Authentication
-[Feature details...]
+| FEATURE-001 | User Authentication | v1.0 | JWT-based auth | None |
+| FEATURE-002 | User Profile | v1.0 | Profile management | FEATURE-001 |
 ```
 
-**Part File Structure (requirement-details-part-X.md):**
-```markdown
-# Requirement Details - Part {X}
-
-> Continued from: [requirement-details-part-{X-1}.md](requirement-details-part-{X-1}.md)  
-> Created: MM-DD-YYYY
-
----
-
-## Feature List
-
-| Feature ID | Feature Title | Version | Brief Description | Feature Dependency |
-|------------|---------------|---------|-------------------|-------------------|
-| FEATURE-012 | Design Themes | v1.0 | Theme folder structure and toolbox integration | FEATURE-011 |
-| FEATURE-013 | Default Theme | v1.0 | Pre-built default theme with design tokens | FEATURE-012 |
+**⚠️ IMPORTANT:** Each part file has its OWN Feature List section. Index does NOT contain a Feature List.
 
----
-
-## Linked Mockups
-
-| Mockup Function Name | Feature | Mockup List |
-|---------------------|---------|-------------|
-| themes-toolbox | FEATURE-012 | [themes-toolbox.html](FEATURE-012/mockups/themes-toolbox.html) |
-
----
-
-## Feature Details (Continued)
-
-### FEATURE-012: Design Themes
-[Feature details...]
-```
-
-**⚠️ IMPORTANT:** Each part file has its OWN Feature List section containing ONLY the features in that part. The index file does NOT contain a Feature List.
-
-**Feature Details Template (for each feature):**
-```markdown
-### {FEATURE-ID}: {Feature Title}
-
-**Version:** v{X.Y}  
-**Brief Description:** [1-2 sentence description]
-
-**Acceptance Criteria:**
-- [ ] Criterion 1
-- [ ] Criterion 2
-- [ ] Criterion 3
-
-**Dependencies:**
-- {FEATURE-ID}: [Why needed]
-- None (if no dependencies)
-
-**Technical Considerations:**
-- [Key technical decisions or constraints]
-- [Performance requirements]
-- [Security considerations]
-```
-
-**Rules:**
-- Keep brief description under 50 words
-- List 3-7 acceptance criteria per feature
-- Note dependencies using Feature IDs
-- Technical considerations are hints for design
+**See:** [references/breakdown-guidelines.md](references/breakdown-guidelines.md) for:
+- Full file structure templates (single file and part files)
+- Feature Details template
+- Part file management rules
 
 ---
 
@@ -357,30 +224,11 @@ CALL feature-stage+feature-board-management skill:
 **When to execute:** Only if requirement-details-part-X.md files exist
 
 **Procedure:**
-```
-1. Check if parts exist (requirement-details-part-X.md files)
-2. IF parts exist:
-   a. Open x-ipe-docs/requirements/requirement-details-index.md
-   b. Update "Parts Overview" table with new feature range
-   c. Update "Lines" column with approximate line count
-   d. Save file
-```
-
-**Index File Structure:**
-```markdown
-# Requirement Details Index
-
-> Last Updated: MM-DD-YYYY
-
-## Parts Overview
-
-| Part | File | Features Covered | Lines |
-|------|------|------------------|-------|
-| 1 | [Part 1](requirement-details-part-1.md) | FEATURE-001 to FEATURE-011 | ~420 |
-| 2 | [Part 2](requirement-details-part-2.md) | FEATURE-012 to FEATURE-017 | ~415 |
-```
+1. Open x-ipe-docs/requirements/requirement-details-index.md
+2. Update "Parts Overview" table with new feature range
+3. Update "Lines" column with approximate line count
 
-**⚠️ IMPORTANT:** Index file contains ONLY Parts Overview table. NO Feature List in index - each part has its own.
+**See:** [references/breakdown-guidelines.md](references/breakdown-guidelines.md) for index file structure.
 
 ---
 
@@ -462,86 +310,26 @@ See [references/examples.md](references/examples.md) for detailed execution exam
 
 ## Feature Dependency Guidelines
 
-### Common Dependency Patterns
-
-**Sequential Dependencies:**
-```
-FEATURE-001: User Authentication (no deps)
-FEATURE-002: User Profile (depends on FEATURE-001)
-FEATURE-003: User Settings (depends on FEATURE-002)
-```
-
-**Parallel with Shared Dependency:**
-```
-FEATURE-001: Database Layer (no deps)
-FEATURE-002: User Service (depends on FEATURE-001)
-FEATURE-003: Product Service (depends on FEATURE-001)
-```
-
-**Multiple Dependencies:**
-```
-FEATURE-001: Authentication (no deps)
-FEATURE-002: Authorization (no deps)
-FEATURE-003: Admin Panel (depends on FEATURE-001, FEATURE-002)
-```
-
-### Dependency Rules
-
-1. **No Circular Dependencies** - A cannot depend on B if B depends on A
-2. **Foundation First** - Core/shared features have no dependencies
-3. **Clear Reason** - Document why dependency exists
-4. **Minimal Dependencies** - Only list direct dependencies
+See [references/breakdown-guidelines.md](references/breakdown-guidelines.md) for:
+- Common dependency patterns (sequential, parallel, multiple)
+- Dependency rules (no cycles, foundation first, minimal deps)
 
 ---
 
 ## Best Practices
 
-### Feature Sizing
-
-**Too Large (Split):**
-- "Complete E-Commerce System" → Split into Cart, Payment, Shipping, etc.
-- "User Management" → Split into Registration, Profile, Settings, etc.
-
-**Good Size:**
-- "Shopping Cart Management"
-- "Payment Processing with Stripe"
-- "Email Notification System"
-
-**Too Small (Combine):**
-- "Add to Cart Button" → Part of Shopping Cart feature
-- "Validate Email Format" → Part of User Registration feature
-
-### Feature Naming
-
-**Good Names:**
-- Specific: "JWT Authentication" not "Login"
-- Action-oriented: "User Profile Management" not "User Profile"
-- Technology-agnostic (usually): "Payment Processing" not "Stripe Integration"
-
-**Bad Names:**
-- Too vague: "User Stuff", "Main Feature"
-- Too technical: "REST API Controller Layer"
-- Too broad: "Everything Users Need"
-
-### Version Numbering
-
-- Start with v1.0 for new features
-- Use v1.1, v1.2 for minor enhancements
-- Use v2.0 for major redesigns
-- Most breakdown features will be v1.0
+See [references/breakdown-guidelines.md](references/breakdown-guidelines.md) for:
+- Feature sizing guidelines (too large, good size, too small)
+- Feature naming conventions (good vs bad names)
+- Version numbering rules
 
 ---
 
 ## Integration with Feature Board Management
 
-This skill **MUST** call the feature-board-management skill to create features on the board. This integration:
-
-1. **Creates centralized tracking** - Single source of truth at x-ipe-docs/requirements/features.md
-2. **Initializes status** - All features start with status "Planned"
-3. **Enables queries** - Other skills can query feature board for Feature Data Model
-4. **Supports lifecycle** - Board tracks features through all phases
+This skill **MUST** call the feature-board-management skill to create features on the board.
 
-**See:** `skills/feature-stage+feature-board-management/SKILL.md` for operation details
+See [references/breakdown-guidelines.md](references/breakdown-guidelines.md) for integration details and call format.
 
 ---