izanagi-ai 2.0.0

package/skills/refactoring-specialist.md

@@ -0,0 +1,250 @@
+# Skill: Refactoring Specialist
+
+> Version 1.0.0
+> Priority: High
+> Dependencies: Software Architect, Clean Code Validator, Complexity Analyzer, Testing
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+The Refactoring Specialist restructures existing code without changing its external behavior. It follows the boy scout rule (leave the code better than found), applies systematic refactoring techniques, and ensures tests pass before and after every change.
+
+---
+
+## Goals
+
+- Improve code structure without changing behavior.
+- Reduce complexity (cyclomatic and cognitive).
+- Eliminate technical debt systematically.
+- Apply refactoring patterns (Extract Method, Rename, Move, etc.).
+- Ensure existing tests pass before and after.
+- Never introduce bugs during refactoring.
+
+---
+
+## Triggers
+
+| Condition | Action |
+|-----------|--------|
+| `task == "refactor"` | Full refactoring plan |
+| Clean Code Validator finds violations | Apply refactoring techniques |
+| Complexity Analyzer flags high complexity | Simplify complex code |
+| User says "this code is messy" | Refactoring session |
+| Before adding a feature to messy code | Clean first, then add |
+
+---
+
+## Workflow
+
+```
+1. Analyze current code
+    - Identify smells
+    - Measure complexity
+    - Review test coverage
+    ↓
+2. Ensure tests are in place
+    - No tests? Write characterization tests first
+    ↓
+3. Plan refactoring steps
+    - One change at a time
+    - Each step is reversible
+    ↓
+4. Execute step
+    - Apply refactoring technique
+    - Run tests (should still pass)
+    - Commit
+    ↓
+5. Repeat for next smell
+    ↓
+6. Verify final state
+    - Tests pass
+    - Complexity reduced
+    - No behavior change
+```
+
+---
+
+## Code Smell Catalog
+
+| Smell | Symptom | Refactoring Technique |
+|-------|---------|----------------------|
+| **Long Method** | > 20 lines, hard to understand | Extract Method |
+| **Large Class** | > 200 lines, too many responsibilities | Extract Class |
+| **Long Parameter List** | > 3 parameters | Introduce Parameter Object |
+| **Duplicate Code** | Same logic in multiple places | Extract Method, Pull Up Method |
+| **Switch Statement** | Type-based switching | Replace with Polymorphism |
+| **Feature Envy** | Method uses more of another class | Move Method |
+| **Data Class** | Class with only getters/setters | Encapsulate Field, Move Method |
+| **Shotgun Surgery** | One change requires many edits | Move Method, Inline Class |
+| **Divergent Change** | One class changed for many reasons | Extract Class |
+| **Primitive Obsession** | Using primitives instead of objects | Replace Data Value with Object |
+| **Message Chains** | a.b.c.d().e() | Hide Delegate |
+| **Middle Man** | Class that delegates everything | Remove Middle Man |
+
+---
+
+## Refactoring Techniques
+
+### Extract Method
+
+```
+Before:
+function printInvoice() {
+    printBanner();
+    let total = calculateTotal();
+    print("Total: " + total);
+    print("Due: " + getDueDate());
+    print("Customer: " + getCustomer());
+    saveToHistory(total);
+}
+
+After:
+function printInvoice() {
+    printBanner();
+    let total = calculateTotal();
+    printDetails(total);
+    saveToHistory(total);
+}
+
+function printDetails(total: number) {
+    print("Total: " + total);
+    print("Due: " + getDueDate());
+    print("Customer: " + getCustomer());
+}
+```
+
+### Replace with Polymorphism
+
+```
+Before:
+function calculateDiscount(type: string, amount: number) {
+    if (type === "regular") return amount * 0.05;
+    if (type === "premium") return amount * 0.10;
+    if (type === "vip") return amount * 0.20;
+    return 0;
+}
+
+After:
+interface DiscountStrategy {
+    calculate(amount: number): number;
+}
+
+class RegularDiscount implements DiscountStrategy {
+    calculate(amount: number) { return amount * 0.05; }
+}
+
+class PremiumDiscount implements DiscountStrategy {
+    calculate(amount: number) { return amount * 0.10; }
+}
+```
+
+### Introduce Parameter Object
+
+```
+Before:
+function createUser(name: string, email: string, age: number, country: string) { ... }
+
+After:
+type UserData = { name: string; email: string; age: number; country: string; }
+function createUser(data: UserData) { ... }
+```
+
+---
+
+## Safety Checklist
+
+Before every refactoring step:
+
+- [ ] Tests exist for the code being changed
+- [ ] All tests pass currently (green)
+- [ ] I understand what the code does (behavior is known)
+- [ ] The change is small (1 technique at a time)
+- [ ] The change is reversible (can undo)
+- [ ] Only structure changes — no behavior changes
+- [ ] No feature additions during refactoring
+
+---
+
+## Refactoring Plan Template
+
+```yaml
+refactoring_plan:
+  target: "app/Services/OrderService.php"
+  current_complexity: 28 (high)
+  target_complexity: 12 (low)
+  
+  steps:
+    - step: 1
+      technique: "Extract Method"
+      target: "calculateTotals() (47 lines)"
+      into: ["applyDiscount()", "calculateTax()", "calculateShipping()"]
+      risk: "low"
+      test_coverage: "yes"
+      
+    - step: 2
+      technique: "Extract Class"
+      target: "OrderService handles validation, pricing, and notification"
+      into: ["OrderValidator", "OrderPricing", "OrderNotification"]
+      risk: "medium"
+      test_coverage: "partial — add before refactoring"
+      
+    - step: 3
+      technique: "Replace Conditional with Polymorphism"
+      target: "switch (order.type) in discount calculation"
+      into: "DiscountStrategy interface + implementations"
+      risk: "medium"
+      test_coverage: "yes"
+  
+  estimated_time: "2 hours"
+  safety_nets:
+    - "Write failing test first (characterization test)"
+    - "Commit after each step"
+    - "All tests must pass before next step"
+```
+
+---
+
+## Rules
+
+### Always
+
+- ✅ Ensure tests exist before refactoring.
+- ✅ Make one change at a time.
+- ✅ Run tests after every change.
+- ✅ Leave the code cleaner than you found it.
+- ✅ Prefer small, safe refactorings over big rewrites.
+
+### Never
+
+- ❌ Refactor without test coverage (write characterization tests first).
+- ❌ Add new features during refactoring.
+- ❌ Refactor and fix bugs in the same change.
+- ❌ Make large, unreviewable refactoring PRs.
+- ❌ Refactor code that is being deprecated or removed.
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Complexity reduction | ≥ 40% | Before/after cyclomatic complexity |
+| Test coverage after refactor | ≥ before | Coverage report |
+| Bugs introduced | 0 | Post-refactor bug count |
+| Code smells eliminated | ≥ 80% | Smells found vs resolved |
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- 12 code smells with refactoring techniques
+- 3 refactoring techniques with before/after (Extract Method, Polymorphism, Parameter Object)
+- Safety checklist (7 items)
+- Workflow with characterization tests
+- Refactoring plan template in YAML
+- "One change at a time" enforced

