incoherence

timmye's avatarfrom timmye

Detect and resolve incoherence in documentation, code, specs vs implementation. Includes reconciliation phase for applying user-provided resolutions.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 6, 2026⬇️1downloads
[Code Review]

When & Why to Use This Skill

The Incoherence Detector is a powerful Claude skill designed to automate the identification and resolution of discrepancies between technical documentation, source code, and project specifications. By utilizing a structured 22-step workflow, it ensures that software implementations remain strictly aligned with their design requirements, significantly reducing technical debt and documentation rot in complex development environments.

Use Cases

  • Technical Debt Reduction: Identifying and fixing outdated README files or API documentation that no longer matches the current codebase implementation.
  • Specification Validation: Verifying that new feature code strictly adheres to the logic and constraints defined in initial technical design documents (TDD).
  • Cross-Artifact Consistency: Detecting naming or logic mismatches between architectural diagrams, inline comments, and the actual executable code.
  • Guided Reconciliation: Using the multi-step workflow to systematically apply user-approved fixes to documentation and code after a major refactoring session.
nameincoherence
descriptionDetect and resolve incoherence in documentation, code, specs vs implementation. Includes reconciliation phase for applying user-provided resolutions.

Incoherence Detector

When this skill activates, IMMEDIATELY invoke the script. The script IS the workflow.

Prerequisites

User must specify the report filename (e.g., "output to incoherence-report.md").

Invocation

# Detection phase (steps 1-13)
python3 scripts/incoherence.py \
  --step-number 1 \
  --total-steps 22 \
  --thoughts "<context>"

# Reconciliation phase (steps 14-22, after user edits report)
python3 scripts/incoherence.py \
  --step-number 14 \
  --total-steps 22 \
  --thoughts "Reconciling user resolutions from report"
Argument Required Description
--step-number Yes Current step (1-22)
--total-steps Yes Always 22
--thoughts Yes Accumulated state from all previous steps

Do NOT explore or detect first. Run the script and follow its output.