| name | detect-tensions |
| description | Detect productive contradictions between notes - high semantic similarity with opposing conclusions that represent synthesis opportunities |
| allowed-tools | ["Bash","Read"] |
| user-invocable | true |
| automation | gated |
| metadata | {"version":"1.1","updated":"2026-06-29T00:00:00.000Z","changelog":["1.1: Document detector blind spots - filter the false-positive flood (boilerplate/near-duplicate pairs) and probe manually for cross-vocabulary tensions the similarity+keyword detector cannot see (output is candidates, not proof of absence).","1.0: Initial version"]} |
Detect Productive Tensions
ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change - the top entry of metadata.changelog above - e.g. detect-tensions vX.Y - recent: <summary>. Then proceed.
Scans the knowledge base for productive contradictions: note pairs with high semantic similarity but opposing conclusions. These tension zones are where the most valuable articles and frameworks emerge.
State Dependencies
| Source | Location | Read | Write | Description |
|---|
| Enrichments | resources/brain-graph/data/graph_enrichments.json | ✓ | ✓ | Tension records saved |
| FAISS Index | resources/local-brain-search/data/brain.faiss | ✓ | | Similarity search |
| Metadata | resources/local-brain-search/data/brain_metadata.pkl | ✓ | | Note content |
Process
Step 1: Run tension detection
Default thresholds (similarity > 0.75, divergence > 0.3):
cd $PROJECT_ROOT/resources/brain-graph
../local-brain-search/venv/bin/python cli.py tensions
Broader search (more results, lower quality):
../local-brain-search/venv/bin/python cli.py tensions --similarity 0.70 --divergence 0.2
Step 2: Filter false positives, then present synthesis opportunities
The raw count is dominated by false positives - discard them before presenting:
- Boilerplate / near-duplicate pairs. The signature is high similarity with maximal divergence (e.g. sim ≈ 1.00, divergence ≈ 1.00), and pairs where both notes are changelogs, registries, or near-identical restatements of one principle. These are detector artifacts, not contradictions.
Keep only pairs that assert genuinely opposing conclusions about the same question. For each surviving tension, explain:
- What the two notes assert
- Why they contradict
- What synthesis opportunity exists (article topic, framework potential)
Step 3: Track existing tensions
../local-brain-search/venv/bin/python cli.py status --json
Check tension_count for total tracked tensions.
Step 4: Probe for cross-vocabulary tensions the detector cannot see
The detector pairs notes by cosine similarity (floor ~0.70) and scores opposition with a keyword heuristic (negation vs. assertion words). It is therefore structurally blind to the most valuable tensions: genuine contradictions are usually cross-vocabulary - two frameworks reaching opposite conclusions in different language - which fall BELOW the similarity floor and read too assertively for the keyword check. A thin or empty result does NOT mean no tensions exist; this tool surfaces candidates, it does not certify absence.
Compensate by manually checking known opposing-framework pairs even when they score below threshold, e.g.:
- loss aversion (prospect theory) ↔ ergodicity / Kelly (bias vs. correct policy)
- Bayesian/Brier "assign a probability" ↔ "There Is No Bayesian Dial" / radical uncertainty
- heuristics-and-biases ↔ ecological / evolutionary rationality
- expert failure as psychological ↔ expert failure as structural
Treat these as candidate tension edges regardless of the detector's similarity score.
Root-cause fix (code, out of scope for this playbook): durable precision needs resources/brain-graph/tension.py to replace the keyword stance heuristic with an LLM stance-classifier on a shared proposition, lower the similarity floor with theme/MOC-anchored cross-cluster pairing, and exclude index/changelog-layer nodes from the scan.
Key Principle
Tensions are features, not bugs. The system NEVER auto-resolves tensions. It surfaces them as the most productive intellectual territory in the vault.
