solvdex 2.0.0-alpha.8 → 3.0.0-alpha.1
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/.claude-plugin/marketplace.json +3 -3
- package/.claude-plugin/plugin.json +2 -2
- package/README.md +52 -48
- package/agents/capture.md +74 -37
- package/agents/duplicate-checker.md +6 -6
- package/agents/graph.md +24 -22
- package/agents/health.md +20 -16
- package/agents/scanner.md +28 -19
- package/agents/searcher.md +7 -5
- package/agents/stats.md +3 -4
- package/agents/validator.md +6 -6
- package/docs/README.md +21 -10
- package/docs/architecture.md +27 -37
- package/docs/diagrams/architecture-overview.md +8 -11
- package/docs/diagrams/data-structures.md +2 -2
- package/docs/diagrams/knowledge-retrieval-flow.md +1 -1
- package/docs/diagrams/session-workflow.md +1 -1
- package/docs/diagrams/system-overview.md +4 -8
- package/docs/getting-started.md +9 -12
- package/docs/plans/2025-01-22-marketplace-distribution.md +2 -0
- package/docs/plans/2025-01-22-solvdex-design.md +2 -0
- package/docs/plans/2025-02-02-generic-wiki-v3.md +747 -0
- package/docs/schema.md +53 -29
- package/docs/templates/problems.md +141 -0
- package/docs/templates/references.md +171 -0
- package/docs/templates/solutions.md +156 -0
- package/docs/use-cases.md +40 -93
- package/docs/workflows.md +19 -21
- package/hooks/hooks.json +3 -3
- package/package.json +2 -2
- package/skills/wiki/SKILL.md +17 -29
- package/skills/wiki-add/SKILL.md +27 -27
- package/skills/wiki-export/SKILL.md +6 -6
- package/skills/wiki-fix/SKILL.md +1 -1
- package/skills/wiki-flag/SKILL.md +1 -1
- package/skills/wiki-graph/SKILL.md +14 -15
- package/skills/wiki-health/SKILL.md +29 -12
- package/skills/wiki-import/SKILL.md +1 -1
- package/skills/wiki-init/SKILL.md +15 -26
- package/skills/wiki-scan/SKILL.md +4 -5
- package/skills/wiki-search/SKILL.md +49 -23
- package/skills/wiki-stats/SKILL.md +26 -30
- package/agents/templates/docs.md +0 -35
- package/agents/templates/gotchas.md +0 -31
- package/agents/templates/issues.md +0 -36
- package/agents/templates/patterns.md +0 -35
- package/agents/templates/performance.md +0 -36
- package/agents/templates/security.md +0 -36
- package/agents/templates/testing.md +0 -39
- package/docs/plans/2025-02-02-implementation-tasks.md +0 -1211
- package/skills/wiki-browse/SKILL.md +0 -74
- package/skills/wiki-capture/SKILL.md +0 -121
- package/skills/wiki-explorer/SKILL.md +0 -93
- package/skills/wiki-status/SKILL.md +0 -53
- package/skills/wiki-test-trigger/SKILL.md +0 -97
- package/skills/wiki-validate/SKILL.md +0 -61
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
},
|
|
7
7
|
"metadata": {
|
|
8
8
|
"description": "Knowledge management plugins for Claude Code",
|
|
9
|
-
"version": "
|
|
9
|
+
"version": "3.0.0-alpha.1"
|
|
10
10
|
},
|
|
11
11
|
"plugins": [
|
|
12
12
|
{
|
|
@@ -15,8 +15,8 @@
|
|
|
15
15
|
"source": "url",
|
|
16
16
|
"url": "https://github.com/ducdmdev/solvdex.git"
|
|
17
17
|
},
|
|
18
|
-
"description": "
|
|
19
|
-
"version": "
|
|
18
|
+
"description": "Universal problem-solving journal - auto-capture and retrieve knowledge (problems, solutions, references)",
|
|
19
|
+
"version": "3.0.0-alpha.1"
|
|
20
20
|
}
|
|
21
21
|
]
|
|
22
22
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "solvdex",
|
|
3
|
-
"description": "
|
|
4
|
-
"version": "
|
|
3
|
+
"description": "Universal problem-solving journal - auto-captures and retrieves knowledge across problems, solutions, and references",
|
|
4
|
+
"version": "3.0.0-alpha.1",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "duc.do",
|
|
7
7
|
"email": "ducdm.dev.work@gmail.com"
|
package/README.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# Solvdex
|
|
2
2
|
|
|
3
3
|
[](./tests)
|
|
4
|
-
[](./package.json)
|
|
5
5
|
[](./LICENSE)
|
|
6
6
|
[](./docs/schema.md)
|
|
7
7
|
|
|
8
|
-
> **An index of solved problems.** A
|
|
8
|
+
> **An index of solved problems.** A personal problem-solving journal that auto-captures and retrieves knowledge across any domain.
|
|
9
9
|
|
|
10
10
|
```
|
|
11
11
|
+-------------------------------------------------------------+
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
|---------|-------------|
|
|
26
26
|
| **Auto-Capture** | Saves solutions when errors are resolved |
|
|
27
27
|
| **Auto-Lookup** | Surfaces relevant knowledge on errors |
|
|
28
|
-
| **
|
|
28
|
+
| **3 Folders** | Organized knowledge: problems, solutions, references |
|
|
29
29
|
| **Trigger Patterns** | Regex matching for automatic error detection |
|
|
30
30
|
| **Confidence Tracking** | Trust scores with decay over time |
|
|
31
31
|
| **Cross-References** | Link related entries and source files |
|
|
@@ -34,16 +34,16 @@
|
|
|
34
34
|
|
|
35
35
|
**Pure Agent Plugin - No Code Required**
|
|
36
36
|
|
|
37
|
-
Solvdex
|
|
37
|
+
Solvdex 3.0 uses a pure agent-based architecture. All logic is implemented in agent markdown files - no TypeScript compilation needed. Fixed templates per folder ensure consistency. See [docs/templates/](./docs/templates/).
|
|
38
38
|
|
|
39
39
|
> **[View Architecture Diagram](./docs/diagrams/architecture-overview.md)**
|
|
40
40
|
|
|
41
41
|
| Layer | Components |
|
|
42
42
|
|-------|------------|
|
|
43
|
-
| **Skills (
|
|
44
|
-
| **Hooks** | SessionStart →
|
|
43
|
+
| **Skills (12)** | `/wiki search`, `/wiki add`, `/wiki health`, etc. |
|
|
44
|
+
| **Hooks** | SessionStart → entry count, PreToolUse → context hints, Stop → capture prompt |
|
|
45
45
|
| **Agents (8)** | searcher, capture, scanner, validator, stats, health, graph, duplicate-checker |
|
|
46
|
-
| **Storage** | `.wiki/` with
|
|
46
|
+
| **Storage** | `.wiki/` with 3 universal folders |
|
|
47
47
|
|
|
48
48
|
## Project Structure
|
|
49
49
|
|
|
@@ -57,26 +57,22 @@ solvdex/
|
|
|
57
57
|
│ ├── stats.md
|
|
58
58
|
│ ├── duplicate-checker.md
|
|
59
59
|
│ ├── health.md
|
|
60
|
-
│
|
|
61
|
-
│ └── templates/ # Category templates
|
|
60
|
+
│ └── graph.md
|
|
62
61
|
├── skills/ # 18 Claude Code skills (thin wrappers)
|
|
63
62
|
├── hooks/ # hooks.json (prompt-based hints)
|
|
64
63
|
├── docs/ # Documentation
|
|
65
|
-
│
|
|
64
|
+
│ ├── schema.md # Entry schema & constants (source of truth)
|
|
65
|
+
│ └── templates/ # Fixed templates per folder
|
|
66
66
|
└── tests/ # Validation tests
|
|
67
67
|
```
|
|
68
68
|
|
|
69
|
-
##
|
|
69
|
+
## Folders
|
|
70
70
|
|
|
71
71
|
```
|
|
72
72
|
.wiki/
|
|
73
|
-
├──
|
|
74
|
-
├──
|
|
75
|
-
|
|
76
|
-
├── testing/ # Test strategies, mocks
|
|
77
|
-
├── docs/ # Documentation guides
|
|
78
|
-
├── security/ # Auth, vulnerabilities
|
|
79
|
-
└── performance/ # Optimizations, benchmarks
|
|
73
|
+
├── problems/ # What went wrong - bugs, errors, gotchas
|
|
74
|
+
├── solutions/ # How to fix/do things - patterns, recipes
|
|
75
|
+
└── references/ # Things to remember - docs, configs
|
|
80
76
|
```
|
|
81
77
|
|
|
82
78
|
## Quick Start
|
|
@@ -89,10 +85,10 @@ solvdex/
|
|
|
89
85
|
/wiki search "database timeout"
|
|
90
86
|
|
|
91
87
|
# Add current solution
|
|
92
|
-
/wiki add --
|
|
88
|
+
/wiki add --folder=problems
|
|
93
89
|
|
|
94
|
-
# Browse entries
|
|
95
|
-
/wiki
|
|
90
|
+
# Browse all entries
|
|
91
|
+
/wiki search
|
|
96
92
|
```
|
|
97
93
|
|
|
98
94
|
## Commands
|
|
@@ -102,30 +98,26 @@ solvdex/
|
|
|
102
98
|
| Command | Description |
|
|
103
99
|
|---------|-------------|
|
|
104
100
|
| `/wiki init` | Create `.wiki/` structure |
|
|
105
|
-
| `/wiki add` |
|
|
106
|
-
| `/wiki search
|
|
107
|
-
| `/wiki browse` | List entries with filters |
|
|
101
|
+
| `/wiki add` | Capture knowledge from conversation |
|
|
102
|
+
| `/wiki search [query]` | Search or browse entries (no query = list all) |
|
|
108
103
|
|
|
109
|
-
###
|
|
104
|
+
### Analysis Commands
|
|
110
105
|
|
|
111
106
|
| Command | Description |
|
|
112
107
|
|---------|-------------|
|
|
113
|
-
| `/wiki
|
|
114
|
-
| `/wiki
|
|
115
|
-
| `/wiki validate` | Check for issues |
|
|
108
|
+
| `/wiki stats [--quick]` | Statistics and health score |
|
|
109
|
+
| `/wiki health [--validate]` | Health analysis with validation |
|
|
116
110
|
| `/wiki scan` | Generate stubs from project |
|
|
117
|
-
| `/wiki flag <entry>` | Mark for review |
|
|
118
|
-
| `/wiki fix <entry>` | Update flagged entry |
|
|
119
|
-
| `/wiki health` | Coverage gaps and health analysis |
|
|
120
111
|
| `/wiki graph` | Relationship diagrams |
|
|
121
112
|
|
|
122
|
-
###
|
|
113
|
+
### Entry Management
|
|
123
114
|
|
|
124
115
|
| Command | Description |
|
|
125
116
|
|---------|-------------|
|
|
117
|
+
| `/wiki flag <entry>` | Mark for review |
|
|
118
|
+
| `/wiki fix <entry>` | Update flagged entry |
|
|
126
119
|
| `/wiki export [file]` | Export to JSON |
|
|
127
120
|
| `/wiki import <file>` | Import from JSON |
|
|
128
|
-
| `/wiki test-trigger` | Test regex patterns |
|
|
129
121
|
|
|
130
122
|
### Agents
|
|
131
123
|
|
|
@@ -133,14 +125,14 @@ All logic is implemented by specialized agents:
|
|
|
133
125
|
|
|
134
126
|
| Agent | Commands | Description |
|
|
135
127
|
|-------|----------|-------------|
|
|
136
|
-
| `searcher` | `/wiki search
|
|
137
|
-
| `capture` | `/wiki add`, `/wiki
|
|
128
|
+
| `searcher` | `/wiki search` | Search + browse |
|
|
129
|
+
| `capture` | `/wiki add`, `/wiki fix` | Knowledge extraction |
|
|
138
130
|
| `scanner` | `/wiki scan` | Project scanning |
|
|
139
|
-
| `validator` | `/wiki
|
|
131
|
+
| `validator` | `/wiki flag` | Quality checks |
|
|
140
132
|
| `stats` | `/wiki stats` | Analytics + maturity |
|
|
141
|
-
| `
|
|
142
|
-
| `health` | `/wiki health` | Coverage gaps |
|
|
133
|
+
| `health` | `/wiki health` | Coverage gaps + validation |
|
|
143
134
|
| `graph` | `/wiki graph` | Relationship diagrams |
|
|
135
|
+
| `duplicate-checker` | (internal) | Prevent duplicates |
|
|
144
136
|
|
|
145
137
|
## How It Works
|
|
146
138
|
|
|
@@ -153,9 +145,9 @@ All logic is implemented by specialized agents:
|
|
|
153
145
|
+--------------+ +--------------+ +--------------+
|
|
154
146
|
|
|
155
147
|
Signals detected:
|
|
156
|
-
- error_resolved ->
|
|
157
|
-
- workaround ->
|
|
158
|
-
- user confirms -> auto-detect
|
|
148
|
+
- error_resolved -> problems/
|
|
149
|
+
- workaround -> solutions/
|
|
150
|
+
- user confirms -> auto-detect folder
|
|
159
151
|
- explicit save -> "remember this"
|
|
160
152
|
```
|
|
161
153
|
|
|
@@ -170,7 +162,7 @@ Signals detected:
|
|
|
170
162
|
Lookup triggers:
|
|
171
163
|
- Session start -> relevant context
|
|
172
164
|
- Error match -> trigger patterns
|
|
173
|
-
- Prompt keywords ->
|
|
165
|
+
- Prompt keywords -> folder detection
|
|
174
166
|
```
|
|
175
167
|
|
|
176
168
|
## Entry Format
|
|
@@ -179,10 +171,20 @@ Lookup triggers:
|
|
|
179
171
|
---
|
|
180
172
|
title: Database Connection Timeout
|
|
181
173
|
created: 2025-01-20
|
|
174
|
+
updated: 2025-01-20
|
|
182
175
|
status: active
|
|
183
176
|
confidence: 85
|
|
177
|
+
maturity: verified
|
|
184
178
|
tags: [database, timeout, postgres]
|
|
185
179
|
trigger: "ETIMEDOUT.*postgres"
|
|
180
|
+
use_count: 5
|
|
181
|
+
last_used: 2025-01-20
|
|
182
|
+
related_entries:
|
|
183
|
+
- .wiki/solutions/connection-pool-config.md
|
|
184
|
+
audit:
|
|
185
|
+
- date: 2025-01-20
|
|
186
|
+
action: created
|
|
187
|
+
by: user
|
|
186
188
|
---
|
|
187
189
|
|
|
188
190
|
## Problem
|
|
@@ -192,11 +194,11 @@ Connection times out after 30 seconds...
|
|
|
192
194
|
Increase timeout and add connection pool...
|
|
193
195
|
|
|
194
196
|
## Related
|
|
195
|
-
- [[
|
|
197
|
+
- [[solutions/connection-pool-config]]
|
|
196
198
|
- `src/db/config.ts:45`
|
|
197
199
|
```
|
|
198
200
|
|
|
199
|
-
> **Note:** For complete schema details including all fields, maturity levels, and constants, see [docs/schema.md](./docs/schema.md).
|
|
201
|
+
> **Note:** For complete schema details including all fields, maturity levels, and constants, see [docs/schema.md](./docs/schema.md). For entry templates, see [docs/templates/](./docs/templates/).
|
|
200
202
|
|
|
201
203
|
### Entry Maturity System
|
|
202
204
|
|
|
@@ -235,10 +237,11 @@ Confidence auto-decays for entries unused for 90+ days.
|
|
|
235
237
|
|
|
236
238
|
Real-time integration with Claude Code via contextual prompts:
|
|
237
239
|
|
|
238
|
-
| Hook |
|
|
239
|
-
|
|
240
|
-
| `SessionStart` |
|
|
241
|
-
| `
|
|
240
|
+
| Hook | When | Purpose |
|
|
241
|
+
|------|------|---------|
|
|
242
|
+
| `SessionStart` | New conversation | Shows entry count, hints to use `/wiki search` |
|
|
243
|
+
| `PreToolUse` | Before Edit/Write | Shows problems/solutions count for context |
|
|
244
|
+
| `Stop` | Task completes | Hint to capture valuable knowledge |
|
|
242
245
|
|
|
243
246
|
Hooks are configured in `hooks/hooks.json` and provide prompt-based guidance to use wiki agents.
|
|
244
247
|
|
|
@@ -272,6 +275,7 @@ npm run test:watch # Watch mode
|
|
|
272
275
|
| Document | Description |
|
|
273
276
|
|----------|-------------|
|
|
274
277
|
| [Schema Reference](./docs/schema.md) | Entry schema & constants (source of truth) |
|
|
278
|
+
| [Entry Templates](./docs/templates/) | Fixed templates per folder |
|
|
275
279
|
| [Getting Started](./docs/getting-started.md) | Quick setup guide |
|
|
276
280
|
| [Architecture](./docs/architecture.md) | System design |
|
|
277
281
|
| [Workflows](./docs/workflows.md) | Hook and skill flows |
|
package/agents/capture.md
CHANGED
|
@@ -14,10 +14,11 @@ tools:
|
|
|
14
14
|
For entry structure, validation rules, and constants, see: `docs/schema.md`
|
|
15
15
|
|
|
16
16
|
Key references:
|
|
17
|
-
- Entry frontmatter fields: `docs/schema.md#
|
|
17
|
+
- Entry frontmatter fields: `docs/schema.md#entryfrontmatter`
|
|
18
18
|
- Maturity rules: `docs/schema.md#maturity-rules`
|
|
19
|
-
- Confidence levels: `docs/schema.md#confidence-
|
|
20
|
-
-
|
|
19
|
+
- Confidence levels: `docs/schema.md#confidence-constants`
|
|
20
|
+
- Folders: `docs/schema.md#default-folders`
|
|
21
|
+
- Entry Templates: `docs/templates/` (problems.md, solutions.md, references.md)
|
|
21
22
|
|
|
22
23
|
Intelligently extract problem and solution from conversation context to create a wiki entry.
|
|
23
24
|
|
|
@@ -30,7 +31,7 @@ You will receive conversation context containing:
|
|
|
30
31
|
|
|
31
32
|
Optional parameters:
|
|
32
33
|
- `mode: "auto-capture"` - Auto-capture from conversation (hook)
|
|
33
|
-
- `
|
|
34
|
+
- `folder: "<folder>"` - Force specific folder (problems, solutions, references)
|
|
34
35
|
- `title: "<title>"` - Force specific title
|
|
35
36
|
|
|
36
37
|
## Process
|
|
@@ -58,9 +59,9 @@ Include relevant code snippets (max 20 lines).
|
|
|
58
59
|
|
|
59
60
|
**IMPORTANT: Always check before creating!**
|
|
60
61
|
|
|
61
|
-
1. Search existing entries in detected
|
|
62
|
+
1. Search existing entries in detected folder:
|
|
62
63
|
```
|
|
63
|
-
Glob .wiki/<
|
|
64
|
+
Glob .wiki/<folder>/*.md
|
|
64
65
|
```
|
|
65
66
|
|
|
66
67
|
2. Compare semantically:
|
|
@@ -70,29 +71,29 @@ Include relevant code snippets (max 20 lines).
|
|
|
70
71
|
|
|
71
72
|
3. If >80% similarity found:
|
|
72
73
|
```
|
|
73
|
-
Similar entry exists:
|
|
74
|
-
Consider updating it instead: /wiki fix
|
|
74
|
+
Similar entry exists: folder/existing-entry.md
|
|
75
|
+
Consider updating it instead: /wiki fix folder/existing-entry.md
|
|
75
76
|
```
|
|
76
77
|
Do NOT create new entry.
|
|
77
78
|
|
|
78
79
|
4. If 50-79% similarity:
|
|
79
80
|
```
|
|
80
|
-
Related entry found:
|
|
81
|
+
Related entry found: folder/related-entry.md
|
|
81
82
|
Creating new entry and linking to related.
|
|
82
83
|
```
|
|
83
84
|
Create entry with `related_entries` field.
|
|
84
85
|
|
|
85
|
-
### Step 4: Determine
|
|
86
|
+
### Step 4: Determine Folder
|
|
86
87
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
|
90
|
-
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
95
|
-
|
|
88
|
+
Analyze content to determine the appropriate folder:
|
|
89
|
+
|
|
90
|
+
| Content Analysis | Folder |
|
|
91
|
+
|------------------|--------|
|
|
92
|
+
| Problem encountered, error, failure, blocker, bug, crash, exception, pitfall, gotcha, warning, careful, avoid, security issue | problems/ |
|
|
93
|
+
| How-to, procedure, recipe, pattern, template, approach, optimization, test strategy, workflow, steps to do something | solutions/ |
|
|
94
|
+
| Documentation, reference, config, link, guide, API docs, notes, information to remember | references/ |
|
|
95
|
+
|
|
96
|
+
**AI decides automatically.** If genuinely uncertain (>30% confidence in multiple folders), default to `problems/` for issues or `references/` for informational content.
|
|
96
97
|
|
|
97
98
|
### Step 5: Generate Tags
|
|
98
99
|
|
|
@@ -119,34 +120,70 @@ Create a concise, descriptive title:
|
|
|
119
120
|
- Include technology: "TypeScript Generic Constraint Issue"
|
|
120
121
|
- Max 60 characters
|
|
121
122
|
|
|
122
|
-
### Step 7: Create Entry Using Template
|
|
123
|
+
### Step 7: Create Entry Using Fixed Template
|
|
123
124
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
125
|
+
**Use the fixed template for the target folder.** See `docs/templates/` for full templates.
|
|
126
|
+
|
|
127
|
+
1. **Select template** based on folder:
|
|
128
|
+
|
|
129
|
+
| Folder | Template Sections |
|
|
130
|
+
|--------|-------------------|
|
|
131
|
+
| `problems/` | Problem, Cause, Solution, Prevention, Related |
|
|
132
|
+
| `solutions/` | Overview, Prerequisites, Steps, Example, Related |
|
|
133
|
+
| `references/` | Summary, Details, Links, Related |
|
|
134
|
+
|
|
135
|
+
2. **Fill frontmatter**:
|
|
136
|
+
|
|
137
|
+
```yaml
|
|
138
|
+
---
|
|
139
|
+
title: {{generated_title}}
|
|
140
|
+
created: {{today YYYY-MM-DD}}
|
|
141
|
+
updated: {{today YYYY-MM-DD}}
|
|
142
|
+
status: active
|
|
143
|
+
confidence: 40
|
|
144
|
+
maturity: captured
|
|
145
|
+
tags: [{{extracted_tags}}]
|
|
146
|
+
trigger: "{{error_regex}}" # problems/ only
|
|
147
|
+
source: capture-agent
|
|
148
|
+
use_count: 0
|
|
149
|
+
audit:
|
|
150
|
+
- date: {{today YYYY-MM-DD}}
|
|
151
|
+
action: created
|
|
152
|
+
by: capture-agent
|
|
153
|
+
---
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
3. **Fill template sections** with extracted content:
|
|
157
|
+
|
|
158
|
+
**For problems/**:
|
|
159
|
+
- Problem: The error or issue encountered
|
|
160
|
+
- Cause: Root cause analysis
|
|
161
|
+
- Solution: Fix steps or code
|
|
162
|
+
- Prevention: How to avoid in future
|
|
163
|
+
|
|
164
|
+
**For solutions/**:
|
|
165
|
+
- Overview: What this does and when to use
|
|
166
|
+
- Prerequisites: What's needed first
|
|
167
|
+
- Steps: Numbered procedure
|
|
168
|
+
- Example: Code or config sample
|
|
128
169
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
- `{{tags}}` → comma-separated tags
|
|
134
|
-
- `{{trigger}}` → error regex pattern (issues/security/performance only)
|
|
135
|
-
- `{{source}}` → "conversation" or "capture-agent"
|
|
136
|
-
- `{{created_by}}` → "capture-agent"
|
|
137
|
-
- Section placeholders → extracted content
|
|
170
|
+
**For references/**:
|
|
171
|
+
- Summary: Brief description
|
|
172
|
+
- Details: Information to remember
|
|
173
|
+
- Links: External resources
|
|
138
174
|
|
|
139
|
-
|
|
175
|
+
4. **Write to** `.wiki/<folder>/<slug>.md`
|
|
140
176
|
|
|
141
177
|
### Step 8: Return Confirmation
|
|
142
178
|
|
|
143
179
|
```
|
|
144
|
-
Captured:
|
|
180
|
+
Captured: folder/entry-name.md
|
|
145
181
|
Title: Entry Title
|
|
182
|
+
Folder: problems | solutions | references
|
|
146
183
|
Tags: tag1, tag2, tag3
|
|
147
184
|
Confidence: 40 (captured)
|
|
148
185
|
|
|
149
|
-
Edit: /wiki fix
|
|
186
|
+
Edit: /wiki fix folder/entry-name.md
|
|
150
187
|
```
|
|
151
188
|
|
|
152
189
|
## Important Rules
|
|
@@ -156,5 +193,5 @@ Captured: category/entry-name.md
|
|
|
156
193
|
3. **Include code** - solutions need concrete examples
|
|
157
194
|
4. **Keep it concise** - problem/solution should be scannable
|
|
158
195
|
5. **Set confidence 40** - captured entries start at maturity baseline
|
|
159
|
-
6. **Add trigger patterns** - for
|
|
196
|
+
6. **Add trigger patterns** - for problems folder, extract regex
|
|
160
197
|
7. **Link related entries** - build the knowledge graph
|
|
@@ -16,7 +16,7 @@ Key references:
|
|
|
16
16
|
- Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
|
|
17
17
|
- Maturity rules: `docs/schema.md#maturity-rules`
|
|
18
18
|
- Confidence levels: `docs/schema.md#confidence-levels`
|
|
19
|
-
-
|
|
19
|
+
- Folders: `docs/schema.md#default-folders`
|
|
20
20
|
|
|
21
21
|
Detect potential duplicate entries before creation.
|
|
22
22
|
|
|
@@ -26,14 +26,14 @@ Detect potential duplicate entries before creation.
|
|
|
26
26
|
{
|
|
27
27
|
"title": "Database Connection Timeout",
|
|
28
28
|
"tags": ["database", "timeout", "postgres"],
|
|
29
|
-
"
|
|
29
|
+
"folder": "problems",
|
|
30
30
|
"contentSummary": "Fix for connection pool exhaustion..."
|
|
31
31
|
}
|
|
32
32
|
```
|
|
33
33
|
|
|
34
34
|
## Process
|
|
35
35
|
|
|
36
|
-
1. Load existing entries in same
|
|
36
|
+
1. Load existing entries in same folder
|
|
37
37
|
2. Compare semantically:
|
|
38
38
|
- Title similarity (exact, partial, synonym)
|
|
39
39
|
- Tag overlap (Jaccard similarity)
|
|
@@ -48,7 +48,7 @@ Detect potential duplicate entries before creation.
|
|
|
48
48
|
{
|
|
49
49
|
"isDuplicate": true,
|
|
50
50
|
"similarity": 85,
|
|
51
|
-
"matchedEntry": "
|
|
51
|
+
"matchedEntry": "problems/db-timeout.md",
|
|
52
52
|
"matchedTitle": "Database Timeout Fix",
|
|
53
53
|
"reason": "Very similar title and tags",
|
|
54
54
|
"suggestion": "Consider updating existing entry instead"
|
|
@@ -60,7 +60,7 @@ Detect potential duplicate entries before creation.
|
|
|
60
60
|
{
|
|
61
61
|
"isDuplicate": false,
|
|
62
62
|
"similarity": 20,
|
|
63
|
-
"closestMatch": "
|
|
63
|
+
"closestMatch": "problems/connection-error.md",
|
|
64
64
|
"suggestion": "Safe to create new entry"
|
|
65
65
|
}
|
|
66
66
|
```
|
|
@@ -94,5 +94,5 @@ Detect potential duplicate entries before creation.
|
|
|
94
94
|
|
|
95
95
|
1. Be conservative - prefer false positives over duplicates
|
|
96
96
|
2. Consider synonyms (e.g., "timeout" ≈ "connection timeout")
|
|
97
|
-
3. Same
|
|
97
|
+
3. Same folder increases likelihood
|
|
98
98
|
4. Different maturity levels can coexist (stub vs detailed)
|
package/agents/graph.md
CHANGED
|
@@ -12,17 +12,17 @@ Generate visual relationship diagrams for wiki entries.
|
|
|
12
12
|
## Input
|
|
13
13
|
|
|
14
14
|
- `{ "full": true }` - All entries
|
|
15
|
-
- `{ "
|
|
16
|
-
- `{ "entry": "
|
|
15
|
+
- `{ "folder": "problems" }` - Single folder
|
|
16
|
+
- `{ "entry": "problems/db-timeout.md" }` - Single entry and its relations
|
|
17
17
|
|
|
18
18
|
## Process
|
|
19
19
|
|
|
20
20
|
1. Load entries (all or filtered)
|
|
21
21
|
2. Extract relationships:
|
|
22
22
|
- **Explicit**: `related_entries` field
|
|
23
|
-
- **Wiki links**: `[[
|
|
23
|
+
- **Wiki links**: `[[folder/entry]]` in content
|
|
24
24
|
- **Tag overlap**: 2+ shared tags
|
|
25
|
-
- **Same
|
|
25
|
+
- **Same folder**: Weak connection
|
|
26
26
|
3. Generate Mermaid diagram
|
|
27
27
|
|
|
28
28
|
## Output Format
|
|
@@ -30,32 +30,34 @@ Generate visual relationship diagrams for wiki entries.
|
|
|
30
30
|
### Full Graph
|
|
31
31
|
```mermaid
|
|
32
32
|
graph LR
|
|
33
|
-
subgraph
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
33
|
+
subgraph problems
|
|
34
|
+
P1[DB Timeout]
|
|
35
|
+
P2[Auth Error]
|
|
36
|
+
P3[Connection Pool Gotcha]
|
|
37
37
|
end
|
|
38
38
|
|
|
39
|
-
subgraph
|
|
40
|
-
|
|
41
|
-
|
|
39
|
+
subgraph solutions
|
|
40
|
+
S1[Retry Pattern]
|
|
41
|
+
S2[Circuit Breaker]
|
|
42
|
+
S3[Pool Config]
|
|
42
43
|
end
|
|
43
44
|
|
|
44
|
-
subgraph
|
|
45
|
-
|
|
45
|
+
subgraph references
|
|
46
|
+
R1[API Docs]
|
|
47
|
+
R2[Config Guide]
|
|
46
48
|
end
|
|
47
49
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
50
|
+
P1 -->|related| S1
|
|
51
|
+
P1 -->|related| P3
|
|
52
|
+
P2 -->|same-tag: auth| S2
|
|
53
|
+
S1 -.->|same-folder| S2
|
|
54
|
+
P3 -->|wiki-link| S3
|
|
53
55
|
```
|
|
54
56
|
|
|
55
|
-
###
|
|
57
|
+
### Folder Graph
|
|
56
58
|
```mermaid
|
|
57
59
|
graph TD
|
|
58
|
-
subgraph
|
|
60
|
+
subgraph problems
|
|
59
61
|
A[DB Timeout]
|
|
60
62
|
B[Auth Error]
|
|
61
63
|
C[API Failure]
|
|
@@ -84,7 +86,7 @@ graph TD
|
|
|
84
86
|
| related | `-->` solid | Explicit related_entries |
|
|
85
87
|
| wiki-link | `-->` solid | [[link]] in content |
|
|
86
88
|
| same-tag | `-->` labeled | 2+ shared tags |
|
|
87
|
-
| same-
|
|
89
|
+
| same-folder | `-.->` dashed | Same folder |
|
|
88
90
|
|
|
89
91
|
## Node Styling
|
|
90
92
|
|
|
@@ -101,5 +103,5 @@ Based on confidence:
|
|
|
101
103
|
## Graph Limits
|
|
102
104
|
|
|
103
105
|
- Full graph: Max 50 entries (summarize if more)
|
|
104
|
-
-
|
|
106
|
+
- Folder: Max 20 entries
|
|
105
107
|
- Entry focus: Max 2 levels deep
|
package/agents/health.md
CHANGED
|
@@ -16,7 +16,7 @@ Key references:
|
|
|
16
16
|
- Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
|
|
17
17
|
- Maturity rules: `docs/schema.md#maturity-rules`
|
|
18
18
|
- Confidence levels: `docs/schema.md#confidence-levels`
|
|
19
|
-
-
|
|
19
|
+
- Folders: `docs/schema.md#default-folders`
|
|
20
20
|
|
|
21
21
|
Comprehensive wiki health analysis and recommendations.
|
|
22
22
|
|
|
@@ -31,7 +31,7 @@ Comprehensive wiki health analysis and recommendations.
|
|
|
31
31
|
- Orphaned: No tags, no related entries
|
|
32
32
|
- Broken links: [[link]] to non-existent entry
|
|
33
33
|
3. **Find coverage gaps**:
|
|
34
|
-
-
|
|
34
|
+
- Folders with < 3 entries
|
|
35
35
|
- Common error patterns without entries
|
|
36
36
|
4. **Generate recommendations**
|
|
37
37
|
|
|
@@ -45,29 +45,28 @@ Comprehensive wiki health analysis and recommendations.
|
|
|
45
45
|
## Issues Found
|
|
46
46
|
|
|
47
47
|
### Stale Entries (5)
|
|
48
|
-
-
|
|
49
|
-
-
|
|
48
|
+
- solutions/old-api.md (120 days)
|
|
49
|
+
- problems/legacy-auth.md (95 days)
|
|
50
50
|
→ Consider reviewing or deprecating
|
|
51
51
|
|
|
52
52
|
### Stub Entries (3)
|
|
53
|
-
-
|
|
54
|
-
-
|
|
53
|
+
- problems/api-timeout.md - Missing Solution
|
|
54
|
+
- problems/edge-case.md - Missing Problem
|
|
55
55
|
→ Run /wiki fix <entry> to complete
|
|
56
56
|
|
|
57
57
|
### Low Confidence (4)
|
|
58
|
-
-
|
|
58
|
+
- solutions/untested.md (confidence: 30)
|
|
59
59
|
→ Verify and increase confidence
|
|
60
60
|
|
|
61
61
|
### Missing Triggers (2)
|
|
62
|
-
-
|
|
63
|
-
-
|
|
62
|
+
- problems/db-error.md
|
|
63
|
+
- problems/auth-fail.md
|
|
64
64
|
→ Add trigger patterns for auto-matching
|
|
65
65
|
|
|
66
66
|
## Coverage Gaps
|
|
67
67
|
|
|
68
|
-
### Underserved
|
|
69
|
-
-
|
|
70
|
-
- performance: 2 entries (recommend: 3+)
|
|
68
|
+
### Underserved Folders
|
|
69
|
+
- references: 1 entry (recommend: 2+)
|
|
71
70
|
|
|
72
71
|
### Suggested Entries
|
|
73
72
|
Based on common errors, consider adding:
|
|
@@ -79,8 +78,8 @@ Based on common errors, consider adding:
|
|
|
79
78
|
|
|
80
79
|
1. Review 5 stale entries
|
|
81
80
|
2. Complete 3 stub entries
|
|
82
|
-
3. Add triggers to 2
|
|
83
|
-
4. Expand
|
|
81
|
+
3. Add triggers to 2 problems
|
|
82
|
+
4. Expand references folder
|
|
84
83
|
```
|
|
85
84
|
|
|
86
85
|
## Health Indicators
|
|
@@ -102,12 +101,17 @@ Based on common errors, consider adding:
|
|
|
102
101
|
|
|
103
102
|
## Coverage Analysis
|
|
104
103
|
|
|
105
|
-
For each
|
|
104
|
+
For each folder:
|
|
106
105
|
1. Count entries
|
|
107
106
|
2. Compare to minimum (3)
|
|
108
107
|
3. Flag if under-served
|
|
109
108
|
|
|
110
|
-
Recommend expanding
|
|
109
|
+
Recommend expanding folders with:
|
|
111
110
|
- High error rates in project
|
|
112
111
|
- Recent user questions
|
|
113
112
|
- Common patterns in codebase
|
|
113
|
+
|
|
114
|
+
### Minimum Recommendations
|
|
115
|
+
- problems: 3+ entries
|
|
116
|
+
- solutions: 3+ entries
|
|
117
|
+
- references: 2+ entries
|