super-opencode 1.1.2 → 1.2.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.
- package/.opencode/agents/architect.md +54 -31
- package/.opencode/agents/backend.md +61 -34
- package/.opencode/agents/data-agent.md +422 -0
- package/.opencode/agents/devops-agent.md +331 -0
- package/.opencode/agents/frontend.md +63 -36
- package/.opencode/agents/mobile-agent.md +636 -0
- package/.opencode/agents/optimizer.md +25 -18
- package/.opencode/agents/pm-agent.md +114 -50
- package/.opencode/agents/quality.md +36 -29
- package/.opencode/agents/researcher.md +30 -21
- package/.opencode/agents/reviewer.md +39 -32
- package/.opencode/agents/security.md +42 -34
- package/.opencode/agents/writer.md +42 -31
- package/.opencode/commands/soc-analyze.md +55 -31
- package/.opencode/commands/soc-brainstorm.md +48 -26
- package/.opencode/commands/soc-cleanup.md +47 -25
- package/.opencode/commands/soc-deploy.md +271 -0
- package/.opencode/commands/soc-design.md +51 -26
- package/.opencode/commands/soc-explain.md +46 -23
- package/.opencode/commands/soc-git.md +47 -25
- package/.opencode/commands/soc-help.md +35 -14
- package/.opencode/commands/soc-implement.md +59 -29
- package/.opencode/commands/soc-improve.md +42 -20
- package/.opencode/commands/soc-onboard.md +329 -0
- package/.opencode/commands/soc-plan.md +215 -0
- package/.opencode/commands/soc-pm.md +40 -18
- package/.opencode/commands/soc-research.md +43 -20
- package/.opencode/commands/soc-review.md +39 -18
- package/.opencode/commands/soc-test.md +43 -21
- package/.opencode/commands/soc-validate.md +221 -0
- package/.opencode/commands/soc-workflow.md +38 -17
- package/.opencode/skills/confidence-check/SKILL.md +26 -19
- package/.opencode/skills/debug-protocol/SKILL.md +27 -17
- package/.opencode/skills/decision-log/SKILL.md +236 -0
- package/.opencode/skills/doc-sync/SKILL.md +345 -0
- package/.opencode/skills/package-manager/SKILL.md +502 -0
- package/.opencode/skills/package-manager/scripts/README.md +106 -0
- package/.opencode/skills/package-manager/scripts/detect-package-manager.sh +796 -0
- package/.opencode/skills/reflexion/SKILL.md +18 -11
- package/.opencode/skills/security-audit/SKILL.md +19 -14
- package/.opencode/skills/self-check/SKILL.md +30 -14
- package/.opencode/skills/simplification/SKILL.md +19 -5
- package/.opencode/skills/tech-debt/SKILL.md +245 -0
- package/LICENSE +1 -1
- package/README.md +126 -9
- package/dist/cli.js +143 -41
- package/package.json +27 -12
- package/.opencode/settings.json +0 -3
|
@@ -6,12 +6,14 @@ description: Post-action analysis to generate heuristics, update project memory,
|
|
|
6
6
|
# Reflexion Skill
|
|
7
7
|
|
|
8
8
|
## Purpose
|
|
9
|
+
|
|
9
10
|
To transform **Failures** into **Heuristics**.
|
|
10
11
|
Reflexion is the cognitive step that occurs **after** a failed attempt and **before** the next attempt. It breaks the "Insanity Loop" (doing the same thing twice expecting different results).
|
|
11
12
|
|
|
12
13
|
**ROI Metric**: Prevents 5-10 wasted attempts in a loop by forcing a strategy shift after the first failure.
|
|
13
14
|
|
|
14
15
|
## When to Use
|
|
16
|
+
|
|
15
17
|
- **Automatic Trigger**: After a tool error (e.g., `bash` exit code != 0).
|
|
16
18
|
- **Automatic Trigger**: After a test failure during `execution` mode.
|
|
17
19
|
- **Manual Trigger**: When the user rejects an artifact ("This isn't what I asked for").
|
|
@@ -20,24 +22,28 @@ Reflexion is the cognitive step that occurs **after** a failed attempt and **bef
|
|
|
20
22
|
## The Reflexion Protocol (The Loop)
|
|
21
23
|
|
|
22
24
|
### 1. The Halt (Stop)
|
|
25
|
+
|
|
23
26
|
**Rule**: *Never retry immediately.*
|
|
24
27
|
If an error occurs, you must pause. Do not simply re-run the command hoping for a different outcome.
|
|
25
28
|
|
|
26
29
|
### 2. The Trace (Diagnosis)
|
|
30
|
+
|
|
27
31
|
**Action**: Analyze the mismatch between *Expected Output* and *Actual Output*.
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
32
|
+
- *Was it a Syntax Error?* (Context failure).
|
|
33
|
+
- *Was it a Logic Error?* (Reasoning failure).
|
|
34
|
+
- *Was it a Hallucination?* (Knowledge failure).
|
|
31
35
|
|
|
32
36
|
### 3. The Heuristic (Correction)
|
|
37
|
+
|
|
33
38
|
**Action**: Create a new rule for yourself.
|
|
34
|
-
*
|
|
35
|
-
*
|
|
39
|
+
- *Old Thought:* "I will use `rm -rf` to clean up."
|
|
40
|
+
- *New Heuristic:* "I must check if the directory exists before attempting delete."
|
|
36
41
|
|
|
37
42
|
### 4. The Store (Memory)
|
|
43
|
+
|
|
38
44
|
**Action**: Save this lesson.
|
|
39
|
-
*
|
|
40
|
-
*
|
|
45
|
+
- *Short-term:* Apply to current context window.
|
|
46
|
+
- *Long-term:* Write to `.opencode/memory/patterns.md`.
|
|
41
47
|
|
|
42
48
|
## Execution Template
|
|
43
49
|
|
|
@@ -77,6 +83,7 @@ Maintain a dedicated memory structure to allow the `researcher` and `pm-agent` t
|
|
|
77
83
|
```
|
|
78
84
|
|
|
79
85
|
### Example: `.opencode/memory/anti_patterns.md`
|
|
86
|
+
|
|
80
87
|
```markdown
|
|
81
88
|
## ⛔ Anti-Patterns
|
|
82
89
|
|
|
@@ -93,10 +100,10 @@ Maintain a dedicated memory structure to allow the `researcher` and `pm-agent` t
|
|
|
93
100
|
|
|
94
101
|
## Integration with Agents
|
|
95
102
|
|
|
96
|
-
-
|
|
97
|
-
|
|
98
|
-
-
|
|
99
|
-
-
|
|
103
|
+
- **`execution` agent**: Must trigger `reflexion` after 2 failed build attempts.
|
|
104
|
+
- *Logic:* "Attempt 1 Failed -> Retry -> Attempt 2 Failed -> **STOP & REFLECT** -> Attempt 3".
|
|
105
|
+
- **`pm-agent`**: Reads `.opencode/memory/patterns.md` at the start of a new task to load context.
|
|
106
|
+
- **`writer`**: Uses successful reflexions to update the project's `README.md` or `CONTRIBUTING.md`.
|
|
100
107
|
|
|
101
108
|
## Reflexion vs. Debugging
|
|
102
109
|
|
|
@@ -6,20 +6,23 @@ description: Static Analysis and Threat Modeling skill to detect OWASP Top 10 vu
|
|
|
6
6
|
# Security Audit Skill
|
|
7
7
|
|
|
8
8
|
## Purpose
|
|
9
|
+
|
|
9
10
|
To act as an automated **SAST (Static Application Security Testing)** scanner.
|
|
10
11
|
**Goal**: Identify vulnerabilities in the *implementation* phase, before the code reaches the `review` phase.
|
|
11
12
|
|
|
12
13
|
**ROI Metric**: Detecting a hardcoded secret here takes 5 seconds. Rotating a compromised key in production takes 5 hours.
|
|
13
14
|
|
|
14
15
|
## When to Use
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
16
|
+
|
|
17
|
+
- **Trigger**: When `backend` implements an endpoint involving `users`, `auth`, or `payments`.
|
|
18
|
+
- **Trigger**: When `frontend` uses `dangerouslySetInnerHTML` or similar raw HTML rendering.
|
|
19
|
+
- **Trigger**: When `pm-agent` flags a task as "High Risk."
|
|
20
|
+
- **Agent**: Primary skill for the `security` agent; secondary skill for `backend`/`review` modes.
|
|
19
21
|
|
|
20
22
|
## The Audit Protocol (The Scanner)
|
|
21
23
|
|
|
22
24
|
### 1. Pattern Scanning (The Grep Check)
|
|
25
|
+
|
|
23
26
|
*Scan the code for these specific "smells":*
|
|
24
27
|
|
|
25
28
|
| Risk Category | Keywords/Patterns to Flag |
|
|
@@ -31,16 +34,18 @@ To act as an automated **SAST (Static Application Security Testing)** scanner.
|
|
|
31
34
|
| **Debug Leftovers** | `console.log(userObj)`, `debugger`, `0.0.0.0` (binding to all interfaces) |
|
|
32
35
|
|
|
33
36
|
### 2. Logic Analysis (STRIDE)
|
|
37
|
+
|
|
34
38
|
*Ask these questions about the flow:*
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
+
- **Spoofing**: Does this verify *who* the user is? (Check: Auth Middleware presence).
|
|
40
|
+
- **Tampering**: Can I modify the payload? (Check: Zod/Joi validation `strip()` on unknown keys).
|
|
41
|
+
- **Information Disclosure**: Does the error return the stack trace? (Check: `try/catch` blocks).
|
|
42
|
+
- **Elevation of Privilege**: Does it check `user.id === resource.ownerId`? (Check: Authorization logic).
|
|
39
43
|
|
|
40
44
|
### 3. Dependency Check (Supply Chain)
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
45
|
+
|
|
46
|
+
* If `package.json` was modified:
|
|
47
|
+
- Are versions pinned? (Good: `1.2.3`, Bad: `^1.2.3`).
|
|
48
|
+
- Are there known CVEs? (Trigger `tavily` search).
|
|
44
49
|
|
|
45
50
|
## Execution Template
|
|
46
51
|
|
|
@@ -85,6 +90,6 @@ To act as an automated **SAST (Static Application Security Testing)** scanner.
|
|
|
85
90
|
|
|
86
91
|
## Integration with Agents
|
|
87
92
|
|
|
88
|
-
-
|
|
89
|
-
-
|
|
90
|
-
-
|
|
93
|
+
- **`security` agent**: Uses this skill as its primary method of interaction.
|
|
94
|
+
- **`backend` agent**: Must invoke `security-audit` before marking an API task as "Complete."
|
|
95
|
+
- **`review` mode**: Uses the *Findings Table* as the basis for "Critical" comments.
|
|
@@ -6,37 +6,47 @@ description: Post-implementation validation to enforce the Definition of Done (D
|
|
|
6
6
|
# Self-Check Skill
|
|
7
7
|
|
|
8
8
|
## Purpose
|
|
9
|
+
|
|
9
10
|
To validate work **after** implementation but **before** handoff.
|
|
10
11
|
This is the "Check" in PDCA. It prevents the "It works on my machine" (or "It works in my context window") syndrome.
|
|
11
12
|
|
|
12
13
|
**ROI Metric**: Catching a syntax error here costs 50 tokens. Catching it in a PR review costs 5,000 tokens + human time.
|
|
13
14
|
|
|
14
15
|
## When to Use
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
16
|
+
|
|
17
|
+
- **Trigger**: Immediately after `execution` mode finishes writing code.
|
|
18
|
+
- **Trigger**: Before the `backend` agent hands off to `frontend`.
|
|
19
|
+
- **Trigger**: Before any `git commit`.
|
|
18
20
|
|
|
19
21
|
## The "Proof of Work" Protocol
|
|
20
22
|
|
|
21
23
|
### 1. The Build Check (Syntax)
|
|
24
|
+
|
|
22
25
|
**Rule**: *Code that doesn't build doesn't exist.*
|
|
23
|
-
|
|
24
|
-
-
|
|
26
|
+
|
|
27
|
+
- Did you run the build/transpile command? (`npm run build`, `go build`, etc.)
|
|
28
|
+
- **Evidence**: Paste the exit code and the last 3 lines of output.
|
|
25
29
|
|
|
26
30
|
### 2. The Logic Check (Behavior)
|
|
31
|
+
|
|
27
32
|
**Rule**: *Claims require proof.*
|
|
28
|
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
33
|
+
|
|
34
|
+
- **Forbidden Phrase**: "I ran the tests and they passed." (This is often a hallucination).
|
|
35
|
+
- **Required Action**: Run the test command via `run_command` and capture the actual output.
|
|
36
|
+
- **Evidence**: Paste the `Total: X Passed, 0 Failed` line.
|
|
31
37
|
|
|
32
38
|
### 3. The Contract Check (Requirements)
|
|
39
|
+
|
|
33
40
|
**Rule**: *Did you solve the user's problem?*
|
|
34
|
-
|
|
41
|
+
|
|
42
|
+
- Map every constraint from the original prompt to a specific line of code or test case.
|
|
35
43
|
|
|
36
44
|
### 4. The Hygiene Check (Cleanup)
|
|
45
|
+
|
|
37
46
|
**Rule**: *Leave no trace.*
|
|
38
|
-
|
|
39
|
-
-
|
|
47
|
+
|
|
48
|
+
- Scan for: `console.log("here")`, `debugger`, commented out code blocks, or `TODO` comments added by you.
|
|
49
|
+
- **Action**: Remove them.
|
|
40
50
|
|
|
41
51
|
## Execution Template
|
|
42
52
|
|
|
@@ -53,24 +63,30 @@ This is the "Check" in PDCA. It prevents the "It works on my machine" (or "It wo
|
|
|
53
63
|
> tsc
|
|
54
64
|
✨ Done in 2.45s.
|
|
55
65
|
```
|
|
66
|
+
|
|
56
67
|
- **Status**: [ PASS / FAIL ]
|
|
57
68
|
|
|
58
69
|
### 2. Test Verification
|
|
70
|
+
|
|
59
71
|
- **Command**: `npm test -- user.service.test.ts`
|
|
60
72
|
- **Output**:
|
|
73
|
+
|
|
61
74
|
```text
|
|
62
75
|
PASS src/services/user.service.test.ts
|
|
63
76
|
Tests: 3 passed, 3 total
|
|
64
77
|
```
|
|
78
|
+
|
|
65
79
|
- **Status**: [ PASS / FAIL ] -> *If FAIL, trigger `reflexion` skill.*
|
|
66
80
|
|
|
67
81
|
### 3. Requirements Mapping
|
|
82
|
+
|
|
68
83
|
| Requirement | Implemented? | Evidence (File/Line) |
|
|
69
84
|
| :--- | :--- | :--- |
|
|
70
85
|
| "Users must have a role" | ✅ | `UserSchema.ts:12` (Zod enum) |
|
|
71
86
|
| "Passwords must be hashed" | ✅ | `AuthService.ts:45` (bcrypt call) |
|
|
72
87
|
|
|
73
88
|
### 4. Code Hygiene
|
|
89
|
+
|
|
74
90
|
- [ ] Removed debug `console.log`s?
|
|
75
91
|
- [ ] Removed temporary comments?
|
|
76
92
|
- [ ] Ran Linter? (`npm run lint`)
|
|
@@ -90,6 +106,6 @@ If you see these patterns in your own reasoning, **STOP**:
|
|
|
90
106
|
|
|
91
107
|
## Integration with Agents
|
|
92
108
|
|
|
93
|
-
-
|
|
94
|
-
-
|
|
95
|
-
-
|
|
109
|
+
- **`execution` mode**: Must run `self-check` before declaring `Status: COMPLETE`.
|
|
110
|
+
- **`pm-agent`**: Rejects any task update that does not include a `self-check` artifact.
|
|
111
|
+
- **`reflexion` skill**: If `self-check` results in **FAIL**, the agent must immediately enter `reflexion` mode to analyze the root cause before retrying.
|
|
@@ -6,47 +6,57 @@ description: Complexity reduction and architectural streamlining for Frontend, B
|
|
|
6
6
|
# Simplification Skill (Occam's Razor)
|
|
7
7
|
|
|
8
8
|
## Purpose
|
|
9
|
+
|
|
9
10
|
"Simplicity is the ultimate sophistication." This skill provides a rigorous protocol for identifying and eliminating over-engineering, code bloat, and technical debt across the entire stack.
|
|
10
11
|
|
|
11
12
|
## Overview
|
|
13
|
+
|
|
12
14
|
The Simplification Skill is a cross-functional protocol used to flatten logic, reduce state, and ensure every line of code justifies its existence. It leverages specialized agents and MCP tools to validate architectural simplicity and performance.
|
|
13
15
|
|
|
14
16
|
## Prerequisites
|
|
17
|
+
|
|
15
18
|
- **Agents**: [Backend](file:///.opencode/agents/backend.md), [Frontend](file:///.opencode/agents/frontend.md), [Quality](file:///.opencode/agents/quality.md).
|
|
16
|
-
- **MCP Tools**:
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
- **MCP Tools**:
|
|
20
|
+
- `context7`: To research lightweight alternatives and library standards.
|
|
21
|
+
- `sequential-thinking`: To audit complex logic flows for potential flattening.
|
|
22
|
+
- `sqlite`: To verify if database schemas or queries can be compressed.
|
|
23
|
+
- `playwright`/`chrome-devtools`: To identify UI "jank" or DOM complexity.
|
|
21
24
|
|
|
22
25
|
## Agent-Specific Simplification Protocols
|
|
23
26
|
|
|
24
27
|
### [Senior Backend Engineer](file:///.opencode/agents/backend.md)
|
|
28
|
+
|
|
25
29
|
- **State Reduction**: Derive values instead of storing them. If `is_active` can be derived from `status === 'active'`, delete the redundant field.
|
|
26
30
|
- **Query Optimization**: Use `sqlite` to check for N+1 issues. Replace nested loops with single optimized queries or batching.
|
|
27
31
|
- **Error Flattening**: Centralize error handling middleware. Remove repetitive `try/catch` blocks from business logic to expose the "Happy Path".
|
|
28
32
|
|
|
29
33
|
### [Senior Frontend Engineer](file:///.opencode/agents/frontend.md)
|
|
34
|
+
|
|
30
35
|
- **DOM Streamlining**: Replace "Div Soup" with semantic HTML elements.
|
|
31
36
|
- **Hook Optimization**: Audit `useEffect` usage. If it's used to sync state, replace it with derived constants or `useMemo`.
|
|
32
37
|
- **Styling Discipline**: Replace custom inline styles with standard Tailwind utility classes or `cva` variants.
|
|
33
38
|
|
|
34
39
|
### [QA Automation Engineer](file:///.opencode/agents/quality.md)
|
|
40
|
+
|
|
35
41
|
- **Test Pruning**: Remove redundant unit tests if the logic is covered by a high-confidence integration test.
|
|
36
42
|
- **Selector Simplification**: Replace fragile XPaths or class-based selectors with accessible `getByRole` or `getByLabel` locators.
|
|
37
43
|
|
|
38
44
|
## The Procedural Workflow
|
|
39
45
|
|
|
40
46
|
### 1. The Deletion Test
|
|
47
|
+
|
|
41
48
|
- **Action**: Use `grep_search` to find references to the target code. If references < 1, **DELETE**.
|
|
42
49
|
- **Rule**: Dead code is the best code.
|
|
43
50
|
|
|
44
51
|
### 2. The Library Leverage (via `context7`)
|
|
52
|
+
|
|
45
53
|
- **Action**: Use `context7` to check if a complex custom utility (e.g., date formatting, deep cloning) can be replaced by a native function or a lightweight standard library (Lodash/Zustand).
|
|
46
54
|
|
|
47
55
|
### 3. Flat Logic Audit (via `sequential-thinking`)
|
|
56
|
+
|
|
48
57
|
- **Action**: Step through the logic. If nesting > 3 levels or cyclomatic complexity is high, apply guard clauses.
|
|
49
58
|
- **Target Pattern**:
|
|
59
|
+
|
|
50
60
|
```diff
|
|
51
61
|
- if (user) {
|
|
52
62
|
- if (user.active) {
|
|
@@ -58,6 +68,7 @@ The Simplification Skill is a cross-functional protocol used to flatten logic, r
|
|
|
58
68
|
```
|
|
59
69
|
|
|
60
70
|
## Complexity Metrics to Watch
|
|
71
|
+
|
|
61
72
|
- **Nesting Level**: Maximum 3 levels of indentation.
|
|
62
73
|
- **Function Size**: Maximum 30 lines.
|
|
63
74
|
- **Cognitive Weight**: If a function requires `sequential-thinking` just to "read" it, it's too complex.
|
|
@@ -81,12 +92,15 @@ The Simplification Skill is a cross-functional protocol used to flatten logic, r
|
|
|
81
92
|
```
|
|
82
93
|
|
|
83
94
|
**After**:
|
|
95
|
+
|
|
84
96
|
```javascript
|
|
85
97
|
// Streamlined, readable, and efficient code
|
|
86
98
|
```
|
|
87
99
|
|
|
88
100
|
### 3. Impact Assessment
|
|
101
|
+
|
|
89
102
|
- Lines Removed: [Count]
|
|
90
103
|
- Performance Gain: [e.g., Reduced O(N²) to O(N)]
|
|
91
104
|
- Maintenance Status: Optimized
|
|
105
|
+
|
|
92
106
|
```
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tech-debt
|
|
3
|
+
description: Technical debt identification, prioritization, and strategic repayment planning.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Tech Debt Skill
|
|
7
|
+
|
|
8
|
+
## Purpose
|
|
9
|
+
|
|
10
|
+
To transform **silent code rot** into **managed, prioritized backlog items**. This skill provides a systematic approach to identifying, quantifying, and scheduling technical debt repayment—preventing the "big bang" rewrite and enabling sustainable development velocity.
|
|
11
|
+
|
|
12
|
+
**ROI Metric**: Addressing debt early costs 1x. Addressing it late costs 10x. Ignoring it costs 100x (failed projects).
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- **Trigger**: When velocity is slowing down (features taking longer).
|
|
17
|
+
- **Trigger**: When `reflexion` identifies recurring issues.
|
|
18
|
+
- **Trigger**: Before major feature work ("Clean the campsite first").
|
|
19
|
+
- **Trigger**: When code complexity metrics exceed thresholds.
|
|
20
|
+
- **Trigger**: When `pm-agent` schedules a "debt sprint."
|
|
21
|
+
|
|
22
|
+
## The Debt Management Protocol (The 4-Step Process)
|
|
23
|
+
|
|
24
|
+
### 1. Identification (Where Is The Debt?)
|
|
25
|
+
|
|
26
|
+
**Scan for these debt signals:**
|
|
27
|
+
|
|
28
|
+
| Signal | Detection Method | Example |
|
|
29
|
+
|:-------|:-----------------|:--------|
|
|
30
|
+
| **Code Smells** | Static analysis, complexity metrics | Functions >50 lines, nested conditionals >3 levels |
|
|
31
|
+
| **Outdated Dependencies** | `npm outdated`, `cargo outdated` | React 16 when 18 is available |
|
|
32
|
+
| **Missing Tests** | Coverage reports | Critical path has <50% coverage |
|
|
33
|
+
| **Documentation Drift** | Doc vs code comparison | API docs don't match implementation |
|
|
34
|
+
| **Workarounds** | Code comments (`// HACK`, `// FIXME`) | Temporary fixes that became permanent |
|
|
35
|
+
| **Performance Issues** | Profiling, metrics | Page load >3s, API latency >500ms |
|
|
36
|
+
| **Security Vulnerabilities** | `npm audit`, SAST scans | Known CVEs in dependencies |
|
|
37
|
+
|
|
38
|
+
### 2. Quantification (How Bad Is It?)
|
|
39
|
+
|
|
40
|
+
Score each debt item across three dimensions:
|
|
41
|
+
|
|
42
|
+
**Impact (1-10)**: How much does this hurt?
|
|
43
|
+
- Development velocity
|
|
44
|
+
- System reliability
|
|
45
|
+
- Security posture
|
|
46
|
+
- User experience
|
|
47
|
+
|
|
48
|
+
**Effort (1-10)**: How hard to fix?
|
|
49
|
+
- Lines of code to change
|
|
50
|
+
- Files affected
|
|
51
|
+
- Dependencies to update
|
|
52
|
+
- Tests to write
|
|
53
|
+
- Risk of breaking changes
|
|
54
|
+
|
|
55
|
+
**Interest Rate (1-10)**: How fast is it growing?
|
|
56
|
+
- How often does this code change?
|
|
57
|
+
- How many new features touch this area?
|
|
58
|
+
- How many workarounds are being added?
|
|
59
|
+
|
|
60
|
+
**Debt Score = Impact × Interest Rate / Effort**
|
|
61
|
+
|
|
62
|
+
Higher score = Pay this debt first.
|
|
63
|
+
|
|
64
|
+
### 3. Categorization (What Type Of Debt?)
|
|
65
|
+
|
|
66
|
+
| Category | Description | Example | Typical Action |
|
|
67
|
+
|:---------|:------------|:--------|:-------------|
|
|
68
|
+
| **Design Debt** | Architectural shortcuts | God class, tight coupling | Refactor with ADR |
|
|
69
|
+
| **Code Debt** | Implementation shortcuts | Copy-pasted code, long methods | Refactor incrementally |
|
|
70
|
+
| **Test Debt** | Missing or poor tests | No integration tests | Write tests before changes |
|
|
71
|
+
| **Documentation Debt** | Outdated or missing docs | API changes not documented | Update docs as you go |
|
|
72
|
+
| **Dependency Debt** | Outdated libraries | React 16 in 2026 | Scheduled upgrade |
|
|
73
|
+
| **Infrastructure Debt** | Ops shortcuts | Manual deploys | Automate via IaC |
|
|
74
|
+
| **Skill Debt** | Team knowledge gaps | No one knows GraphQL | Training + pairing |
|
|
75
|
+
|
|
76
|
+
### 4. Scheduling (When Do We Pay?)
|
|
77
|
+
|
|
78
|
+
**Strategies:**
|
|
79
|
+
|
|
80
|
+
**A. Debt Sprints (20% Rule)**
|
|
81
|
+
- Reserve 20% of every sprint for debt repayment.
|
|
82
|
+
- Pay highest-scored debt items first.
|
|
83
|
+
- Track debt burndown like feature burndown.
|
|
84
|
+
|
|
85
|
+
**B. Boy Scout Rule**
|
|
86
|
+
- "Leave the code better than you found it."
|
|
87
|
+
- Small improvements with every feature PR.
|
|
88
|
+
- Limit: 10-20% of PR scope should be cleanup.
|
|
89
|
+
|
|
90
|
+
**C. Before New Features**
|
|
91
|
+
- Clean debt in the area you're about to modify.
|
|
92
|
+
- Prevents building on shaky foundations.
|
|
93
|
+
|
|
94
|
+
**D. Scheduled Maintenance**
|
|
95
|
+
- Quarterly dependency updates.
|
|
96
|
+
- Bi-annual architecture reviews.
|
|
97
|
+
- Annual security audits.
|
|
98
|
+
|
|
99
|
+
## Debt Item Template
|
|
100
|
+
|
|
101
|
+
```markdown
|
|
102
|
+
# Tech Debt Item: [TITLE]
|
|
103
|
+
|
|
104
|
+
## Summary
|
|
105
|
+
**ID**: DEBT-XXX
|
|
106
|
+
**Category**: [Design/Code/Test/Doc/Dependency/Infra/Skill]
|
|
107
|
+
**Filed Date**: YYYY-MM-DD
|
|
108
|
+
**Status**: Identified | Scheduled | In Progress | Paid
|
|
109
|
+
|
|
110
|
+
## Problem Statement
|
|
111
|
+
[What is the debt? What are the symptoms?]
|
|
112
|
+
|
|
113
|
+
[Example: The UserService class has grown to 2000 lines and handles authentication, profile management, and preferences. Changes require touching 15+ methods.]
|
|
114
|
+
|
|
115
|
+
## Impact Assessment
|
|
116
|
+
|
|
117
|
+
| Dimension | Score (1-10) | Justification |
|
|
118
|
+
|:----------|:------------:|:--------------|
|
|
119
|
+
| **Impact** | 8 | Every user feature touches this class. Changes are slow and error-prone. |
|
|
120
|
+
| **Effort** | 6 | Requires splitting into 3-4 services. Estimated 3 days. |
|
|
121
|
+
| **Interest Rate** | 9 | We add 2-3 new user features per sprint. Debt grows fast. |
|
|
122
|
+
|
|
123
|
+
**Debt Score**: (8 × 9) / 6 = **12.0** [Pay Immediately: >10]
|
|
124
|
+
|
|
125
|
+
## Symptoms
|
|
126
|
+
- [ ] Feature X took 5 days instead of 2
|
|
127
|
+
- [ ] Bug Y introduced because of tight coupling
|
|
128
|
+
- [ ] Developer onboarding takes 3 days to understand UserService
|
|
129
|
+
- [ ] Tests are flaky due to too many responsibilities
|
|
130
|
+
|
|
131
|
+
## Proposed Solution
|
|
132
|
+
[What should we do to pay this debt?]
|
|
133
|
+
|
|
134
|
+
[Example: Split UserService into AuthService, ProfileService, and PreferenceService. Each <300 lines.]
|
|
135
|
+
|
|
136
|
+
### Steps
|
|
137
|
+
1. [ ] Step 1: Create ProfileService, move profile methods
|
|
138
|
+
2. [ ] Step 2: Update tests for ProfileService
|
|
139
|
+
3. [ ] Step 3: Create PreferenceService, move preference methods
|
|
140
|
+
4. [ ] Step 4: Update tests for PreferenceService
|
|
141
|
+
5. [ ] Step 5: Refactor UserService to AuthService only
|
|
142
|
+
6. [ ] Step 6: Update all imports and calls
|
|
143
|
+
7. [ ] Step 7: Verify all tests pass
|
|
144
|
+
|
|
145
|
+
## Risks & Mitigations
|
|
146
|
+
- **Risk**: Breaking changes to API → Mitigation: Maintain backward-compatible wrapper during transition
|
|
147
|
+
- **Risk**: Tests need major rewrite → Mitigation: Write new service tests before migration
|
|
148
|
+
|
|
149
|
+
## Payment Schedule
|
|
150
|
+
- **Strategy**: Before New Feature
|
|
151
|
+
- **Scheduled Sprint**: Sprint 12 (when we build User Preferences v2)
|
|
152
|
+
- **Owner**: @backend-team
|
|
153
|
+
- **Estimated Effort**: 3 days
|
|
154
|
+
|
|
155
|
+
## Notes
|
|
156
|
+
- **Related PRs**: #123, #456
|
|
157
|
+
- **Related ADRs**: ADR-002 (Service Boundaries)
|
|
158
|
+
- **Outcome (when paid)**: [To be filled]
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Execution Template
|
|
162
|
+
|
|
163
|
+
*Use this when running a debt audit.*
|
|
164
|
+
|
|
165
|
+
```markdown
|
|
166
|
+
## 🔍 Tech Debt Audit: [Scope]
|
|
167
|
+
|
|
168
|
+
### 1. Scan Results
|
|
169
|
+
|
|
170
|
+
| ID | Category | Location | Impact | Effort | Interest | Score | Priority |
|
|
171
|
+
|:---|:---------|:---------|:------:|:------:|:--------:|:-----:|:--------:|
|
|
172
|
+
| D-001 | Design | UserService.ts | 8 | 6 | 9 | 12.0 | HIGH |
|
|
173
|
+
| D-002 | Dependency | React 16.x | 6 | 4 | 7 | 10.5 | HIGH |
|
|
174
|
+
| D-003 | Test | auth/ | 7 | 3 | 6 | 14.0 | HIGH |
|
|
175
|
+
| D-004 | Code | utils/helpers.js | 4 | 2 | 3 | 6.0 | MEDIUM |
|
|
176
|
+
|
|
177
|
+
### 2. High Priority Items (Score >10)
|
|
178
|
+
|
|
179
|
+
#### D-003: Missing Auth Tests
|
|
180
|
+
**Problem**: Authentication flows have 23% test coverage.
|
|
181
|
+
**Impact**: Every auth change risks regression.
|
|
182
|
+
**Solution**: Write integration tests for all auth flows.
|
|
183
|
+
**Effort**: 2 days
|
|
184
|
+
**Schedule**: Next sprint (Sprint 11)
|
|
185
|
+
|
|
186
|
+
### 3. Payment Plan
|
|
187
|
+
|
|
188
|
+
**This Sprint (Sprint 10)**
|
|
189
|
+
- [ ] D-004: Refactor utils/helpers.js (1 day)
|
|
190
|
+
- Feature work: 80%
|
|
191
|
+
- Debt work: 20%
|
|
192
|
+
|
|
193
|
+
**Next Sprint (Sprint 11)**
|
|
194
|
+
- [ ] D-003: Auth test coverage (2 days)
|
|
195
|
+
- [ ] D-002: React upgrade planning (1 day)
|
|
196
|
+
- Feature work: 70%
|
|
197
|
+
- Debt work: 30%
|
|
198
|
+
|
|
199
|
+
**Following Sprint (Sprint 12)**
|
|
200
|
+
- [ ] D-001: Split UserService (3 days)
|
|
201
|
+
- Feature work: 60%
|
|
202
|
+
- Debt work: 40%
|
|
203
|
+
|
|
204
|
+
### 4. Debt Metrics
|
|
205
|
+
- **Total Items**: 4
|
|
206
|
+
- **High Priority**: 3
|
|
207
|
+
- **Estimated Total Effort**: 12 days
|
|
208
|
+
- **Debt Burndown Target**: 0 high-priority items by end of Q2
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## Debt Register
|
|
212
|
+
|
|
213
|
+
Maintain a central debt register:
|
|
214
|
+
|
|
215
|
+
```markdown
|
|
216
|
+
# Technical Debt Register
|
|
217
|
+
|
|
218
|
+
## Active Debt
|
|
219
|
+
| ID | Title | Category | Score | Status | Owner | Target Sprint |
|
|
220
|
+
|:---|:------|:---------|:-----:|:-------|:------|:-------------:|
|
|
221
|
+
| D-001 | UserService too large | Design | 12.0 | Scheduled | Backend | 12 |
|
|
222
|
+
| D-002 | React 16 outdated | Dependency | 10.5 | Scheduled | Frontend | 11 |
|
|
223
|
+
| D-003 | Auth tests missing | Test | 14.0 | In Progress | Quality | 11 |
|
|
224
|
+
|
|
225
|
+
## Recently Paid
|
|
226
|
+
| ID | Title | Category | Paid Date | Effort | Outcome |
|
|
227
|
+
|:---|:------|:---------|:----------|:-------|:--------|
|
|
228
|
+
| D-000 | Legacy API wrapper | Code | 2026-01-15 | 2 days | API response time -30% |
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
## Integration with Agents
|
|
232
|
+
|
|
233
|
+
- **`architect`**: Identifies design debt, creates ADRs for major refactors.
|
|
234
|
+
- **`backend` / `frontend`**: Identifies code debt during implementation.
|
|
235
|
+
- **`quality`**: Identifies test debt from coverage reports.
|
|
236
|
+
- **`pm-agent`**: Schedules debt sprints, tracks debt burndown.
|
|
237
|
+
- **`reflexion`**: Surfaces recurring issues that become debt items.
|
|
238
|
+
|
|
239
|
+
## Anti-Patterns (Avoid)
|
|
240
|
+
|
|
241
|
+
- ❌ **"We'll fix it later"** without scheduling → Becomes permanent
|
|
242
|
+
- ❌ **Big Bang Rewrite** → High risk, hard to validate
|
|
243
|
+
- ❌ **Perfect is Enemy of Good** → Don't gold-plate while debt accumulates
|
|
244
|
+
- ❌ **Debt Amnesty** → Don't ignore debt because "it's always been there"
|
|
245
|
+
- ❌ **Paying Low-Score Debt First** → Focus on high-impact, high-interest debt
|