incoherence
Detect contradictions between documentation and code, ambiguous specs, and policy violations across a codebase. Use when documentation seems stale, specs conflict with implementation, or a pre-release consistency audit is needed. Produces an actionable incoherence report with resolution workflow.
- License 许可
- MIT
- 最近更新
- 2026-03-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- incoherence
- model
- claude-sonnet-4-5
- agents
- [ "analyst", "critic", "qa" ]
- license
- MIT
- metadata
- { "version": "1.0.0" }
- description
- Detect contradictions between documentation and code, ambiguous specs, and policy violations across a codebase. Use when documentation seems stale, specs conflict with implementation, or a pre-release consistency audit is needed. Produces an actionable incoherence report with resolution workflow.
02 资源文件 2
- 参考文档references/DEVELOPMENT.md1.6 KB
- 脚本scripts/incoherence.ts12.7 KB
03 SKILL.md 正文
Incoherence Detector Skill
Purpose
Detect and resolve incoherence: contradictions between docs and code, ambiguous specifications, missing documentation, or policy violations.
Triggers
| Trigger Phrase | Operation |
|---|---|
find contradictions in the docs |
Detection phase (steps 1-13) |
audit docs vs code consistency |
Detection phase with Dimension A focus |
check for stale documentation |
Detection phase with Dimension D focus |
run incoherence detector |
Full detection phase |
reconcile incoherence report |
Reconciliation phase (steps 14-22) |
When to Use
Use this skill when:
- Documentation may contradict actual code behavior
- Preparing for a release and need a consistency audit
- Specs have changed but implementation status is unclear
- Multiple authors edited docs and code independently
Use direct code review instead when:
- Investigating a single known bug
- The inconsistency is already identified and just needs a fix
Anti-Patterns
| Avoid | Why | Instead |
|---|---|---|
| Skipping the report filename specification | Script requires output path upfront | Specify filename before starting detection |
| Running reconciliation without user edits | Nothing to apply, wasted steps | Wait for user to fill Resolution sections |
| Editing the report format manually | Breaks reconciliation parsing | Let the script manage report structure |
| Selecting all 11 dimensions | Excessive scope, diminishing returns | Let step 2 select the most relevant 3-5 |
| Ignoring low-severity issues | They accumulate into real drift | Triage all issues, defer explicitly if needed |
Verification
After detection:
- [ ] Report file created at user-specified path
- [ ] Each issue has Type, Severity, Source A/B, Suggestions, and Resolution section
- [ ] Dimension coverage matches selection from step 2
After reconciliation:
- [ ] Resolved issues show status marker in report
- [ ] Code changes match user-provided resolutions
- [ ] No unresolved critical or high severity issues remain
Prerequisites
Before starting: User must specify the report filename (e.g., "output to incoherence-report.md").
Scripts
| Script | Purpose |
|---|---|
scripts/incoherence.ts |
22-step detection and reconciliation workflow for doc-code contradictions |
Invocation
# Detection phase (steps 1-13)
bun run ${CLAUDE_SKILL_DIR}/scripts/incoherence.ts --step-number 1 --total-steps 22 --thoughts "<context>"
# Reconciliation phase (steps 14-22, after user edits report)
bun run ${CLAUDE_SKILL_DIR}/scripts/incoherence.ts --step-number 14 --total-steps 22 --thoughts "Reconciling..."
Process
DETECTION PHASE (Steps 1-13):
Step 1: CODEBASE SURVEY ─────┐
Step 2: DIMENSION SELECTION │ Parent
Step 3: EXPLORATION DISPATCH ─────┘
│
▼
┌────────────────────────┐
│ Step 4: BROAD SWEEP │
│ Step 5: COVERAGE CHECK│ Exploration
│ Step 6: GAP-FILL │ Sub-agents
│ Step 7: FORMAT │
└────────────────────────┘
│
▼
Step 8: SYNTHESIS ─────┐
Step 9: DEEP-DIVE DISPATCH ─────┘ Parent
│
▼
┌────────────────────────┐
│ Step 10: EXPLORATION │ Deep-dive
│ Step 11: FORMAT │ Sub-agents
└────────────────────────┘
│
▼
Step 12: VERDICT ANALYSIS ─────┐
Step 13: REPORT GENERATION │ Parent
│ ─────┘
▼
═══════════════════════════
USER EDITS REPORT
(fills in Resolution sections)
═══════════════════════════
│
▼
RECONCILIATION PHASE (Steps 14-22):
Step 14: RECONCILE PARSE ─────┐
Step 15: RECONCILE ANALYZE │
Step 16: RECONCILE PLAN │ Parent
Step 17: RECONCILE DISPATCH ─────┘
│
▼
┌────────────────────────┐
│ Step 18: APPLY │ Sub-agents
│ Step 19: FORMAT │ (invoke script)
└────────────────────────┘
│
▼
Step 20: RECONCILE COLLECT ───┐
│ (loop if more waves) │
▼ │ Parent
Step 21: RECONCILE UPDATE │
│ │
▼ │
Step 22: RECONCILE COMPLETE ────┘
Reconciliation Behavior
Idempotent: Can be run multiple times on the same report.
Skip conditions (issue left unchanged):
- No resolution provided by user
- Already marked as resolved (from previous run)
- Could not apply (sub-agent failed)
Only action: Mark successfully applied resolutions as ✅ RESOLVED in report.
Report Format
Step 9 generates issues with Resolution sections:
### Issue I1: [Title]
**Type**: Contradiction | Ambiguity | Gap | Policy Violation
**Severity**: critical | high | medium | low
#### Source A / Source B
[quotes and locations]
#### Suggestions
1. [Option A]
2. [Option B]
#### Resolution
<!-- USER: Write your decision below. Be specific. -->
<!-- /Resolution -->
After reconciliation, resolved issues get a Status section:
#### Resolution
<!-- USER: Write your decision below. Be specific. -->
Use the spec value (100MB).
<!-- /Resolution -->
#### Status
✅ RESOLVED — src/uploader.py:156: Changed MAX_FILE_SIZE to 100MB
Dimension Catalog (A-K)
| Cat | Name | Detects |
|---|---|---|
| A | Specification vs Behavior | Docs vs code |
| B | Interface Contract Integrity | Types/schemas vs runtime |
| C | Cross-Reference Consistency | Doc vs doc |
| D | Temporal Consistency | Stale references |
| E | Error Handling Consistency | Error docs vs implementation |
| F | Configuration & Environment | Config docs vs code |
| G | Ambiguity & Underspecification | Vague specs |
| H | Policy & Convention Compliance | ADRs/style guides violated |
| I | Completeness & Documentation Gaps | Missing docs |
| J | Compositional Consistency | Claims valid alone, impossible together |
| K | Implicit Contract Integrity | Names/messages that lie about behavior |
04 同仓库更多 Skills
validation-authority
Treat upstream validators as authoritative. Align local config to them. Use when validation fails unexpectedly, before modifying validator behavior, or when tempted to change upstream tool code.
using-brain-memory
Guidance for using Brain semantic memory effectively. Applies Zettelkasten atomic note principles with observations and relations. Use when deciding whether to query or create notes, structuring note content, or understanding the semantic knowledge graph.
threat-modeling
Structured security analysis using OWASP Four-Question Framework and STRIDE methodology. Generates threat matrices with risk ratings, mitigations, and prioritization. Use for attack surface analysis, security architecture review, or when asking what can go wrong.
taste-lints
Custom lints with agent-readable remediation instructions. Enforces taste invariants (file size, naming conventions, structured logging, complexity) and surfaces errors that agents can act on directly. Use when writing or reviewing code to catch style violations early.
style-enforcement
Validate code against style rules from .editorconfig, StyleCop.json, and Directory.Build.props. Detects line ending violations, naming convention issues, indentation problems, and charset mismatches across C#, Python, TypeScript, and JavaScript. Produces JSON reports for pre-commit hooks and CI pipelines.
steering-matcher
Match file paths against steering file glob patterns to determine applicable steering guidance. Use when orchestrator needs to inject context-aware guidance based on files being modified.