intentumdiff-architecture-audit
Systematically reason over the IntentDiff codebase and find its real problems — invariant violations, architectural drift, latent bugs, and tech debt — then produce a ranked, root-caused findings repo
SKILL.mdskills/intentumdiff-architecture-audit/SKILL.md
GitHubIntentDiff — Architecture audit ("find all the problems")
Goal: turn "review the architecture" into a repeatable, evidence-backed sweep that ends in a ranked findings report an agent can act on. Two principles govern the whole pass:
- Root cause, not symptoms. A failing test or a wrong pixel is a lead, not a finding. Trace it to the construction that produced it. If a fix would compensate downstream for something built wrong upstream, the finding is the upstream construction. (See the "stick-plaster" category.)
- Verify before you report. Each finding must include how you confirmed it (a repro, a grep hit with file:line, a failing assertion, a boundary-gate run) — and, where cheap, whether it is pre-existing vs newly introduced (stash the working changes and re-run).
Work category by category. For deep per-category probes, greps, and known traps, read references/audit-checklist.md. The categories:
1. Engine boundary (Rust = engine, Python = shell)
The release contract. Look for processing/analysis logic added to Python instead of Rust, and
first-party product paths importing intentdiff.analysis.* / intentdiff.core.engine.
Authoritative: docs/ENGINE_BOUNDARY_AUDIT.md. Run the strict gate:
INTENTDIFF_ENFORCE_RUST_ONLY_ENGINE=1 <pytest ...>. New Python engine code is a finding.
2. Change-group index-space contract
The highest-recurrence bug class. Every ChangeGroup producer must carry node ids or be
honestly empty — never emit phantom raw_change_indices for a downstream pass to erase. Every
consumer must range-check dereferences and cover ungrouped changes. See
intentdiff-engine → references/index-space-contract.md. Audit new/edited producers and
consumers against that contract.
3. Theme-native styling (extension)
No hardcoded chrome hex literals, no bundled fonts, codicons-only, category colors via the
contributed intentdiff.semanticChanges.* tokens. Grep the panel/diagnostics HTML output
(not just media/) for hex literals, iconSvg/<svg> chrome icons, and font <link>s.
Do not assume test/themeColors.test.ts enforces this — it validates the contributed color
IDs + overview-ruler tokens but does not scan rendered HTML for chrome hex or custom icons.
There is standing drift here (100+ hardcoded hex + a custom iconSvg set in
reviewWebviewModel.ts styles() and extension.ts diagnostics HTML) that passes CI — a known
hotspot; confirm current state with a real grep rather than trusting the test.
4. Privacy / BYOK
No bundled API key, no paid proxy, keys only in SecretStorage, consent modal before any send,
verbatim source only to a local endpoint, unit tests do no network. Grep for hardcoded
keys, cloud URLs, fetch( outside the gated explainer, and network calls reachable from unit
tests. Cross-check plugins/vscode/PRIVACY.md.
5. Monaco-retirement / native-first
No reintroduced Monaco, createDiffEditor webview embeds, media/monaco/ references, or
retired gap machinery (gapStates, expandGap, floating chevrons, reconstructFullFile).
Grep for these symbols.
6. Stick-plaster patterns
Downstream compensation for upstream defects; duplicated fixes; "fix the symptom" comments; tags/flags whose only purpose is to make another pass clean up a mess. Each is a finding whose recommended fix is at the source.
7. Test health
Run pytest tests/unit, cargo test -p rust-core-host, and cd plugins/vscode && npm run lint && npm run test. For every failure: get the traceback, root-cause it, and classify —
genuine regression (bisect-worthy) vs documented gap vs stale assertion/reference. Confirm
pre-existing vs introduced by stashing. xfailed markers are expected, not failures. Note
that the RC gate (docs/BACKLOG.md → "0.0.1 RC Release Gate") requires the suites green, so
undocumented failures are release blockers — surface them.
8. Dead code, stale docs, drift
Unused functions/branches, superseded paths, stale references (e.g. a fixture pointing at a
deleted test), and docs that contradict shipped behavior (reconcile CLAUDE.md /
docs/architecture/diff-viewer.md with the code).
Report format (use this exactly)
Rank findings most-severe first. For each:
### [SEV: critical|high|medium|low] <one-line defect>
- **Category:** <one of the 8 above>
- **Location:** <path:line> (+ related sites)
- **Root cause:** <the construction that produces it, not the symptom>
- **Evidence:** <repro / grep hit / failing assertion / gate output; pre-existing? y/n>
- **Impact:** <what breaks, for whom>
- **Fix:** <the source-level fix, and which layer (Rust / Python shell / extension)>
- **Verify:** <the exact command/repro that will show it fixed>
End with a short Summary: counts by severity + category, the top 3 to fix first, and any
systemic theme (e.g. "three findings share the index-space root cause"). If a finding needs a
bigger effort than the current task, recommend a docs/BACKLOG.md entry rather than an inline
fix — the audit's job is to find and rank, the dev-loop's job is to fix.
Scope control
A full sweep is large. If the user scoped it ("audit the extension", "check the engine after my change"), run only the relevant categories but keep the same root-cause + verify rigor. Prefer depth on real findings over breadth of shallow observations — a ranked list of five confirmed, root-caused issues beats twenty unverified smells.