incoherence_skill

Overview

This skill detects and resolves incoherence between documentation, code, specs, and implementation. It runs a prescribed script workflow immediately on activation and guides you through detection, decision, and application phases. The goal is reproducible, interactive fixes without manual file editing.

How this skill works

On activation the skill immediately invokes the bundled Python script with required arguments (step number, total steps = 21, and accumulated thoughts). The script performs a 21-step workflow: steps 1–12 detect and verify incoherent candidates, steps 13–15 present structured questions to collect user decisions, and steps 16–21 apply changes and produce a final report. Follow the script output exactly; do not pre-scan or modify files before the script runs.

When to use it

• When documentation, code, or specs contradict each other
• During code reviews to surface hidden mismatches between docs and implementation
• Before releases to ensure docs and behavior are aligned
• When onboarding new contributors to reduce ambiguity
• If automated tests pass but runtime behavior seems unexpected

Best practices

• Always allow the script to run immediately on activation; it controls workflow sequencing
• Provide clear, concise replies to the interactive questions to speed resolution
• Keep --total-steps set to 21 and increment --step-number only as directed by the script
• Capture and preserve the script’s final report for audit and review
• Run in a clean working directory or CI environment to avoid unrelated state interference

Example use cases

• Detect outdated API docs that no longer match the Python implementation and choose whether to update docs or code
• Resolve spec ambiguity where tests pass but runtime errors reveal untested edge cases
• Uncover mismatches between configuration comments and effective behavior in a deployed service
• Step through a guided resolution when multiple candidate fixes exist and user input is required
• Generate a final consistency report for release notes or compliance records