wicked-brain-lint - SKILL.md Agent Skill

name: wicked-brain:lint description: | Check brain health and fix issues. Dispatches a lint subagent that runs deterministic checks (broken links, orphans, stale entries) and semantic analysis (inconsistencies, gaps, tag misalignment).

Use when: "lint the brain", "check brain health", "brain lint", "find issues in the brain".

wicked-brain:lint

Checks brain quality by dispatching a lint subagent.

Cross-Platform Notes

Commands in this skill work on macOS, Linux, and Windows. When a command has platform differences, alternatives are shown. Your native tools (Read, Write, Grep, Glob) work everywhere — prefer them over shell commands when possible.

For the brain path default:

macOS/Linux: ~/.wicked-brain
Windows: %USERPROFILE%.wicked-brain

Config

Brain discovery + server lifecycle are handled by wicked-brain-call. Pass --brain <path> to override the auto-detected brain, or set WICKED_BRAIN_PATH. The CLI starts the server on first call (no manual init required) and writes an audit record to {brain}/calls/ per call.

Process

Dispatch a lint subagent with these instructions:

You are a quality assurance agent for the digital brain at {brain_path}.
Server interactions: use `npx wicked-brain-call <action> [--param k=v ...]`.

## Pass 1: Deterministic checks

### Broken wikilinks
Find all [[wikilinks]] in wiki and chunk files, check if targets exist.
Use your Grep tool (preferred):
- Pattern: `\[\[[^\]]*\]\]`
- Search in: `{brain_path}/wiki/` and `{brain_path}/chunks/`

Shell fallback:
- macOS/Linux: `grep -roh '\[\[[^]]*\]\]' {brain_path}/wiki/ {brain_path}/chunks/ 2>/dev/null | sort -u`
- Windows (findstr): `findstr /s /r "\[\[" "{brain_path}\wiki\*.md" "{brain_path}\chunks\*.md" 2>nul`
- Windows (PowerShell preferred): `Get-ChildItem -Recurse -Path "{brain_path}\wiki","{brain_path}\chunks" -Filter "*.md" | Select-String -Pattern '\[\[' | Select-Object Path,LineNumber,Line`

For each link, use the Read tool to check if the target file exists.

### Orphan chunks
Use your Glob tool to find all chunk files in `{brain_path}/chunks/**/*.md`.
Then use your Grep tool to check which chunk IDs appear in wiki files.

Shell fallback:
- macOS/Linux:
  ```bash
  find {brain_path}/chunks -name "chunk-*.md" -type f
  grep -rl "chunk-" {brain_path}/wiki/ 2>/dev/null

Windows:

Get-ChildItem -Recurse -Filter "chunk-*.md" "{brain_path}\chunks"
findstr /s /r /m "chunk-" "{brain_path}\wiki\*.md" 2>nul
# PowerShell preferred: Get-ChildItem -Recurse -Path "{brain_path}\wiki" -Filter "*.md" | Select-String -Pattern "chunk-" -List | Select-Object -ExpandProperty Path

Stale entries

Compare source file modification times with chunk creation times.

Stale wiki articles

For each wiki article with source_hashes in frontmatter:

Read each source chunk
Compare its current content hash prefix against the stored hash
If any hash mismatches or chunk is missing: flag as stale

Missing frontmatter

Check each chunk has required frontmatter fields (source, chunk_id, confidence, indexed_at).

Also check the provenance field method (how the chunk/memory was obtained). The shared controlled vocabulary — the same set documented by wicked-brain:ingest and wicked-brain:memory — is: deterministic-parse, llm-vision, llm-synthesis, session-capture, manual, unknown. In practice deterministic-parse/llm-vision come from ingested chunks, session-capture from memories, and llm-synthesis/manual from either. method is optional — it was added after some content was written, so a chunk/memory without it is still valid. When it is missing, auto-fix by stamping method: unknown and report the fix as info severity, type missing_field (do NOT raise it to a warning/error — that would invalidate pre-existing content). Surfacing method: unknown lets a reviewer distinguish facts with known provenance from those whose origin was never recorded.

Lightweight provenance check (the "no source ⇒ assumption" rule): if a chunk has no source/source_path and its method is not one of the inferred kinds (llm-synthesis, unknown), flag it info, type missing_field: unsourced fact with method "{method}" — add a source or set method to llm-synthesis.

Tag synonym candidates

Call the server to get all tag frequencies:

npx wicked-brain-call tag_frequency

The response contains tags: [{tag, count}]. Identify potential synonyms:

Substring pairs: if tag A is a substring of tag B (e.g., "auth" is a substring of "authentication"), they may be synonyms. Flag pairs where both appear in the brain.
Edit distance ≤ 2: tags that differ by at most 2 character insertions, deletions, or substitutions (e.g., "authentification" vs "authentication") may be typos or synonyms.

For each candidate pair, report as info severity with type synonym_candidate:

path: _meta (brain-level issue, not file-specific)
message: Possible synonym: "{tagA}" ({countA} uses) and "{tagB}" ({countB} uses) — consider merging
fix: Run wicked-brain:retag to consolidate tags

Only report pairs where both tags have at least 1 use.

Link confidence report

Call the server for link health:

npx wicked-brain-call link_health

The response contains:

broken_links: count of links whose target is not in the index
low_confidence_links: count of links with confidence < 0.3
total_links: total link count
avg_confidence: average confidence across all links

Report findings:

If broken_links > 0: severity error, type broken_link: {broken_links} links point to targets not in the index. Use wicked-brain:search to verify targets.
If low_confidence_links > 0: severity warning, type low_confidence: {low_confidence_links} links have confidence < 0.3. Use wicked-brain:confirm to evaluate them.
Always include summary stats in the report: Total links: {total_links}, avg confidence: {avg_confidence:.2f}

Pass 2: Semantic analysis

Read a sample of chunks and wiki articles. Check:

Are tags consistent? (same concept tagged differently in different chunks)
Are there factual contradictions between articles?
Check for contradicts typed links — query the server:
```
npx wicked-brain-call contradictions
```
For each contradiction link, read both the source and target to determine if the contradiction is resolved. Flag unresolved contradictions as warnings.
Are there implicit connections that should be explicit [[links]]?
What topics have chunks but no wiki article? (coverage gaps)

Report

For each issue found:

severity: error | warning | info
type: broken_link | orphan | stale | missing_field | inconsistency | gap
path: which file
message: what's wrong
fix: suggested fix (or "auto-fixed" if you fixed it)

Auto-fix items include (apply silently, then report as "auto-fixed"):

Missing frontmatter fields: fill with safe defaults (e.g., confidence: low, indexed_at: now)
Orphaned index entries: remove entries from the SQLite index whose source file no longer exists

Manual review required (flag as error or warning — do NOT auto-fix):

Factual contradictions between articles
Duplicate content covering the same concept in different files
Broken wikilinks where the correct target is ambiguous
Stale wiki articles where the underlying chunk content has changed substantially

Auto-fix broken links and missing fields where possible. Report everything else.