@wipal/agent-team 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/.claude/rules/common/general-rules.md +141 -0
  2. package/.claude/rules/lessons/lessons.md +91 -0
  3. package/.claude/rules/role-rules/dev-fe-rules.md +146 -0
  4. package/.claude/rules/role-rules/sa-rules.md +226 -0
  5. package/.claude/skills/SKILL-INDEX.md +299 -0
  6. package/.claude/skills/community/security-validator/SKILL.md +392 -0
  7. package/.claude/skills/core/agent-creation/SKILL.md +338 -0
  8. package/.claude/skills/core/code-review/SKILL.md +154 -0
  9. package/.claude/skills/core/git-automation/SKILL.md +93 -0
  10. package/.claude/skills/core/retrospect-work/SKILL.md +172 -0
  11. package/.claude/skills/domain/architecture/adr-writing/SKILL.md +254 -0
  12. package/.claude/skills/domain/architecture/adr-writing/references/adr-best-practices.md +257 -0
  13. package/.claude/skills/domain/architecture/adr-writing/references/adr-examples.md +246 -0
  14. package/.claude/skills/domain/architecture/adr-writing/references/adr-template.md +160 -0
  15. package/.claude/skills/domain/architecture/architecture-patterns/SKILL.md +316 -0
  16. package/.claude/skills/domain/architecture/architecture-patterns/references/event-driven.md +393 -0
  17. package/.claude/skills/domain/architecture/architecture-patterns/references/microservices.md +315 -0
  18. package/.claude/skills/domain/architecture/architecture-patterns/references/monolith.md +321 -0
  19. package/.claude/skills/domain/architecture/architecture-patterns/references/serverless.md +457 -0
  20. package/.claude/skills/domain/architecture/performance-engineering/SKILL.md +227 -0
  21. package/.claude/skills/domain/architecture/performance-engineering/references/benchmarking.md +336 -0
  22. package/.claude/skills/domain/architecture/performance-engineering/references/caching-strategies.md +284 -0
  23. package/.claude/skills/domain/architecture/performance-engineering/references/optimization.md +298 -0
  24. package/.claude/skills/domain/architecture/security-architecture/SKILL.md +206 -0
  25. package/.claude/skills/domain/architecture/security-architecture/references/auth-patterns.md +209 -0
  26. package/.claude/skills/domain/architecture/security-architecture/references/compliance.md +246 -0
  27. package/.claude/skills/domain/architecture/security-architecture/references/threat-modeling.md +219 -0
  28. package/.claude/skills/domain/architecture/system-design/SKILL.md +227 -0
  29. package/.claude/skills/domain/architecture/system-design/references/distributed-systems.md +231 -0
  30. package/.claude/skills/domain/architecture/system-design/references/resilience.md +344 -0
  31. package/.claude/skills/domain/architecture/system-design/references/scalability.md +303 -0
  32. package/.claude/skills/domain/architecture/tech-selection/SKILL.md +192 -0
  33. package/.claude/skills/domain/architecture/tech-selection/references/build-vs-buy.md +258 -0
  34. package/.claude/skills/domain/architecture/tech-selection/references/evaluation-framework.md +203 -0
  35. package/.claude/skills/domain/architecture/tech-selection/references/tech-radar.md +257 -0
  36. package/.claude/skills/domain/backend/api-design/SKILL.md +121 -0
  37. package/.claude/skills/domain/backend/database-design/SKILL.md +156 -0
  38. package/.claude/skills/domain/backend/performance-be/SKILL.md +210 -0
  39. package/.claude/skills/domain/backend/security/SKILL.md +138 -0
  40. package/.claude/skills/domain/backend/testing-be/SKILL.md +203 -0
  41. package/.claude/skills/domain/devops/ci-cd/SKILL.md +188 -0
  42. package/.claude/skills/domain/devops/containerization/SKILL.md +177 -0
  43. package/.claude/skills/domain/devops/deployment/SKILL.md +198 -0
  44. package/.claude/skills/domain/devops/infrastructure-as-code/SKILL.md +178 -0
  45. package/.claude/skills/domain/devops/monitoring/SKILL.md +163 -0
  46. package/.claude/skills/domain/frontend/accessibility/SKILL.md +179 -0
  47. package/.claude/skills/domain/frontend/frontend-design/SKILL.md +138 -0
  48. package/.claude/skills/domain/frontend/performance-fe/SKILL.md +195 -0
  49. package/.claude/skills/domain/frontend/state-management/SKILL.md +190 -0
  50. package/.claude/skills/domain/frontend/testing-fe/SKILL.md +193 -0
  51. package/.claude/skills/domain/product/requirements-gathering/SKILL.md +136 -0
  52. package/.claude/skills/domain/product/roadmap-planning/SKILL.md +169 -0
  53. package/.claude/skills/domain/product/sprint-planning/SKILL.md +151 -0
  54. package/.claude/skills/domain/product/stakeholder-communication/SKILL.md +162 -0
  55. package/.claude/skills/domain/product/user-stories/SKILL.md +141 -0
  56. package/.claude/skills/domain/quality/bug-reporting/SKILL.md +150 -0
  57. package/.claude/skills/domain/quality/regression-testing/SKILL.md +178 -0
  58. package/.claude/skills/domain/quality/test-automation/SKILL.md +185 -0
  59. package/.claude/skills/domain/quality/test-planning/SKILL.md +177 -0
  60. package/.claude/skills/leadership/code-review-advanced/SKILL.md +167 -0
  61. package/.claude/skills/leadership/mentoring/SKILL.md +151 -0
  62. package/.claude/skills/leadership/technical-debt/SKILL.md +166 -0
  63. package/.claude/skills/leadership/technical-decision/SKILL.md +160 -0
  64. package/.claude/skills/security-reports/.gitkeep +0 -0
  65. package/.claude/skills/skills-registry.yaml +441 -0
  66. package/README.md +232 -0
  67. package/bin/agent-team.js +107 -0
  68. package/package.json +51 -0
  69. package/src/commands/add.js +227 -0
  70. package/src/commands/init.js +136 -0
  71. package/src/commands/list.js +66 -0
  72. package/src/commands/remove.js +71 -0
  73. package/src/commands/switch.js +53 -0
  74. package/src/index.js +11 -0
  75. package/src/interactive/prompts.js +153 -0
  76. package/src/server/api/agents.js +150 -0
  77. package/src/server/api/roles.js +97 -0
  78. package/src/server/api/skills.js +79 -0
  79. package/src/server/index.js +78 -0
  80. package/src/ui/agents.html +174 -0
  81. package/src/ui/css/styles.css +470 -0
  82. package/src/ui/index.html +107 -0
  83. package/src/ui/roles.html +371 -0
  84. package/src/ui/skills.html +332 -0
  85. package/src/utils/file-utils.js +193 -0
  86. package/src/utils/skill-resolver.js +594 -0
  87. package/src/utils/skill-scanner.js +154 -0
  88. package/templates/CLAUDE.md.tmpl +42 -0
  89. package/templates/knowledge.md.tmpl +31 -0