package/skills/release-planner.md

@@ -0,0 +1,70 @@
+# Skill: Release Planner
+
+> Version 1.0.0 | Priority: Medium
+> Dependencies: Project Manager, Breaking Change Detector
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Release Planner manages version bumps, changelog generation, release branches, and deployment coordination.
+
+---
+
+## Version Bump Rules
+
+```yaml
+major: breaking changes (API contract, DB schema, public API)
+  format: "1.0.0 → 2.0.0"
+  branch: "release/2.0.0"
+  action: "Includes migration guide, sunset headers"
+
+minor: new features, backward compatible
+  format: "1.0.0 → 1.1.0"
+  branch: "release/1.1.0"
+  action: "Add deprecation notices for old APIs"
+
+patch: bug fixes, no new features
+  format: "1.0.0 → 1.0.1"
+  branch: "main (direct commit/tag)"
+  action: "Urgent: hotfix branch"
+```
+
+---
+
+## Release Checklist
+
+- [ ] All tests pass (CI green)
+- [ ] Changelog.md updated
+- [ ] Version bumped in config/app.php or package.json
+- [ ] Migration scripts tested (up + down)
+- [ ] Breaking changes documented in release notes
+- [ ] Deployment playbook reviewed
+- [ ] Rollback plan confirmed
+- [ ] Stakeholders notified
+
+---
+
+## Changelog Entry
+
+```markdown
+## [1.2.0] — 2026-07-17
+
+### Added
+- Payment integration with Stripe
+- Email notifications for payment confirmation
+
+### Changed
+- Upgrade Laravel from 10 to 11
+
+### Fixed
+- N+1 query on posts listing (#142)
+- Null email handling in login (#138)
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Version rules, checklist, changelog format.

package/skills/requirement-analyzer.md

@@ -0,0 +1,65 @@
+# Skill: Requirement Analyzer
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Software Architect
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Requirement Analyzer extracts, clarifies, and structures requirements from natural language input. Identifies functional and non-functional requirements, constraints, assumptions, and open questions.
+
+---
+
+## Extraction Process
+
+```
+1. Parse input → extract explicit requirements
+2. Ask clarifying questions for ambiguities
+3. Categorize: functional vs non-functional
+4. Prioritize: must-have vs nice-to-have
+5. Identify constraints (time, budget, tech)
+6. Document open questions
+7. Output structured requirements document
+```
+
+---
+
+## Requirement Format
+
+```yaml
+requirements:
+  functional:
+    - id: F1
+      title: "User registration"
+      description: "Users can register with email and password"
+      priority: "must-have"
+      acceptance: "POST /api/v1/users returns 201 with valid data"
+    
+    - id: F2
+      title: "Email verification"
+      description: "Users must verify email before accessing dashboard"
+      priority: "must-have"
+      acceptance: "Unverified users get 403 on dashboard"
+  
+  non_functional:
+    - id: NF1
+      title: "Response time"
+      description: "API p95 response under 200ms"
+      priority: "must-have"
+    
+  constraints:
+    - "Laravel 11 + PostgreSQL 16"
+    - "Delivery in 4 weeks"
+  
+  open_questions:
+    - "Should we support social login (Google, GitHub)?"
+    - "Password policy: minimum length?"
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Extraction, categorization, format.

