integration-checker · diff

git:20260610.60dbf44 to git:20260905.f512261

32 added, 165 removed. Audit A to A.

---

name: integration-checker

description: "Verify cross-component wiring and data flow."

user-invocable: false

command: /integration-checker

allowed-tools:

- Read

- Bash

- Grep

- Glob

routing:

triggers:

- integration check

- check integration

- verify wiring

- are components connected

- check connections

- integration-checker

- wiring check

pairs_with:

- feature-lifecycle

- systematic-code-review

complexity: Medium

category: process

---

- # Integration Checker Skill

- **Existence does not equal integration.** A component existing is implementation-level verification; a component being connected is integration-level verification. Both are necessary. Neither is sufficient alone.

- This skill catches the most common class of real-world bugs in AI-generated code: components that are individually correct but not connected to each other. A function can exist, contain real logic, pass correctness verification, and never be imported or called. An API endpoint can be defined but never wired into the router. An event handler can be registered but never receive events.

- This is a read-only analysis skill -- it reads and reports but does not fix wiring issues. Fixes route back to /feature-lifecycle (implement phase) or the user, because integration fixes often require design decisions about which component should call which.

- ---

- ## Reference Loading Table

- | Signal | Load These Files | Why |

- |---|---|---|

- | classifying exports/imports and tracing data flow (Phases 0-2) | `wiring-checks.md` | Loads detailed guidance from `wiring-checks.md`. |

- ## Instructions

- ### Phase 0: PRIME

- **Goal**: Establish context, detect language, identify scope.

- **Step 1: Read repository CLAUDE.md** (if present) and follow any project-specific conventions before proceeding.

- **Step 2: Detect execution context**

- Determine if running within the feature pipeline or standalone:

- - **Pipeline**: Check for `.feature/state/implement/` artifact. If present, load it to understand what was built and scope the check to changed/added files. Scoping to changed files prevents wasting time analyzing unchanged code in large repositories.

- - **Standalone**: Scope to the current working directory or user-specified path. Analyze all source files.

- **Step 3: Detect project language(s)**

- Detect language(s) before applying any verification techniques -- different languages have fundamentally different import/export patterns.

- > See `references/wiring-checks.md` for language detection indicators, per-language export/import patterns, and common integration failures per language.

- Multiple languages may coexist. Run all applicable techniques for each.

- **Gate**: Language(s) detected. Scope established. Proceed to Phase 1.

- ---

- ### Phase 1: EXPORT/IMPORT MAP

- **Goal**: For every export in scope, determine its wiring status. Every export gets exactly one of three states -- no ambiguous classifications.

- **Step 1: Discover exports**

- Scan source files for exported symbols. Be language-aware:

- - **Go**: Find all capitalized function, type, const, and var declarations at package level. Include method receivers on exported types.

- - **Python**: Find all module-level function/class/variable definitions. Check `__all__` if present (it restricts the public API). Check `__init__.py` for re-exports.

- - **TypeScript/JavaScript**: Find all `export` declarations, `export default`, and barrel file re-exports.

- Skip `node_modules/`, `vendor/`, `.git/`, `__pycache__/`, `dist/`, `build/`, test fixtures, and generated files. These contain intentionally unused exports (library code, vendored deps) that would flood the report with false positives.

- Record each export as: `{file, name, kind (function/type/const/var), line}`.

- **Step 2: Discover imports and usages**

- For each export found, search the codebase for:

- 1. **Import**: The symbol is imported (appears in an import statement referencing the exporting module)

- 2. **Usage**: The imported symbol is actually used (called, referenced, assigned, passed as argument) beyond the import statement itself

- Both checks are required. An import without usage is a distinct failure mode from an orphan -- it signals someone intended to use the component but didn't finish wiring it.

- **Step 3: Classify each export**

- > See `references/wiring-checks.md` for the full classification table, exclusion list, and files to skip during discovery.

- **Step 4: Build the export/import map**

- Report failures first -- users need to see ORPHANED before IMPORTED_NOT_USED before WIRED.