@@ -0,0 +1,177 @@
1
+ ---
2
+ name: test-planning
3
+ description: |
4
+ Test strategy and planning for comprehensive quality assurance. Use when:
5
+ creating test plans, defining test strategy, planning test coverage, or when
6
+ user mentions "test plan", "test strategy", "QA plan", "coverage".
7
+ version: 1.0.0
8
+ category: quality
9
+ tags:
10
+ - test-planning
11
+ - qa
12
+ - strategy
13
+ - coverage
14
+ depends_on: []
15
+ recommends:
16
+ - test-automation
17
+ used_by:
18
+ - regression-testing
19
+ ---
20
+
21
+ # Skill: Test Planning
22
+
23
+ ## Core Principle
24
+ **Test early, test often, test smart.** Quality is built in, not tested in.
25
+
26
+ ## Testing Pyramid
27
+
28
+ ```
29
+
30
+ /E2E\ 10% - Slow, expensive
31
+ /─────\
32
+ / API \ 20% - Integration
33
+ /─────────\
34
+ / Unit \ 70% - Fast, cheap
35
+ /─────────────\
36
+ ```
37
+
38
+ ## Hard Rules
39
+
40
+ 1. **NEVER test everything manually** - Automate what makes sense
41
+ 2. **NEVER skip edge cases** - That's where bugs hide
42
+ 3. **ALWAYS define acceptance criteria first** - Know what "done" means
43
+ 4. **ALWAYS prioritize by risk** - High-risk areas need more testing
44
+
45
+ ## Test Plan Template
46
+
47
+ ```markdown
48
+ # Test Plan: [Feature/Release Name]
49
+
50
+ ## 1. Overview
51
+ - **Feature:** User authentication
52
+ - **Release:** v2.0
53
+ - **QA Lead:** @name
54
+ - **Timeline:** Sprint 5-6
55
+
56
+ ## 2. Scope
57
+
58
+ ### In Scope
59
+ - Login/logout functionality
60
+ - Password reset
61
+ - Session management
62
+ - OAuth integration
63
+
64
+ ### Out of Scope
65
+ - Biometric auth (Phase 2)
66
+ - Multi-factor auth (Phase 3)
67
+
68
+ ## 3. Test Strategy
69
+
70
+ ### Unit Tests
71
+ - Service layer business logic
72
+ - Input validation
73
+ - Error handling
74
+
75
+ ### Integration Tests
76
+ - API endpoints
77
+ - Database operations
78
+ - External service mocks
79
+
80
+ ### E2E Tests
81
+ - Critical user flows
82
+ - Happy paths only
83
+
84
+ ## 4. Test Cases
85
+
86
+ | ID | Type | Priority | Description |
87
+ |----|------|----------|-------------|
88
+ | AUTH-001 | Unit | High | Validate email format |
89
+ | AUTH-002 | API | High | Login with valid credentials |
90
+ | AUTH-003 | API | High | Login with invalid credentials |
91
+ | AUTH-004 | E2E | Critical | Complete login flow |
92
+
93
+ ## 5. Entry Criteria
94
+ - [ ] Feature development complete
95
+ - [ ] Unit tests passing
96
+ - [ ] Code review approved
97
+ - [ ] Test environment ready
98
+
99
+ ## 6. Exit Criteria
100
+ - [ ] All test cases executed
101
+ - [ ] No critical bugs open
102
+ - [ ] Coverage > 80%
103
+ - [ ] Performance tests passed
104
+
105
+ ## 7. Risks
106
+ | Risk | Likelihood | Mitigation |
107
+ |------|------------|------------|
108
+ | OAuth delay | Medium | Test with mock first |
109
+
110
+ ## 8. Resources
111
+ - QA: 2 engineers
112
+ - Duration: 5 days
113
+ - Environment: Staging
114
+ ```
115
+
116
+ ## Test Case Template
117
+
118
+ ```markdown
119
+ # TC-AUTH-001: Login with valid credentials
120
+
121
+ ## Metadata
122
+ - **Priority:** Critical
123
+ - **Type:** Functional
124
+ - **Automation:** Yes
125
+
126
+ ## Pre-conditions
127
+ - User account exists
128
+ - User is not logged in
129
+
130
+ ## Test Steps
131
+ 1. Navigate to login page
132
+ 2. Enter valid email
133
+ 3. Enter valid password
134
+ 4. Click "Login" button
135
+
136
+ ## Expected Result
137
+ - User is redirected to dashboard
138
+ - Session token is set
139
+ - User name displayed in header
140
+
141
+ ## Test Data
142
+ - Email: test@example.com
143
+ - Password: ValidPass123!
144
+
145
+ ## Post-conditions
146
+ - User session created
147
+ - Login timestamp updated
148
+ ```
149
+
150
+ ## Coverage Matrix
151
+
152
+ ```markdown
153
+ | Requirement | Unit | Integration | E2E | Manual |
154
+ |-------------|------|-------------|-----|--------|
155
+ | Login | ✅ | ✅ | ✅ | - |
156
+ | Password | ✅ | ✅ | - | ✅ |
157
+ | OAuth | ✅ | ✅ | ✅ | ✅ |
158
+ | Session | ✅ | ✅ | - | - |
159
+ ```
160
+
161
+ ## Common Mistakes
162
+
163
+ | ❌ Mistake | ✅ Fix |
164
+ |------------|--------|
165
+ | Testing only happy path | Include edge cases |
166
+ | No prioritization | Risk-based testing |
167
+ | No entry/exit criteria | Define clearly |
168
+ | Manual-only testing | Automate wisely |
169
+
170
+ ## Checklist
171
+
172
+ - [ ] Scope defined
173
+ - [ ] Strategy documented
174
+ - [ ] Test cases written
175
+ - [ ] Entry criteria met
176
+ - [ ] Exit criteria defined
177
+ - [ ] Risks identified
@@ -0,0 +1,167 @@
1
+ ---
2
+ name: code-review-advanced
3
+ description: |
4
+ Advanced code review practices for Tech Leads and senior engineers. Use when:
5
+ reviewing architecture changes, mentoring through review, or when user mentions
6
+ "advanced review", "architecture review", "lead review", "senior review".
7
+ version: 1.0.0
8
+ category: leadership
9
+ tags:
10
+ - code-review
11
+ - leadership
12
+ - mentorship
13
+ - architecture
14
+ depends_on:
15
+ - code-review
16
+ recommends:
17
+ - technical-debt
18
+ used_by: []
19
+ ---
20
+
21
+ # Skill: Code Review Advanced
22
+
23
+ ## Core Principle
24
+ **Elevate the team through review.** Every review is a mentoring opportunity.
25
+
26
+ ## Beyond Basic Review
27
+
28
+ | Level | Focus |
29
+ |-------|-------|
30
+ | **Junior** | Correctness, style |
31
+ | **Mid** | Patterns, edge cases |
32
+ | **Senior** | Architecture, maintainability |
33
+ | **Lead** | Team growth, system health |
34
+
35
+ ## Hard Rules
36
+
37
+ 1. **NEVER block without teaching** - Explain the "why"
38
+ 2. **NEVER nitpick style** - Automate with linters
39
+ 3. **ALWAYS consider alternatives** - Is there a better approach?
40
+ 4. **ALWAYS think about future readers** - Code is read 10x more than written
41
+
42
+ ## Review Dimensions
43
+
44
+ ### 1. Correctness
45
+ ```
46
+ - Does it work as intended?
47
+ - Are edge cases handled?
48
+ - Are errors handled properly?
49
+ - Is the logic sound?
50
+ ```
51
+
52
+ ### 2. Architecture
53
+ ```
54
+ - Does it fit the system design?
55
+ - Is the abstraction appropriate?
56
+ - Are dependencies correct?
57
+ - Will it scale?
58
+ ```
59
+
60
+ ### 3. Maintainability
61
+ ```
62
+ - Is it readable?
63
+ - Is it testable?
64
+ - Is it documented where needed?
65
+ - Will it be easy to change?
66
+ ```
67
+
68
+ ### 4. Performance
69
+ ```
70
+ - Are there obvious bottlenecks?
71
+ - Is the algorithm efficient?
72
+ - Are resources managed properly?
73
+ - Is caching used appropriately?
74
+ ```
75
+
76
+ ### 5. Security
77
+ ```
78
+ - Is input validated?
79
+ - Is output sanitized?
80
+ - Are secrets protected?
81
+ - Is access controlled?
82
+ ```
83
+
84
+ ## Feedback Framework
85
+
86
+ ### SBI Model
87
+ ```
88
+ Situation: "In the handleOrder function..."
89
+ Behavior: "You're querying the database inside a loop..."
90
+ Impact: "This will cause N+1 queries under load..."
91
+ ```
92
+
93
+ ### Teaching Through Review
94
+ ```markdown
95
+ // ❌ Blocking comment
96
+ "This is wrong, use a Map instead."
97
+
98
+ // ✅ Teaching comment
99
+ "Consider using a Map here instead of an object.
100
+ Why: Maps have O(1) lookups and preserve insertion order.
101
+ Example:
102
+ ```typescript
103
+ const orderMap = new Map<string, Order>();
104
+ for (const order of orders) {
105
+ orderMap.set(order.id, order);
106
+ }
107
+ ```
108
+ What do you think?"
109
+ ```
110
+
111
+ ## Architecture Review Checklist
112
+
113
+ ```markdown
114
+ ## Design Review
115
+
116
+ ### High-Level
117
+ - [ ] Solution addresses the problem
118
+ - [ ] Alternatives considered
119
+ - [ ] Trade-offs documented
120
+ - [ ] Scalability considered
121
+ - [ ] Security reviewed
122
+
123
+ ### Implementation
124
+ - [ ] Follows existing patterns
125
+ - [ ] Appropriate abstraction level
126
+ - [ ] Testable design
127
+ - [ ] Error handling complete
128
+ - [ ] Logging/monitoring added
129
+
130
+ ### Integration
131
+ - [ ] API contracts clear
132
+ - [ ] Backwards compatible
133
+ - [ ] Migration plan if needed
134
+ - [ ] Documentation updated
135
+ ```
136
+
137
+ ## Review Metrics
138
+
139
+ ```markdown
140
+ ## Team Health Indicators
141
+
142
+ | Metric | Target | Current |
143
+ |--------|--------|---------|
144
+ | Review turnaround | < 4 hours | 2.5 hours |
145
+ | Comments per PR | 3-8 | 5 |
146
+ | PR size | < 400 lines | 280 |
147
+ | Rework rate | < 20% | 15% |
148
+ ```
149
+
150
+ ## Common Mistakes
151
+
152
+ | ❌ Mistake | ✅ Fix |
153
+ |------------|--------|
154
+ | Only finding problems | Acknowledge good patterns |
155
+ | Vague comments | Be specific with examples |
156
+ | Personal tone | Focus on code, not person |
157
+ | Blocking without alternative | Suggest solutions |
158
+ | Reviewing too quickly | Take time to understand |
159
+
160
+ ## Checklist
161
+
162
+ - [ ] Logic verified
163
+ - [ ] Architecture reviewed
164
+ - [ ] Performance considered
165
+ - [ ] Security checked
166
+ - [ ] Mentoring opportunities used
167
+ - [ ] Team patterns followed
@@ -0,0 +1,151 @@
1
+ ---
2
+ name: mentoring
3
+ description: |
4
+ Developer mentoring and coaching techniques for Tech Leads. Use when:
5
+ mentoring team members, career development, skill building, or when user
6
+ mentions "mentor", "coach", "develop", "grow", "career".
7
+ version: 1.0.0
8
+ category: leadership
9
+ tags:
10
+ - mentoring
11
+ - coaching
12
+ - career
13
+ - development
14
+ depends_on: []
15
+ recommends: []
16
+ used_by: []
17
+ ---
18
+
19
+ # Skill: Mentoring
20
+
21
+ ## Core Principle
22
+ **Grow people, not just code.** A mentor's success is measured by their mentees' growth.
23
+
24
+ ## Mentoring Styles
25
+
26
+ | Style | When to Use |
27
+ |-------|-------------|
28
+ | **Directive** | New skills, urgent situations |
29
+ | **Coaching** | Problem-solving, growth |
30
+ | **Supportive** | Building confidence |
31
+ | **Delegating** | Experienced, self-directed |
32
+
33
+ ## Hard Rules
34
+
35
+ 1. **NEVER do the work for them** - Guide, don't solve
36
+ 2. **NEVER assume knowledge** - Ask what they understand
37
+ 3. **ALWAYS give specific feedback** - Not just "good job"
38
+ 4. **ALWAYS follow up** - Check progress regularly
39
+
40
+ ## Growth Framework
41
+
42
+ ### 1:1 Meeting Structure
43
+ ```
44
+ Week 1: Goal setting (15 min)
45
+ - What do you want to learn?
46
+ - Where do you want to grow?
47
+ - What's blocking you?
48
+
49
+ Week 2-3: Progress check (30 min)
50
+ - What did you try?
51
+ - What worked? What didn't?
52
+ - What did you learn?
53
+
54
+ Week 4: Review & adjust (30 min)
55
+ - Progress toward goals?
56
+ - Adjust approach?
57
+ - Next month's focus?
58
+ ```
59
+
60
+ ## Feedback Model
61
+
62
+ ### SBI + Growth
63
+ ```
64
+ Situation: "In yesterday's code review..."
65
+ Behavior: "You explained the trade-offs clearly..."
66
+ Impact: "The team understood why we chose this approach..."
67
+ Growth: "Next time, consider adding a diagram for complex flows..."
68
+ ```
69
+
70
+ ### Radical Candor
71
+ ```
72
+ Care Personally + Challenge Directly = Growth
73
+
74
+ ❌ Ruinous Empathy: Nice but not honest
75
+ ❌ Obnoxious Aggression: Honest but not kind
76
+ ❌ Manipulative Insincerity: Neither honest nor kind
77
+ ✅ Radical Candor: Both honest and kind
78
+ ```
79
+
80
+ ## Career Development
81
+
82
+ ### Skill Matrix
83
+ ```markdown
84
+ | Level | Technical | Leadership | Communication |
85
+ |-------|-----------|------------|---------------|
86
+ | Junior | Learn basics | Follow | Ask questions |
87
+ | Mid | Apply patterns | Collaborate | Explain ideas |
88
+ | Senior | Design systems | Mentor | Influence |
89
+ | Staff | Define direction | Lead teams | Drive change |
90
+ ```
91
+
92
+ ### Growth Plan Template
93
+ ```markdown
94
+ # Growth Plan: [Name]
95
+
96
+ ## Current Level
97
+ - Role: Mid-level Developer
98
+ - Strengths: API design, testing
99
+ - Areas for growth: System design, mentoring
100
+
101
+ ## 6-Month Goals
102
+ 1. Lead design of [feature]
103
+ 2. Mentor 1 junior developer
104
+ 3. Present at team meeting
105
+
106
+ ## Actions
107
+ - [ ] Shadow architect on [project]
108
+ - [ ] Complete system design course
109
+ - [ ] Pair program with junior weekly
110
+
111
+ ## Check-ins
112
+ - Monthly 1:1 with mentor
113
+ - Bi-weekly progress updates
114
+ ```
115
+
116
+ ## Common Mistakes
117
+
118
+ | ❌ Mistake | ✅ Fix |
119
+ |------------|--------|
120
+ | Doing the work | Guide with questions |
121
+ | Vague feedback | Specific, actionable |
122
+ | No follow-up | Regular check-ins |
123
+ | One-size-fits-all | Adapt to individual |
124
+ | Only fixing problems | Recognize growth |
125
+
126
+ ## Coaching Questions
127
+
128
+ ```
129
+ Discovery:
130
+ - What have you tried?
131
+ - What do you think is the issue?
132
+ - What would success look like?
133
+
134
+ Growth:
135
+ - What did you learn from this?
136
+ - How would you approach it differently?
137
+ - What support do you need?
138
+
139
+ Empowerment:
140
+ - What's your next step?
141
+ - When will you try it?
142
+ - How will I know it worked?
143
+ ```
144
+
145
+ ## Checklist
146
+
147
+ - [ ] Regular 1:1s scheduled
148
+ - [ ] Goals documented
149
+ - [ ] Feedback given regularly
150
+ - [ ] Progress tracked
151
+ - [ ] Growth celebrated
@@ -0,0 +1,166 @@
1
+ ---
2
+ name: technical-debt
3
+ description: |
4
+ Technical debt management and prioritization strategies. Use when: managing
5
+ technical debt, prioritizing refactoring, or when user mentions "tech debt",
6
+ "refactor", "legacy", "cleanup", "improvement".
7
+ version: 1.0.0
8
+ category: leadership
9
+ tags:
10
+ - technical-debt
11
+ - refactoring
12
+ - maintenance
13
+ - prioritization
14
+ depends_on:
15
+ - code-review-advanced
16
+ recommends: []
17
+ used_by: []
18
+ ---
19
+
20
+ # Skill: Technical Debt
21
+
22
+ ## Core Principle
23
+ **Not all debt is bad.** Some debt is an investment. Manage it deliberately.
24
+
25
+ ## Types of Technical Debt
26
+
27
+ | Type | Cause | Example |
28
+ |------|-------|---------|
29
+ | **Deliberate** | Strategic shortcut | MVP with hardcoded config |
30
+ | **Accidental** | Lack of knowledge | Wrong abstraction |
31
+ | **Bit rot** | Time/environment | Outdated dependencies |
32
+ | **Design debt** | Evolving requirements | Architectural mismatch |
33
+
34
+ ## Debt Assessment
35
+
36
+ ### Impact vs Effort Matrix
37
+ ```
38
+ High Impact
39
+
40
+ Quick │ Strategic
41
+ Wins │ Refactors
42
+ ────────────┼────────────
43
+ Ignore │ Consider
44
+ (For now)│ Carefully
45
+
46
+ Low Impact
47
+
48
+ Low Effort High Effort
49
+ ```
50
+
51
+ ## Hard Rules
52
+
53
+ 1. **NEVER ignore debt** - Document it
54
+ 2. **NEVER refactor without value** - What problem are we solving?
55
+ 3. **ALWAYS quantify the cost** - Time lost, bugs caused, velocity impact
56
+ 4. **ALWAYS allocate time** - 10-20% of sprint capacity
57
+
58
+ ## Debt Tracking
59
+
60
+ ### Debt Register
61
+ ```markdown
62
+ # Technical Debt Register
63
+
64
+ | ID | Description | Impact | Effort | Priority | Status |
65
+ |----|-------------|--------|--------|----------|--------|
66
+ | TD-001 | Legacy auth module | High | 5 days | P1 | Planned |
67
+ | TD-002 | Missing tests for payments | High | 3 days | P1 | In Progress |
68
+ | TD-003 | Outdated React version | Medium | 2 days | P2 | Backlog |
69
+ | TD-004 | Hardcoded feature flags | Low | 1 day | P3 | Backlog |
70
+ ```
71
+
72
+ ### Debt Cost Calculator
73
+ ```markdown
74
+ # Debt Cost: Legacy Auth Module
75
+
76
+ ## Symptoms
77
+ - 2 hours/week debugging auth issues
78
+ - 3 security patches in last quarter
79
+ - Can't add new OAuth providers
80
+
81
+ ## Quantified Cost
82
+ - Engineering time: 2 hrs/week × $100/hr × 52 weeks = $10,400/year
83
+ - Security risk: Medium (estimated $50K if exploited)
84
+ - Opportunity cost: 2 features delayed
85
+
86
+ ## Fix Cost
87
+ - Refactor: 5 days × $800/day = $4,000
88
+ - Testing: 2 days × $800/day = $1,600
89
+ - Total: $5,600
90
+
91
+ ## ROI
92
+ - Payback: ~6 months
93
+ - Year 1 savings: $4,800
94
+ - Risk reduction: Significant
95
+
96
+ ## Recommendation
97
+ Fix in Q2 - High priority
98
+ ```
99
+
100
+ ## Prioritization Framework
101
+
102
+ ### SQALE Method
103
+ ```
104
+ S - Severity: How bad is it?
105
+ Q - Quality: What does it affect?
106
+ U - Urgency: When must it be fixed?
107
+ A - Area: Where in the codebase?
108
+ L - Level: What skill needed?
109
+ E - Effort: How long to fix?
110
+ ```
111
+
112
+ ## Refactoring Strategies
113
+
114
+ ### Strangler Fig Pattern
115
+ ```typescript
116
+ // 1. Create new implementation
117
+ const newUserService = new UserServiceV2();
118
+
119
+ // 2. Route new features to new code
120
+ if (featureFlags.useNewUserService) {
121
+ return newUserService.getUser(id);
122
+ }
123
+
124
+ // 3. Gradually migrate existing calls
125
+ const userService = isNewFeature ? newUserService : legacyUserService;
126
+
127
+ // 4. Remove old code when complete
128
+ ```
129
+
130
+ ### Incremental Refactoring
131
+ ```
132
+ Week 1: Add tests to legacy code
133
+ Week 2: Extract first module
134
+ Week 3: Extract second module
135
+ Week 4: Remove legacy code
136
+ ```
137
+
138
+ ## Common Mistakes
139
+
140
+ | ❌ Mistake | ✅ Fix |
141
+ |------------|--------|
142
+ | "Rewrite everything" | Incremental improvement |
143
+ | No debt tracking | Maintain debt register |
144
+ | Zero debt goal | Accept some debt |
145
+ | Ignoring until crisis | Regular debt review |
146
+ | Refactoring without tests | Test first |
147
+
148
+ ## Debt Review Meeting
149
+
150
+ ```markdown
151
+ ## Agenda (30 min)
152
+
153
+ 1. Review new debt items (5 min)
154
+ 2. Update existing debt status (5 min)
155
+ 3. Prioritize for next sprint (10 min)
156
+ 4. Assign owners (5 min)
157
+ 5. Action items (5 min)
158
+ ```
159
+
160
+ ## Checklist
161
+
162
+ - [ ] Debt register maintained
163
+ - [ ] Costs quantified
164
+ - [ ] Sprint capacity allocated
165
+ - [ ] Regular reviews scheduled
166
+ - [ ] Fixes tested before removing debt