| name | knowledge |
| description | Instructions for contextual knowledge retrieval, tagging, search, and rating. Referenced by plan-session, implementation-session, and review-pr-comments-session skills.
|
Knowledge Operations
Purpose
Knowledge captures gotchas, buried constraints, hidden invariants, and facts not in AGENTS.md/CLAUDE.md — things a future agent would otherwise waste time rediscovering. It is not a work log, a changelog, or a duplicate of documentation that already exists. If the fact is in AGENTS.md, CLAUDE.md, or derivable from git log/git blame, do not add it.
Contextual retrieval
Do not dump all knowledge at session start. Instead, search for entries
relevant to your current task:
wade knowledge get --search "worktree safety"
wade knowledge get --tag git
wade knowledge get --search "error handling" --tag testing
When both --search and --tag are provided, entries matching either
criterion are returned (OR semantics).
Only fall back to wade knowledge get (no filters) if you need a broad overview
or the knowledge base is small.
Search syntax
The --search flag accepts boolean queries:
| Syntax | Meaning |
|---|
term | Entries containing the term (case-insensitive) |
"exact phrase" | Entries containing the exact phrase |
term1 AND term2 | Both terms must appear |
term1 OR term2 | Either term may appear |
NOT term | Exclude entries containing the term |
(a OR b) AND c | Parentheses for grouping |
worktree safety | Bare space = implicit AND |
Tagging
When to tag
Tag entries when they relate to specific topics that future sessions might
search for. Good tags describe the domain (e.g. git, testing,
ci, error-handling), not the action (avoid fix, add, update).
Tag format
- Lowercase kebab-case:
git, worktree-safety, error-handling
- Alphanumeric + hyphens only, no spaces
- Max 30 characters per tag
Adding tags
When creating an entry:
echo "Learning" | wade knowledge add --session plan --tag git --tag worktree
Managing tags on existing entries:
wade knowledge tag add <entry-id> <tag>
wade knowledge tag remove <entry-id> <tag>
wade knowledge tag list
wade knowledge tag list <entry-id>
Rating
For each entry you open and evaluate, make an explicit decision per the decision tree below — not per search call. A broad search returning many results does not force you to rate all of them; only entries you actually read and assessed require a decision. Rate up/down when appropriate; otherwise intentionally leave the entry unrated.
wade knowledge rate <entry-id> up
wade knowledge rate <entry-id> down
wade knowledge rate <entry-id> stale
How to decide:
-
Was your search appropriate (correct tags/text)?
- No → do not rate. The issue is your search, not the entry.
-
Search was appropriate; entry came back legitimately:
- Useful for your task → rate up.
- Correct content but not applicable to your task → do not rate (entry is fine; refine future searches).
- Outdated / no longer applies → rate stale. Two stale votes hide the entry by default;
--no-filter still shows it.
- Incorrect or misleading → rate down.
- Tags or terminology are wrong/missing (content itself is correct) → do not rate down — fix tags via
wade knowledge tag add/remove <id> <tag>. Downvoting good content for tag problems mis-signals the auto-pruner.
-
Entry surfaced due to a known parser/search bug → do not rate; flag as a system issue.
Entry style
Write entries that are easy to scan and reuse across sessions:
- One insight per entry — no multi-topic dumps; split if needed
- Lead with the key fact — state the finding first, context second
- ≤3 sentences — if longer, split into separate entries
- No preamble or hedging — omit "I noticed that…", "It turned out that…"
- Active voice, present tense — "Use X when Y", not "It was found that X should be used"
Before (verbose, hedged):
I noticed during testing that it turned out the sync command needs to be run after all commits are staged, otherwise it may fail with a dirty-tree error in some cases.
After (concise, direct):
Run wade implementation-session sync only after all changes are committed — a dirty worktree causes exit code 4.
Adding entries
Knowledge is not a changelog — it is a searchable store of facts, gotchas, and limitations that help future agents avoid scanning the codebase. Only capture what is non-obvious or hard to derive from the code or git history:
- Non-obvious constraints, gotchas, and footguns
- Known limitations and their workarounds
- Patterns with a WHY that code alone can't explain
- Pointers to where a rule or config lives when the location isn't obvious
DO NOT capture:
- Completed-work summaries: "We added X feature in this session", "Implemented Y in PR #N" — this duplicates
git log.
- Refactor or fix histories: "Fixed bug Z by doing W" — derivable from
git blame / git log.
- Content already in
AGENTS.md or CLAUDE.md: anything that is documented there does not need a knowledge entry.
- Anything reconstructable from
git log, git blame, or reading the current source — if a future agent can find it in 10 seconds, it doesn't belong here.
Entry dates (shown in search results) indicate freshness — rate an entry stale if it no longer applies (two stale votes hide it by default; use --no-filter to still show it).
echo "Your learnings here" | wade knowledge add --session <type> --issue <number> --tag <topic>
If a new entry corrects or replaces an existing one:
echo "Corrected info" | wade knowledge add --session <type> --supersedes <old-entry-id>
Filtering
By default, entries with enough negative votes are automatically pruned
(statistical auto-filter), and entries with stale >= 2 votes are hidden.
Override with:
--min-score N — hard cutoff on net score (bypasses auto-filter)--no-filter — show everything, bypasses both score filtering and stale filtering
