shadow-frog-meditate

ShadowFrog Meditate

Shadow hygiene — deduplicate, merge, and resolve conflicts across the entire .shadow/ knowledge base. Prerequisite: .shadow/ exists with discoveries.

Phase 1: Scan

Use parallel subagents to scan the shadow. Each subagent handles a batch of shadow files.

Scope Optimization

Not every file needs scanning. To reduce cost:

• Skip files with 0-1 discoveries — they can't have internal duplicates
• Focus on files modified since last meditate — check _meta/state.json last_update_at against file modification times
• Always scan files with 5+ discoveries — highest duplicate risk

For the first meditate after a large dream run, most files will need scanning.

Per-File Scan

For each per-file shadow (e.g., src/auth.py.md):

1. Read all discoveries under each ## symbol heading
2. Compare discoveries under the same symbol by behavioral meaning, not wording:
   • Duplicate: same behavioral claim, different wording
   • Near-duplicate: one discovery is a subset/refinement of the other
   • Conflict: the two discoveries make contradicting claims
   • Distinct: genuinely different insights — no action needed
3. Record each finding as a structured action (see below)

Overlapping Also involves: refs can help identify related claims.

Scan Output Format

Subagents must output findings as one JSON object per line so the orchestrator can auto-apply resolutions. This is critical for automation — prose recommendations require manual interpretation.

{"action": "merge", "file": "src/auth.py.md", "symbol": "authenticate_user", "keep": "- silently returns None on expired tokens...", "remove": "- returns None when token expires...", "merged": "- authenticate_user() silently returns None on expired tokens instead of raising. 3 of 7 callers don't check.\n  _(verified, source: exploration, citation_score: 0)_", "reason": "duplicate: same claim, different wording"}
{"action": "merge", "file": "src/db.py.md", "symbol": "connect", "keep": "- connection pool exhaustion...", "remove": "- pool runs out...", "merged": "...", "reason": "near-duplicate: first extends second"}
{"action": "conflict", "file": "src/auth.py.md", "symbol": "validate_token", "entry_a": "- raises ValueError...", "entry_b": "- returns False...", "resolution": "verified_a", "reason": "code inspection: line 42 raises ValueError"}
{"action": "conflict", "file": "src/cache.py.md", "symbol": "invalidate", "entry_a": "...", "entry_b": "...", "resolution": "escalate", "reason": "both claims have evidence, needs user input"}
{"action": "move_to_cross", "file": "src/auth.py.md", "symbol": "validate_token", "entry": "- all validators share...", "cross_slug": "shared-validation-pattern", "reason": "cross-scope: involves 4 files"}