audit-simplification

# Audit Simplification Find removable mechanisms while preserving required observable behavior. Favor fewer concepts, allocations, synchronization paths, and lifecycle responsibilities. ## Scope and Authorization - Analyze the project or directory the user names. If they name no target, infer the smallest reasonable scope from the request and repository state. - Treat an audit as read-only. Edit only when the user explicitly asks for implementation. - Read the root `AGENTS.md`, nearer agent instructions, and the target project's `DEVELOPMENT.md` before analyzing. `DEVELOPMENT.md` lists the test types the project runs, which shows which observable behavior is already covered. Read additional required guidelines for the files or APIs in scope. - Preserve unrelated working-tree changes. - Preserve published API unless the user authorizes a breaking change. Treat each project's `package.json` `exports` as its published boundary. Packages also export their `/internal` entrypoints, and sibling packages depend on them; for example, most other projects import `@nvidia-elements/core/internal`. Before calling anything unused or unpublished, search every project under `projects/`, including starters, site docs, `*.examples.ts` files, and `projects/internals/patterns`. Use `audit-consolidation` instead when the main question is where duplicate or shared responsibility should live. Use this skill when the earlier question is whether a mechanism or responsibility needs to exist at all. When both apply, run this audit first; removing a mechanism often removes the duplication question with it. ## Establish the Observable Contract Before proposing removal, identify the behavior that must survive: - public properties, attributes, slots, methods, events, and exports - CSS selectors, accessibility semantics, external observers, SSR, or serialization that depend on DOM state - connection, disconnection, host replacement, and resource cleanup behavior - ordering, isolation, caching, and error-reporting guarantees - tests that assert externally observable behavior rather than implementation structure Do not keep internal machinery merely because a test describes it. Preserve required behavior and update implementation-coupled tests when the user authorizes the simplification. ## Inspect for Removable Mechanisms Trace reads, writes, construction sites, call sites, cleanup paths, and platform behavior. Use the following lenses as prompts, not assumptions that every match warrants removal. ### Property and Attribute Duplication Inspect property reflection, normalization, converters, and property-to-attribute synchronization. Determine whether declarative input, CSS selectors, accessibility, external observation, SSR, or serialization needs the attribute. Accepting an attribute as input does not require reflecting later property changes back to it. `projects/site/src/docs/api-design/properties-attributes.md` sets the repository rule: reflect only when the attribute serves as a style hook or another observable purpose, and never reflect object or array properties. Recommend removing reflection or normalization only when it has no required observable purpose. ### Dependency Indirection Look for: - callbacks that only return a public host member - options that are always passed the same constant - methods that only forward arguments to another object - return values that all callers ignore - abstractions with one implementation and no meaningful substitution or test seam Prefer direct access when it does not introduce coupling beyond the dependency already present. ### Lifecycle Ownership Find paired operations such as event listener registration and removal, binding and unbinding, or resource acquisition and release. The object that owns the behavior should normally own its setup and cleanup. When a Lit host owns behavior, consider a `ReactiveController` if the behavior's lifetime naturally follows host connection and disconnection. Do not introduce a controller merely to move unrelated code. ### Stored-State Necessity Trace fields and collections through both reads and writes. Flag state that is: - written but never meaningfully read - reset only because it exists - retained after an event has already communicated the outcome - used only to compute an ignored return value - duplicated by another authoritative source Remove the state and its maintenance paths together. ### Instance Cardinality and Allocation Search for every construction site of significant classes. Determine whether the state is genuinely per-instance, per-host, per-device, per-document, or realm-wide. A shared service is appropriate when it represents one shared facility, host behavior can remain isolated through explicit identity keys, and shared ownership does not leak elements or test state. Prefer lazy allocation and `WeakMap` storage for state keyed by externally owned objects. Do not turn every module-level cache, adapter, controller, or state store into a service. Keep domain-local implementation details beside their owner when shared dependency injection provides no benefit. ### Native Platform Replacement Look for custom synchronization that duplicates browser or Lit behavior, including manual slot distribution, mutation-driven redistribution, attribute mirroring, lifecycle forwarding, and bookkeeping for native DOM state. During the audit, cite the platform behavior the replacement would rely on and any existing tests that cover it. When no test covers it, mark the finding as needing verification; writing that focused test becomes the first implementation step. Keep custom behavior when it intentionally differs from the platform default. ### Naming and Placement Check whether names and locations accurately communicate responsibility and cardinality: - per-host Lit lifecycle behavior generally belongs in `*.controller.ts` - a shared singleton dependency generally belongs in `*.service.ts` - domain-local caches and platform adapters should remain near their subsystem - rendering, content management, and input behavior should remain separate when they have different lifecycles or dependencies Renaming alone is not a simplification unless it makes ownership or cardinality clearer. ## Guardrails Do not recommend removal when: - reflection supports CSS, accessibility, serialization, or external observers - separate instances provide required isolation, ordering, or namespaces - a singleton would introduce SSR, cross-document, test, or global-state leakage - manual DOM behavior intentionally differs from native semantics - lifecycle code must support hosts outside Lit - the replacement adds more coupling or indirection than it removes Tie performance findings to a concrete avoided allocation, listener, synchronization step, retained object, or hot-path operation. Label speculative performance benefits as such. When the user wants measured evidence, use the `authoring-benchmarks` skill rather than estimating. ## Rank Findings Rank opportunities using all four factors: - **Evidence:** strength of the demonstrated redundancy across reads, writes, and call sites. - **Payoff:** concepts, allocations, listeners, synchronization paths, or lifecycle responsibilities removed. - **Confidence:** certainty that no required observable behavior depends on the mechanism. - **Risk:** migration size, behavioral sensitivity, package/API impact, and test churn. Assign each finding a priority: - **P1:** strong evidence and clear payoff at low-to-moderate risk; worth doing next. - **P2:** worthwhile, but larger, riskier, or waiting on a user decision. - **P3:** minor payoff; worth doing alongside related work. Return a few high-confidence findings rather than an exhaustive list of weak possibilities. ## Report Use this structure. `audit-consolidation` shares it so that both audits of one project read side by side. ### Scope Analyzed Name the directories, entrypoints, exclusions, consumer search scope, and test types available in the project. ### Findings List findings in priority order. For each include: - a concise title, priority, and confidence (high, medium, or low) - exact source locations and symbols - the unnecessary mechanism and evidence of redundancy - observable behavior that must survive - the smallest safe simplification - concrete runtime or maintenance benefit - risks and focused validation ### Keep Call out tempting mechanisms the audit found necessary, with the reason, so a future cleanup does not repeat the same investigation. ### Recommended Starting Point Choose one bounded first simplification, explain why it has the best payoff-to-risk ratio, and state any decision the user must make before implementation. If no worthwhile simplification exists, say so and summarize the evidence instead of inventing work. ## When the User Asks for Changes Apply one coherent opportunity at a time unless the user requests a broader migration. - Establish a targeted behavioral baseline before editing. - Remove obsolete state, callbacks, branches, tests, and imports without leaving parallel paths. - Search every project under `projects/` for remaining construction sites, references, and old terminology. - Run the target project's documented tests, type checking, linting, and build tasks as appropriate through `mise`, then run `git diff --check`. When reflection, slotting, or DOM synchronization changes, also run the project's `test:ssr`, `test:axe`, and `test:visual` tasks when it has them, since unit tests rarely catch those regressions. - Summarize the removed mechanisms, preserved behavior, validation, and any deferred candidates.