- ```

- ## Export/Import Map

- ### ORPHANED (Failure)

- |------|--------|------|-------------|

- ### IMPORTED_NOT_USED (Warning)

- |------|--------|------|-------------|-------|

- ### WIRED (Pass) — [N] components

- (Shown only in verbose mode)

- ```

- **Gate**: All in-scope exports classified. Map produced. Proceed to Phase 2.

- ---

- ### Phase 2: DATA FLOW AND CONTRACT CHECK

- **Goal**: For WIRED components, verify that real data flows through the connections and that output shapes match input expectations. A component wired to always receive empty data is functionally disconnected.

- This phase checks two things simultaneously because they both operate on the same set of WIRED connections identified in Phase 1.

- This is structural analysis, not semantic verification. Contract checking verifies shape and naming compatibility, not whether data is logically correct -- semantic correctness would require runtime information that static analysis cannot provide.

- #### Data Flow Tracing

- For each WIRED connection, check whether real data actually reaches the component.

- > See `references/wiring-checks.md` for the full catalog of data flow failure patterns (hardcoded empty data, placeholder data, dead parameters, mock remnants) and contract mismatch patterns (shape, type, event/message mismatches) with confidence level guidance.

+ # Integration checker

- **Gate**: Data flow and contract findings recorded. Proceed to Phase 3.

+ Check that components are connected and receive real data. A function can pass unit tests yet never be called; an endpoint can exist without being registered.

- ---

+ This skill reads and reports. Return fixes to the active implementation task or `feature-lifecycle`; do not create another approval round when fixes are already authorized.

- ### Phase 3: REPORT

+ ## Reference loading

- **Goal**: Produce a structured integration report with actionable findings. Report facts and show the wiring map -- not prose about the wiring map.

+ Load `references/wiring-checks.md` for language detection, export exclusions, wiring states, data-flow failures, contract patterns, and the requirements map.

- **Step 1: Requirements integration map (pipeline mode only)**

+ ## Phase 0: PRIME

- If running within the feature pipeline and a task plan exists in `.feature/state/plan/`, trace each requirement from entry point to implementation using WIRED / PARTIAL / UNWIRED status.

+ Read repository instructions. In a feature pipeline, use `.feature/state/implement/` to scope changed and added files. Otherwise use the requested path or diff; a requested full audit covers all source files. If the implementation artifact is missing, use the diff and state the gap.

- > See `references/wiring-checks.md` for the requirements integration map format and status definitions.

+ Detect every language in scope. Reuse existing integration evidence for unchanged connections; trace affected producers and consumers beyond the diff where needed.

- **Step 2: Compile integration report**

+ **Gate:** Scope and languages are known.

- ```markdown

- # Integration Check Report

+ ## Phase 1: EXPORT/IMPORT MAP

- ## Summary

- - Components checked: [N]

- - WIRED: [N]

- - IMPORTED_NOT_USED: [N]

- - ORPHANED: [N]

- - Data flow issues: [N]

- - Contract mismatches: [N]

- - Integration score: [WIRED / (WIRED + IMPORTED_NOT_USED + ORPHANED) * 100]%

+ Inventory public symbols using language-aware searches:

- ## Verdict: PASS / WARN / FAIL

+ - Go: exported package functions, types, constants, variables, and methods.

+ - Python: module definitions, `__all__`, and `__init__.py` re-exports.

+ - TypeScript/JavaScript: named/default exports and barrel re-exports.

- PASS: No ORPHANED components, no data flow issues, no contract mismatches

- WARN: No ORPHANED, but has IMPORTED_NOT_USED or low-confidence contract findings

- FAIL: Has ORPHANED components, data flow issues, or high-confidence contract mismatches

+ Exclude dependencies, generated files, build output, fixtures, and repository metadata. Apply the reference's exceptions for public library APIs, plugin contracts, framework entrypoints, and other legitimate external consumers before calling a symbol orphaned.

- ## Export/Import Map

- [From Phase 1 — only issues, unless verbose mode]

+ For each symbol, record file, name, kind, and line. Find imports and actual usage; an import alone does not establish wiring. Classify as ORPHANED, IMPORTED_NOT_USED, or WIRED using the reference. Report failures first; show successful connections only in verbose mode.

- ## Data Flow Issues

- [From Phase 2 — data flow findings]

+ **Gate:** Every in-scope symbol has a status or an explicit unresolved limitation.

- ## Contract Mismatches

- [From Phase 2 — contract findings with confidence level]

+ ## Phase 2: DATA FLOW AND CONTRACT CHECK

- ## Requirements Integration Map

- [From Step 1 — if in pipeline mode]

+ Trace WIRED connections for real inputs and compatible contracts. Check hardcoded empty data, placeholders, dead parameters, mock remnants, shape/type mismatches, and event/message names using the reference.

- ## Recommended Actions

- 1. [Specific action for each ORPHANED component]

- 2. [Specific action for each IMPORTED_NOT_USED]

- 3. [Specific action for each data flow issue]

- 4. [Specific action for each contract mismatch]

- ```

