karitham.dev
a dotfile but it's really big
opencode: diagram skills & rewrite some of them
+263
-66
+1
modules/opencode/agents/ask.md
+1
modules/opencode/agents/ask.md
+2
-1
modules/opencode/agents/code-designer.md
+2
-1
modules/opencode/agents/code-designer.md
+1
-1
modules/opencode/skills/debugging/SKILL.md
+1
-1
modules/opencode/skills/debugging/SKILL.md
···
1
1
---
2
2
name: debugging
3
-
description: Load when debugging failures, errors, crashes, or unexpected behavior. Emphasizes empirical investigation over code reasoning.
3
+
description: Load when debugging failures, errors, crashes, or unexpected behavior. Triggers: "bug", "broken", "not working", "error", "crash", "failing test", "investigate", "debug". Emphasizes empirical investigation over code reasoning.
4
4
---
5
5
6
6
# Debugging Protocol
+133
modules/opencode/skills/decision-framework/SKILL.md
+133
modules/opencode/skills/decision-framework/SKILL.md
···
1
+
---
2
+
name: decision-framework
3
+
description: Load BEFORE implementing when you need to explore alternatives, surface blind spots, or produce a decision document. Triggers: "help me decide", "what are the options", "tradeoffs", "RFC", "design doc", "before I build this", "not sure which approach".
4
+
---
5
+
6
+
## Your Role
7
+
8
+
You are a thinking partner. Your job is to expand the user's understanding—not to produce a plan, but to help them see the full picture before they commit. Ask questions. Surface blind spots. Challenge assumptions.
9
+
10
+
## Workflow
11
+
12
+
### 1. Explore the Problem Space
13
+
14
+
You MUST NOT accept the first framing—the first interpretation is often incomplete or biased. Probe deeper.
15
+
16
+
- What's the **real** problem here? (vs symptom, vs proposed solution)
17
+
- Who is affected? What are their actual needs?
18
+
- What constraints are real vs assumed?
19
+
- What would "good enough" look like?
20
+
21
+
**Use targeted questions, not suggestions:**
22
+
- "Have you considered X?" not "You should do X"
23
+
- "What happens when Y?" not "Y will break"
24
+
- "Why this approach over Z?" not "Z is better"
25
+
26
+
### 2. Surface Alternatives
27
+
28
+
The user's first idea is rarely the only one. You MUST find others.
29
+
30
+
- What's the **simplest** thing that could work?
31
+
- What's the most **flexible**? **Fastest to ship**? **Easiest to undo**?
32
+
- How would someone with a different background approach this?
33
+
- What would you do if you had **half the time**? **Twice the time**?
34
+
35
+
### 3. Find the Blind Spots
36
+
37
+
You MUST identify what the user isn't thinking about.
38
+
39
+
- What dependencies does this touch that haven't been mentioned?
40
+
- What breaks if this goes wrong? **How badly?**
41
+
- What edge cases or failure modes are being overlooked?
42
+
- What does this look like at **10x scale**?
43
+
44
+
### 4. Make Tradeoffs Visible
45
+
46
+
You MUST help the user see what they're trading.
47
+
48
+
- What's being **optimized for**? What's being **sacrificed**?
49
+
- What becomes **harder** after this change?
50
+
- What **doors does this close**? Which does it **open**?
51
+
- Is this **reversible**? How expensive is **rollback**?
52
+
53
+
### 5. Produce a Decision Document
54
+
55
+
When analysis is complete, synthesize findings into an RFC-style document.
56
+
57
+
**Structure:**
58
+
```markdown
59
+
## Title
60
+
61
+
---
62
+
63
+
### Status
64
+
65
+
**Accepted** | Proposed | Deprecated
66
+
67
+
---
68
+
69
+
### Background
70
+
71
+
Context and motivation. Link to related issues/tickets.
72
+
73
+
---
74
+
75
+
### Problem Statement
76
+
77
+
What specific problem does this solve?
78
+
79
+
---
80
+
81
+
### Decision Table
82
+
83
+
| Decision | Choice | Rationale |
84
+
|----------|--------|-----------|
85
+
86
+
---
87
+
88
+
### Implementation
89
+
90
+
Code references, API contracts, sequence diagrams if helpful.
91
+
92
+
---
93
+
94
+
### Acceptance Criteria
95
+
96
+
- [ ] Criteria 1
97
+
- [ ] Criteria 2
98
+
99
+
---
100
+
101
+
### Unresolved
102
+
103
+
| Question | Owner |
104
+
|----------|-------|
105
+
| Open question | Team |
106
+
107
+
---
108
+
109
+
### References
110
+
111
+
- Related documents
112
+
- Code links (use full GitHub URLs)
113
+
```
114
+
115
+
## Proactive Skill Loading
116
+
117
+
Before diving into analysis, check if the problem domain matches a known skill and load it:
118
+
119
+
| Problem Type | Skill to Load |
120
+
|--------------|---------------|
121
+
| Software architecture, refactoring, adding abstractions | `software-architecture` |
122
+
| Debugging failures, errors, crashes | `debugging` |
123
+
124
+
## Know When to Stop
125
+
126
+
The goal is understanding, not endless analysis. You're done when:
127
+
128
+
- The user can explain the problem clearly
129
+
- Major alternatives have been explored
130
+
- Tradeoffs are explicit and accepted
131
+
- Unknowns are identified and owned
132
+
133
+
Then the user decides. Your job is to make that decision informed.
+125
modules/opencode/skills/mermaid-diagram-writing/SKILL.md
+125
modules/opencode/skills/mermaid-diagram-writing/SKILL.md
···
1
+
---
2
+
name: mermaid-diagram-writing
3
+
description: Load when writing ANY Mermaid diagram. Triggers: "sequence diagram", "flowchart", "visualize the flow", "draw the architecture", "show me how X works", "diagram", "mermaid".
4
+
---
5
+
6
+
# Mermaid Diagram Writing
7
+
8
+
## Core Rules
9
+
10
+
### 1. Keep Diagrams Simple
11
+
12
+
Avoid colored rectangles and complex styling. Use `theme: base` or let renderers use their default minimal style.
13
+
14
+
### 2. Prefer Many Small Diagrams Over One Big Diagram
15
+
16
+
**Bad** - One large diagram trying to show everything:
17
+
```mermaid
18
+
sequenceDiagram
19
+
participant A
20
+
participant B
21
+
participant C
22
+
participant D
23
+
participant E
24
+
A->>B: 1
25
+
B->>C: 2
26
+
C->>D: 3
27
+
D->>E: 4
28
+
-- lots more steps --
29
+
```
30
+
31
+
**Good** - Multiple focused diagrams:
32
+
```mermaid
33
+
sequenceDiagram
34
+
participant FE
35
+
participant BE
36
+
FE->>BE: Request
37
+
BE-->>FE: Response
38
+
```
39
+
40
+
### 3. Diagram Scope Guidelines
41
+
42
+
- **Max 4-5 participants** per diagram
43
+
- **Max 10-15 messages** per sequence diagram
44
+
- Each diagram should tell one coherent story
45
+
46
+
### 4. Participant Naming
47
+
48
+
- Use short, clear names: `FE`, `BE`, `DB`, `Provider`, `User`
49
+
- Avoid: `FrontendApplication`, `BackendService`
50
+
51
+
### 5. Use Structured Flow Control
52
+
53
+
Leverage `alt`/`else`, `loop`, and `opt`:
54
+
55
+
```mermaid
56
+
sequenceDiagram
57
+
participant FE
58
+
participant BE
59
+
FE->>BE: Request
60
+
alt Success
61
+
BE-->>FE: 200 OK
62
+
else Error
63
+
BE-->>FE: 400 Error
64
+
end
65
+
```
66
+
67
+
### 6. Consistent Message Patterns
68
+
69
+
- **Queries**: `Source->>Target: Action`
70
+
- **Responses**: `Target-->>Source: Result`
71
+
72
+
### 7. Label Everything
73
+
74
+
- Always label `alt`/`else` blocks
75
+
- Include status codes when relevant
76
+
77
+
## Common Patterns
78
+
79
+
### API Endpoint
80
+
```mermaid
81
+
sequenceDiagram
82
+
participant Client
83
+
participant Server
84
+
participant DB
85
+
Client->>Server: POST /resource
86
+
Server->>DB: Insert
87
+
DB-->>Server: Result
88
+
Server-->>Client: 201 Created
89
+
```
90
+
91
+
### Error Handling
92
+
```mermaid
93
+
sequenceDiagram
94
+
participant FE
95
+
participant BE
96
+
FE->>BE: Request
97
+
alt Valid
98
+
BE-->>FE: Success
99
+
else Invalid
100
+
BE-->>FE: 400 Error
101
+
end
102
+
```
103
+
104
+
### Conditional Flow
105
+
```mermaid
106
+
sequenceDiagram
107
+
participant FE
108
+
participant BE
109
+
participant Provider
110
+
FE->>BE: Check status
111
+
BE->>Provider: Verify
112
+
alt Exists
113
+
Provider-->>BE: found
114
+
BE-->>FE: { status: active }
115
+
else Not Found
116
+
Provider-->>BE: not found
117
+
BE-->>FE: { status: deleted }
118
+
end
119
+
```
120
+
121
+
## When to Split
122
+
123
+
- More than 5 participants
124
+
- More than 15 messages
125
+
- Multiple unrelated flows mixed together
-63
modules/opencode/skills/planning/SKILL.md
-63
modules/opencode/skills/planning/SKILL.md
···
1
-
---
2
-
name: planning
3
-
description: Load when designing solutions, planning features, or before significant work. Ensures thorough understanding and explicit tradeoffs.
4
-
---
5
-
6
-
## Your Role
7
-
8
-
You are a thinking partner. Your job is to expand the user's understanding—not to produce a plan, but to help them see the full picture before they commit. Ask questions. Surface blind spots. Challenge assumptions.
9
-
10
-
## Explore the Problem Space
11
-
12
-
You MUST NOT accept the first framing—the first interpretation is often incomplete or biased. Probe deeper.
13
-
14
-
- What's the real problem here? (vs symptom, vs proposed solution)
15
-
- Who is affected? What are their actual needs?
16
-
- What constraints are real vs assumed?
17
-
- What would "good enough" look like?
18
-
19
-
## Surface Alternatives
20
-
21
-
The user's first idea is rarely the only one. You MUST find others.
22
-
23
-
- What's the simplest thing that could work?
24
-
- What's the most flexible? Fastest to ship? Easiest to undo?
25
-
- How would someone with a different background approach this?
26
-
- What would you do if you had half the time? Twice the time?
27
-
28
-
## Find the Blind Spots
29
-
30
-
You MUST identify what the user isn't thinking about.
31
-
32
-
- What dependencies does this touch that haven't been mentioned?
33
-
- What breaks if this goes wrong? How badly?
34
-
- What edge cases or failure modes are being overlooked?
35
-
- What does this look like at 10x scale?
36
-
37
-
## Make Tradeoffs Visible
38
-
39
-
You MUST help the user see what they're trading.
40
-
41
-
- What's being optimized for? What's being sacrificed?
42
-
- What becomes harder after this change?
43
-
- What doors does this close? Which does it open?
44
-
- Is this reversible? How expensive is rollback?
45
-
46
-
## Ask, Don't Assume
47
-
48
-
You MUST prefer questions over suggestions.
49
-
50
-
- "Have you considered X?" not "You should do X"
51
-
- "What happens when Y?" not "Y will break"
52
-
- "Why this approach over Z?" not "Z is better"
53
-
54
-
## Know When to Stop
55
-
56
-
The goal is understanding, not endless analysis. You're done when:
57
-
58
-
- The user can explain the problem clearly
59
-
- Major alternatives have been explored
60
-
- Tradeoffs are explicit and accepted
61
-
- Unknowns are identified and owned
62
-
63
-
Then the user decides. Your job is to make that decision informed.
+1
-1
modules/opencode/skills/software-architecture/SKILL.md
+1
-1
modules/opencode/skills/software-architecture/SKILL.md
···
1
1
---
2
2
name: software-architecture
3
-
description: Load BEFORE implementing new features, refactoring, adding abstractions, writing RFCs/architecture docs, or any non-trivial code changes. Skip for simple bugfixes, typo fixes, or one-liners.
3
+
description: Load BEFORE any non-trivial code: new features, refactoring, adding abstractions. Triggers: "implement", "refactor", "add a layer", "design the API", "before I code this". Skip for one-liners and typo fixes.
4
4
---
5
5
6
6
## Deep Modules