package/skills/risk-analyzer.md

@@ -0,0 +1,73 @@
+# Skill: Risk Analyzer
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Requirement Analyzer, Software Architect
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Risk Analyzer identifies, assesses, and mitigates project and technical risks before they materialize.
+
+---
+
+## Risk Assessment Matrix
+
+```yaml
+probability:
+  rare: 1 (unlikely)
+  unlikely: 2
+  possible: 3
+  likely: 4
+  almost_certain: 5
+
+impact:
+  negligible: 1
+  minor: 2
+  moderate: 3
+  major: 4
+  catastrophic: 5
+
+risk_score: probability × impact
+
+thresholds:
+  critical: 20-25 → requires immediate mitigation
+  high: 15-19 → requires mitigation plan
+  medium: 10-14 → monitor monthly
+  low: 1-9 → accept
+```
+
+---
+
+## Risk Register
+
+```yaml
+risks:
+  - id: R1
+    title: "Third-party payment API downtime"
+    probability: unlikely (2)
+    impact: major (4)
+    score: 8 (medium)
+    mitigation: "Queue failed payments with retry + fallback"
+    
+  - id: R2
+    title: "Key developer leaves mid-project"
+    probability: possible (3)
+    impact: major (4)
+    score: 12 (medium)
+    mitigation: "Cross-training, documentation, no bus factor = 1"
+    
+  - id: R3
+    title: "Database migration causes data loss"
+    probability: unlikely (2)
+    impact: catastrophic (5)
+    score: 10 (medium)
+    mitigation: "Staging restore test before production, backup verified"
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Matrix, thresholds, register.

package/skills/root-cause-analyzer.md

@@ -0,0 +1,210 @@
+# Skill: Root Cause Analyzer
+
+> Version 1.0.0
+> Priority: High
+> Dependencies: Bug Hunter
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+The Root Cause Analyzer goes beyond the immediate bug to find the systemic reason it exists. It applies techniques like 5 Whys, Fishbone Diagram, and Premortem to identify process gaps, assumptions, and systemic weaknesses that allowed the bug to exist.
+
+---
+
+## Goals
+
+- Identify the systemic root cause, not just the code-level cause.
+- Distinguish between proximate cause and root cause.
+- Recommend process changes to prevent recurrence.
+- Identify patterns across multiple bugs.
+- Feed findings into the Evolution Engine.
+
+---
+
+## Triggers
+
+| Condition | Action |
+|-----------|--------|
+| After Bug Hunter completes | Full root cause analysis |
+| Same bug appears twice | Systemic pattern analysis |
+| Bug was introduced by a previous fix | Regression analysis |
+| Critical or security bug | Root cause + process recommendation |
+
+---
+
+## Techniques
+
+### 5 Whys
+
+```
+Bug: "Login returns 500 error on invalid email"
+
+Why 1: "Str::contains() throws TypeError on null input in Laravel 11"
+Why 2: "The email variable is null because validation happens after the check"
+Why 3: "The developer assumed validation would run before the service layer"
+Why 4: "No explicit contract between controller and service about input state"
+Why 5: "No team convention on where null checks should live"
+
+Root cause: Missing architectural convention for input validation boundaries.
+Fix: Adopt convention: validate at controller boundary, assert at service boundary.
+```
+
+### Fishbone (Cause and Effect)
+
+```
+Effect: Login 500 error on invalid email
+
+Categories → Causes:
+People      | Assumed validation always runs first
+Process     | No code review checklist for type safety
+Technology  | Laravel 11 changed Str::contains() behavior
+Environment | PHP 8.2 strict_types mode
+Measurement | No test coverage for edge case inputs
+
+Root cause: Multiple factors — no type safety checklist, missed behavior change,
+no edge case tests. System-level vulnerability, not individual mistake.
+```
+
+### Premortem
+
+```
+Scenario: "We deploy the fix. 3 months later, we discover..."
+
+What could go wrong?
+1. The null check pattern isn't applied consistently
+2. Other Str:: methods also changed behavior
+3. Developers in other teams make the same assumption
+4. The fix works but the underlying pattern repeats elsewhere
+
+Prevention:
+1. Run codemod to add null checks everywhere
+2. Audit all Str:: usages in the codebase
+3. Share findings in team tech talk
+4. Add to PR review checklist
+```
+
+---
+
+## Root Cause Categories
+
+| Category | Examples | Systemic Fix |
+|----------|----------|-------------|
+| **Knowledge Gap** | Didn't know the framework change | Update onboarding, share in team chat |
+| **Process Gap** | No code review requirement for migrations | Update PR template |
+| **Convention Gap** | No standard for null handling | Create ADR, add to style guide |
+| **Testing Gap** | No edge case tests | Add test template, coverage requirements |
+| **Communication Gap** | Team didn't know about the upgrade | Add upgrade notice channel, changelog bot |
+| **Tooling Gap** | No static analysis for type safety | Add PHPStan at max level |
+| **Assumption** | Assumed input is always valid | Document service contracts explicitly |
+
+---
+
+## Pattern Detection
+
+The engine tracks root causes across multiple bugs to find patterns:
+
+```yaml
+patterns:
+  - pattern_id: "p-001"
+    category: "testing_gap"
+    description: "Edge case inputs not tested"
+    count: 4
+    last_bug: "2026-07-17"
+    recommendation: "Add fuzz testing to CI pipeline"
+    
+  - pattern_id: "p-002"
+    category: "knowledge_gap"
+    description: "Laravel upgrade behavior changes unknown"
+    count: 2
+    last_bug: "2026-07-15"
+    recommendation: "Add automated changelog analysis to upgrade process"
+```
+
+---
+
+## Root Cause Report
+
+```yaml
+root_cause_analysis:
+  bug_title: "Login returns 500 error on invalid email"
+  
+  proximate_cause:
+    what: "Str::contains() throws TypeError on null"
+    where: "app/Services/LoginService.php:45"
+    
+  root_cause:
+    what: "No convention on where input validation boundaries are enforced"
+    category: "convention_gap"
+    
+    5_whys:
+      - "Str::contains() throws TypeError on null in Laravel 11"
+      - "Email is null because validation ran inside controller but service received raw request"
+      - "Developer assumed controller validated before service call"
+      - "No explicit contract between controller and service about validated state"
+      - "No team convention on validation boundaries"
+    
+  systemic_recommendations:
+    - priority: 1
+      action: "Create ADR: validation boundaries convention"
+      owner: "Tech Lead"
+      deadline: "2026-07-24"
+      
+    - priority: 2
+      action: "Add null check rule to PHPStan config"
+      owner: "DevOps"
+      deadline: "2026-07-21"
+      
+    - priority: 3
+      action: "Audit all Str:: usages for null safety"
+      owner: "Backend Team"
+      deadline: "2026-07-28"
+    
+  evolution_feed:
+    skill: "security-engineer"
+    suggestion: "Add null safety check to code review checklist"
+```
+
+---
+
+## Rules
+
+### Always
+
+- ✅ Ask "why" at least 5 times.
+- ✅ Distinguish proximate cause from root cause.
+- ✅ Categorize root cause (knowledge, process, convention, testing, etc.).
+- ✅ Recommend systemic fixes, not just code fixes.
+- ✅ Feed patterns into Evolution Engine.
+
+### Never
+
+- ❌ Stop at the first "why".
+- ❌ Blame individuals for systemic issues.
+- ❌ Suggest only code fixes without process recommendations.
+- ❌ Ignore patterns — if it happened twice, it'll happen again.
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Root cause depth | ≥ 5 whys | Average depth per analysis |
+| Systemic fix rate | ≥ 50% | Systemic fixes / total recommendations |
+| Pattern detection rate | ≥ 80% | Patterns found / patterns present |
+| Bug recurrence after analysis | ≤ 2% | Same bug reappearing after RCA |
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- 3 root cause techniques: 5 Whys, Fishbone, Premortem
+- 7 root cause categories with systemic fixes
+- Pattern detection across multiple bugs
+- Root cause report in YAML
+- Systemic recommendation engine