kb-contradictions

name	kb-contradictions
description	Semantic contradiction sweep — detects factual contradictions, conflicting recommendations, and superseded claims. Token-expensive, run deliberately. Use when the user wants to find contradictions or inconsistencies. Also triggers on "kb-contradictions" or "/kb-contradictions".

kb-contradictions

Perform a deep semantic contradiction sweep across the knowledge base. Detects factual contradictions, conflicting recommendations, and superseded claims between wiki pages.

Warning: This command is token-expensive. It reads and compares many pages. Run deliberately, not routinely.

Step 1: Token Cost Warning

Before proceeding, warn the user:

This command reads and cross-compares wiki pages in clusters.
It is significantly more token-expensive than other commands.
Proceed? (yes/no)

Abort if the user declines.

Step 2: Resolve KB

python3 ~/.config/kb/scripts/kb_resolve.py --mode mutating

Capture the KB root path. Abort if resolution fails.

Step 3: Cluster Pages by Topic

Extract unique tags from all wiki pages, then for each significant tag, run the related-content finder:

python3 ~/.config/kb/scripts/kb_find_related.py "{{KB_ROOT}}" --tags "{{TAG}}" --top-k 20

Build clusters of related pages. Also read index.md for a full page inventory. Prioritize clusters where pages share tags or source_ids, as these are most likely to contain contradictions.

Step 4: Read and Compare Clusters

For each cluster of related pages:

1. Read all pages in the cluster.

2. Extract factual claims, recommendations, and data points from each page, noting:

   • The specific claim.
   • The page it appears on.
   • The source(s) backing the claim (from source_ids).
   • The confidence level and date.

3. Cross-compare claims within the cluster. Detect three types:

Factual contradictions

Different pages assert conflicting facts about the same subject. Example: Page A says "X uses Python 3.8" while Page B says "X requires Python 3.11+".

Conflicting recommendations

Different pages recommend opposing approaches for the same problem. Example: Page A recommends "use REST for this" while Page B recommends "use GraphQL for this".

Superseded claims

A newer source contradicts or updates an older source's claims. Example: Page A (2024) says "library X is maintained" while Page B (2025) says "library X is archived".

Step 5: Generate Report

For each contradiction found, report:

### Contradiction {{N}}: {{SHORT_DESCRIPTION}}

**Type**: factual | recommendation | superseded
**Pages**:
  - [[page-a]] (confidence: {{C}}, created: {{D}})
  - [[page-b]] (confidence: {{C}}, created: {{D}})

**Claim A**: "{{QUOTE_OR_SUMMARY}}"
**Claim B**: "{{QUOTE_OR_SUMMARY}}"

**Raw sources**:
  - page-a <- raw/source-1.md
  - page-b <- raw/source-2.md

**Suggested resolution**: {{SUGGESTION}}

Step 6: User Decision

For each contradiction, ask the user to choose:

Option A: Resolve now

1. Determine which claim is correct (based on recency, confidence, source quality).
2. Update the incorrect page:
   • If human_reviewed: true: Skip with warning. Do not modify.
   • Otherwise: Correct the claim. Add a resolved contradiction record to frontmatter:

contradictions:
  - page: "wiki/<other-page>.md"
    claim: "<the corrected claim>"
    conflicting_claim: "<what was originally stated>"
    resolved: true
    resolution_date: YYYY-MM-DD

• Adjust confidence if warranted.
• Update last_verified to today.

3. Update the correct page:
   • Increase confidence slightly if corroborated.
   • Add a resolved contradiction record.
4. If one page supersedes another:
   • Add the old page path to the new page's supersedes field.
   • Move the old page to wiki/deprecated/ (unless human_reviewed: true).

Option B: Flag for later

1. Add the contradiction to BOTH pages' contradictions frontmatter with resolved: false:

contradictions:
  - page: "wiki/<other-page>.md"
    claim: "<this page's claim>"
    conflicting_claim: "<other page's claim>"
    resolved: false

2. Do not modify page content or confidence.
3. Skip human_reviewed: true pages with warning.

Option C: Skip

Take no action on this contradiction.

Step 7: Append Log

Add a row to log.md:

| {{DATE}} | contradictions | Found {{N}} contradictions — {{R}} resolved, {{F}} flagged, {{S}} skipped |

Final Output

Print:

• Total contradictions found.
• Breakdown by type (factual, recommendation, superseded).
• Resolutions applied.
• Contradictions flagged for later.
• Pages skipped due to human_reviewed.
• Suggestion: "Review flagged contradictions manually. Run kb-lint to verify KB health."