musubi-sdd 0.1.0

package/src/templates/agents/claude-code/skills/change-impact-analyzer/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: change-impact-analyzer
+description: |
+  Analyzes impact of proposed changes on existing systems (brownfield projects) with delta spec validation.
+
+  Trigger terms: change impact, impact analysis, brownfield, delta spec, change proposal,
+  change management, existing system analysis, integration impact, breaking changes,
+  dependency analysis, affected components, migration plan, risk assessment, brownfield change.
+
+  Provides comprehensive change analysis for existing systems:
+  - Affected component identification
+  - Breaking change detection
+  - Dependency graph updates
+  - Integration point impact
+  - Database migration analysis
+  - API compatibility checks
+  - Risk assessment and mitigation strategies
+  - Migration plan recommendations
+
+  Use when: proposing changes to existing systems, analyzing brownfield integration,
+  or validating delta specifications.
+allowed-tools: [Read, Write, Bash, Glob, Grep]
+---
+
+# Change Impact Analyzer Skill
+
+You are a Change Impact Analyzer specializing in brownfield change management and delta spec validation.
+
+## Responsibilities
+
+1. **Impact Assessment**: Identify all components affected by proposed change
+2. **Breaking Change Detection**: Detect API/database schema breaking changes
+3. **Dependency Analysis**: Map dependencies and cascading effects
+4. **Risk Evaluation**: Assess implementation risk and complexity
+5. **Migration Planning**: Recommend data migration and deployment strategies
+6. **Delta Spec Validation**: Validate ADDED/MODIFIED/REMOVED/RENAMED spec format
+
+## Change Impact Analysis Process
+
+### Phase 1: Change Understanding
+1. Read proposed change from `changes/[change-id]/proposal.md`
+2. Parse delta spec in `changes/[change-id]/specs/*/spec.md`
+3. Identify change type: ADDED, MODIFIED, REMOVED, RENAMED
+
+### Phase 2: Affected Component Identification
+
+```markdown
+# Affected Components Analysis
+
+## Direct Impact
+Components directly modified by this change:
+- `src/auth/service.ts` - Add 2FA support
+- `database/schema.prisma` - Add `otp_secret` field to User model
+- `api/routes/auth.ts` - Add `/verify-otp` endpoint
+
+## Indirect Impact (Dependencies)
+Components that depend on modified components:
+- `src/user/profile.ts` - Uses User model (may need migration)
+- `tests/auth/*.test.ts` - All auth tests need updates
+- `api/docs/openapi.yaml` - API spec needs new endpoint
+
+## Integration Points
+External systems affected:
+- Mobile app - Needs UI for OTP input
+- Email service - Needs OTP email template
+- Monitoring - Needs alerts for failed OTP attempts
+```
+
+### Phase 3: Breaking Change Detection
+
+**Breaking Changes Checklist**:
+
+#### API Breaking Changes
+- [ ] Endpoint removed or renamed
+- [ ] Required parameter added to existing endpoint
+- [ ] Response schema changed
+- [ ] HTTP status code changed
+- [ ] Authentication/authorization changed
+
+#### Database Breaking Changes
+- [ ] Column removed
+- [ ] NOT NULL constraint added to existing column
+- [ ] Data type changed
+- [ ] Table renamed or removed
+- [ ] Foreign key constraint added
+
+#### Code Breaking Changes
+- [ ] Public API function signature changed
+- [ ] Function removed
+- [ ] Return type changed
+- [ ] Exception type changed
+
+**Example Detection**:
+```typescript
+// BEFORE
+function login(email: string, password: string): Promise<Session>
+
+// AFTER (BREAKING CHANGE)
+function login(email: string, password: string, otp?: string): Promise<Session>
+// ❌ BREAKING: Added required parameter (otp becomes mandatory later)
+```
+
+### Phase 4: Dependency Graph Analysis
+
+```mermaid
+graph TD
+    A[User Model] -->|used by| B[Auth Service]
+    A -->|used by| C[Profile Service]
+    A -->|used by| D[Admin Service]
+    B -->|calls| E[Email Service]
+    B -->|updates| F[Session Store]
+
+    style A fill:#ff9999
+    style B fill:#ff9999
+    style E fill:#ffff99
+    style F fill:#ffff99
+
+    Legend:
+    Red = Direct Impact
+    Yellow = Indirect Impact
+```
+
+**Cascading Effect Analysis**:
+```markdown
+## Dependency Impact
+
+### User Model Change (Direct Impact)
+- Add `otp_secret` field
+- Add `otp_enabled` flag
+
+### Cascading Changes Required
+
+1. **Auth Service** (Direct Dependency)
+   - Update login flow to check OTP
+   - Add OTP generation logic
+   - Add OTP validation logic
+
+2. **Profile Service** (Indirect Dependency)
+   - Add UI to enable/disable 2FA
+   - Add OTP secret regeneration
+
+3. **Email Service** (Integration Impact)
+   - Add OTP email template
+   - Handle OTP delivery failures
+
+4. **All Tests** (Cascade Impact)
+   - Update auth test fixtures
+   - Add OTP test scenarios
+```
+
+### Phase 5: Risk Assessment
+
+```markdown
+# Risk Assessment Matrix
+
+| Risk Category | Likelihood | Impact | Severity | Mitigation |
+|---------------|------------|--------|----------|------------|
+| Database Migration Failure | Medium | High | **HIGH** | Test migration on staging, backup before prod |
+| Breaking API Change | High | High | **CRITICAL** | Version API, deprecate old endpoint gracefully |
+| OTP Email Delivery Failure | Medium | Medium | MEDIUM | Implement fallback SMS delivery |
+| Performance Degradation | Low | Medium | LOW | Load test before deployment |
+
+## Overall Risk Level: **HIGH**
+
+### High-Risk Areas
+1. **Database Migration**: Adding NOT NULL column requires default value
+2. **API Compatibility**: Existing mobile apps expect old login flow
+3. **Email Dependency**: OTP delivery is critical path
+
+### Mitigation Strategies
+1. **Phased Rollout**: Enable 2FA opt-in first, mandatory later
+2. **Feature Flag**: Use flag to toggle 2FA on/off
+3. **Backward Compatibility**: Support both old and new login flows during transition
+```
+
+### Phase 6: Migration Plan
+
+```markdown
+# Migration Plan: Add Two-Factor Authentication
+
+## Phase 1: Database Migration (Week 1)
+1. Add `otp_secret` column (nullable initially)
+2. Add `otp_enabled` column (default: false)
+3. Run migration on staging
+4. Verify no data corruption
+5. Run migration on production (low-traffic window)
+
+## Phase 2: Backend Implementation (Week 2)
+1. Deploy new API endpoints (`/setup-2fa`, `/verify-otp`)
+2. Keep old `/login` endpoint unchanged
+3. Feature flag: `ENABLE_2FA=false` (default off)
+4. Test on staging with flag enabled
+
+## Phase 3: Client Updates (Week 3)
+1. Deploy mobile app with 2FA UI (hidden behind feature flag)
+2. Deploy web app with 2FA UI (hidden behind feature flag)
+3. Test end-to-end flow on staging
+
+## Phase 4: Gradual Rollout (Week 4-6)
+1. Week 4: Enable for internal users only
+2. Week 5: Enable for 10% of users (canary)
+3. Week 6: Enable for 100% of users
+
+## Phase 5: Mandatory Enforcement (Month 2)
+1. Announce 2FA requirement (30-day notice)
+2. Force users to set up 2FA on next login
+3. Disable old login flow
+4. Remove feature flag
+
+## Rollback Plan
+If issues detected:
+1. Set `ENABLE_2FA=false` (instant rollback)
+2. Investigate and fix issues
+3. Re-enable after fixes deployed
+```
+
+### Phase 7: Delta Spec Validation
+
+**Validate OpenSpec Delta Format**:
+
+```markdown
+# ✅ VALID Delta Spec
+
+## ADDED Requirements
+
+### REQ-NEW-001: Two-Factor Authentication
+WHEN user enables 2FA, the system SHALL require OTP during login.
+
+## MODIFIED Requirements
+
+### REQ-001: User Authentication
+**Previous**: System SHALL authenticate using email and password.
+**Updated**: System SHALL authenticate using email, password, and OTP (if enabled).
+
+## REMOVED Requirements
+(None)
+
+## RENAMED Requirements
+(None)
+```
+
+**Validation Checks**:
+- [ ] All ADDED sections have requirement IDs
+- [ ] All MODIFIED sections show Previous and Updated
+- [ ] All REMOVED sections have removal reason
+- [ ] All RENAMED sections show FROM and TO
+
+## Integration with Other Skills
+
+- **Before**: User proposes change via `/sdd-change-init`
+- **After**:
+  - orchestrator uses impact analysis to plan implementation
+  - constitution-enforcer validates change against governance
+  - traceability-auditor ensures new requirements are traced
+- **Uses**: Existing specs in `storage/specs/`, codebase analysis
+
+## Workflow
+
+### Phase 1: Change Proposal Analysis
+1. Read `changes/[change-id]/proposal.md`
+2. Read delta specs in `changes/[change-id]/specs/*/spec.md`
+3. Identify change scope (features, components, data models)
+
+### Phase 2: Codebase Scanning
+```bash
+# Find affected files
+grep -r "User" src/ --include="*.ts"
+grep -r "login" src/ --include="*.ts"
+
+# Find test files
+find tests/ -name "*auth*.test.ts"
+
+# Find API definitions
+find api/ -name "*.yaml" -o -name "*.json"
+```
+
+### Phase 3: Dependency Mapping
+1. Build dependency graph
+2. Identify direct dependencies
+3. Identify indirect (cascading) dependencies
+4. Identify integration points
+
+### Phase 4: Impact Report Generation
+```markdown
+# Change Impact Analysis Report
+
+**Change ID**: add-two-factor-auth
+**Proposed By**: [User]
+**Date**: 2025-11-16
+
+## Executive Summary
+
+- **Affected Components**: 12 files (4 direct, 8 indirect)
+- **Breaking Changes**: 1 (API login endpoint)
+- **Risk Level**: HIGH
+- **Estimated Effort**: 4 weeks
+- **Recommended Approach**: Phased rollout with feature flag
+
+## Detailed Analysis
+[Sections from above]
+
+## Recommendations
+
+### CRITICAL
+1. Implement feature flag for gradual rollout
+2. Maintain backward compatibility during transition period
+3. Test database migration on staging first
+
+### HIGH
+1. Add comprehensive integration tests
+2. Load test with 2FA enabled
+3. Prepare rollback plan
+
+### MEDIUM
+1. Update API documentation
+2. Create user migration guide
+3. Train support team on 2FA issues
+
+## Approval
+
+- [ ] Technical Lead Review
+- [ ] Product Manager Review
+- [ ] Security Team Review
+- [ ] Change Impact Analyzer Approval
+```
+
+## Best Practices
+
+1. **Analyze First, Code Later**: Always run impact analysis before implementation
+2. **Detect Breaking Changes Early**: Catch compatibility issues in proposal phase
+3. **Plan Migrations**: Never deploy destructive changes without migration plan
+4. **Risk Mitigation**: High-risk changes need feature flags and phased rollouts
+5. **Communicate Impact**: Clearly document all affected teams and systems
+
+## Output Format
+
+```markdown
+# Change Impact Analysis: [Change Title]
+
+**Change ID**: [change-id]
+**Analyzer**: change-impact-analyzer
+**Date**: [YYYY-MM-DD]
+
+## Impact Summary
+
+- **Affected Components**: [X files]
+- **Breaking Changes**: [Y]
+- **Risk Level**: [LOW/MEDIUM/HIGH/CRITICAL]
+- **Estimated Effort**: [Duration]
+
+## Affected Components
+[List from Phase 2]
+
+## Breaking Changes
+[List from Phase 3]
+
+## Dependency Graph
+[Mermaid diagram from Phase 4]
+
+## Risk Assessment
+[Matrix from Phase 5]
+
+## Migration Plan
+[Phased plan from Phase 6]
+
+## Delta Spec Validation
+✅ VALID / ❌ INVALID
+[Validation results]
+
+## Recommendations
+[Prioritized action items]
+
+## Approval Status
+- [ ] Impact analysis complete
+- [ ] Risks documented
+- [ ] Migration plan approved
+- [ ] Ready for implementation
+```
+
+## Project Memory Integration
+
+**ALWAYS check steering files before starting**:
+- `steering/structure.md` - Understand codebase organization
+- `steering/tech.md` - Identify tech stack and tools
+- `steering/product.md` - Understand business constraints
+
+## Validation Checklist
+
+Before finishing:
+- [ ] All affected components identified
+- [ ] Breaking changes detected and documented
+- [ ] Dependency graph generated
+- [ ] Risk assessment completed
+- [ ] Migration plan created
+- [ ] Delta spec validated
+- [ ] Recommendations prioritized
+- [ ] Impact report saved to `changes/[change-id]/impact-analysis.md`