+ Static inspection establishes structure and likely compatibility, not runtime correctness. Use existing runtime evidence where available; distinguish observed failures from uncertain dynamic-language matches. Low-confidence contract findings warn rather than fail.

- Only fail the verdict on high-confidence contract mismatches. Low-confidence findings in dynamic languages are informational -- they belong in the WARN tier, not FAIL.

+ **Gate:** Data-flow and contract findings include locations, evidence, and confidence.

- **Step 3: Verdict and next steps**

+ ## Phase 3: REPORT

- | Verdict | Next Step |

- |---------|-----------|

- | **PASS** | Proceed to /feature-lifecycle (validate phase) |

- | **WARN** | Review warnings. Proceed if warnings are intentional (unused imports for future use, etc.). Fix if unintentional. |

- | **FAIL** | Route back to /feature-lifecycle (implement phase) with specific wiring tasks so validation runs only after the wiring is in place. |

+ Report component counts, wiring failures, data-flow issues, contract mismatches, and concrete fixes. In pipeline mode, use `.feature/state/plan/` to map each requirement from entrypoint to implementation as WIRED, PARTIAL, or UNWIRED.

- **Gate**: Report produced with verdict and actionable recommendations.

+ Compute integration score as `100 * WIRED / (WIRED + IMPORTED_NOT_USED + ORPHANED)`; report N/A when the denominator is zero.

- ---

+ | Verdict | Condition | Next action |

+ |---|---|---|

+ | PASS | No wiring, flow, or contract issues | Continue validation |

+ | WARN | Unused imports or low-confidence contract findings only | Resolve or explain warnings |

+ | FAIL | Orphaned components, data-flow defects, or high-confidence contract mismatches | Return concrete fixes to implementation |

- ## Error Handling

+ State incomplete coverage separately; missing source or unresolved scope cannot establish a PASS. Include circular imports as integration findings. For a large monorepo, narrow to affected connections unless the user requested a full audit; split a full audit into bounded scopes without silently omitting files.

- | Error | Cause | Solution |

- |-------|-------|----------|

- | No source files found | Wrong scope path or empty project | Verify working directory, check scope parameter |

- | Language not detected | No recognizable build files or source extensions | Specify language manually or check project structure |

- | Too many exports to analyze | Large monorepo or library with thousands of exports | Narrow scope to changed files (use `git diff --name-only` against base branch) |

- | False positive ORPHANED | Library code, plugin interfaces, or entry points | Check exclusion patterns. If legitimate public API, add to exclusions. |

- | Circular import detected | Python circular imports or Go import cycles | Report as separate finding -- circular imports are integration issues themselves |

- | No implementation artifact | Running in pipeline mode but implement phase didn't checkpoint | Fall back to standalone mode using git diff to identify changed files |

+ **Gate:** Findings, limitations, and next actions are clear. After fixes, recheck affected connections rather than repeating unchanged analysis.

## References

- - [Feature State Conventions](../feature-lifecycle/references/shared.md)

- - [ADR-078: Integration Checker](../../adr/078-integration-checker.md)

+ - [Feature state conventions](../../process/feature-lifecycle/references/shared.md)