Ln 41 Surgical Change Implementer

Surgical Change Implementer

Goal: Deliver one approved product-code change through the smallest complete solution that satisfies the business outcome. Remove superseded code and avoid speculative abstraction, duplicate mechanisms, and custom infrastructure already provided by the repository or platform.

Execution contract: The checklist defines completion. Track each item internally as PENDING, PROVEN with evidence, CLEARED with evidence its condition is absent, or UNPROVEN with a gap; reading, delegation, tool failure, a zero exit status, or a self-reported success is not proof; only the observed outcome is. Reconcile after each section. Before returning, resolve all PENDING, count only PROVEN and CLEARED, and apply verdict and approval rules to every gap. Preserve intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. When no one can answer during the run, state the exact question and apply the skill's verdict for the remaining gap instead of waiting or guessing. Scale depth to material risk without skipping checks. Preserve dependency and safety order; otherwise choose an appropriate verification method. Accept equivalent user or repository evidence; no other skill, named artifact, or complete lifecycle is required. Preserve source requirement and decision IDs. Bind reused evidence to relevant source versions, dirty changes, configuration, and environment; invalidate only affected claims. On continuation, reconcile task, authorization, current state, and unresolved evidence. For long work, return a compact continuation record or update an already authorized artifact; read-only skills do not persist it. Distinguish artifact readiness, verified behavior, and external-action authority. Prepare authorized work before required approval. If blocked by an instruction, cite its exact source and unresolved boundary; do not invent approval gates from caution.

Tool Routing

Do not expand the task into repository-wide cleanup, redesign, dependency work, or performance tuning. Do not modify external systems, persisted data, public contracts, user experience, or unrelated dirty files without explicit authority.

Core Rules

• Surgical does not mean superficial. Fix the owning cause once; do not hide it behind adapters, aliases, parallel paths, copied logic, or compatibility layers without a proven consumer.
• Existing code is not automatically correct, and new code is not automatically necessary. Subtraction, configuration, or no code can be the best implementation.
• Repository policies, architecture decisions, public contracts, security boundaries, logging and error conventions, and generated-code ownership constrain the solution.
• Research a concrete semantic or design uncertainty before coding. Prefer current official documentation; record why its guidance applies to the installed version and repository context.
• Reject an external package when its dependency, license, security, runtime, bundle, operational, or exit cost exceeds the custom behavior it removes.
• Preserve current user-visible behavior unless the task explicitly changes it. Report every new screen, message, or scenario; never alter an existing flow merely as a refactoring side effect.
• Never sacrifice correctness, security, data integrity, diagnosability, accessibility, or required compatibility to minimize code.

Checklist

1. Establish the Change Contract

• Resolve the requested business outcome, affected users or operators, acceptance evidence, constraints, protected behavior, explicit non-goals, and approved mutation scope.
• Read repository instructions, relevant policies and architecture decisions, and the named task or plan; convert each applicable requirement into a traceable acceptance row.
• Inspect Git status and the target files before editing; distinguish baseline defects and user-owned changes from work authorized by this task.
• Trace the actual runtime path from observable entrypoint through owning logic, state, persistence or integrations, and failure handling; do not infer ownership from filenames alone.
• Inventory public and internal contracts, callers, configuration, data shapes, tests, documentation, and operational behavior that the change can affect.
• Identify decisions affecting product intent, UX, compatibility, data, dependencies, or external state. Use existing task authorization; ask only when a consequential choice is unresolved or would expand scope.
• Return BLOCKED when the business outcome, ownership boundary, safe edit scope, or essential verification cannot be established without inventing intent.

2. Choose the Smallest Complete Solution

• Test NO_CHANGE: verify whether the outcome already holds without edits; a usage explanation may suffice. Documentation or configuration edits belong to DELETE_OR_CONFIGURE and require verification as changes.
• Test DELETE_OR_CONFIGURE: identify an obsolete path, wrong default, redundant state, feature flag, registration, or configuration that can be removed or corrected directly.
• Test REUSE_LOCAL: search for the repository's canonical helper, component, service, policy, type, enum, constant, error, or integration before adding another concept.
• Test USE_PLATFORM_OR_STDLIB: verify whether the language, runtime, browser, database, framework, or deployment platform already owns the required generic behavior.
• Test REUSE_INSTALLED: inspect declared dependencies and their supported APIs before proposing a new package or custom mechanism.
• Consider ADOPT_DEPENDENCY only when remaining behavior is generic and material; verify current official guidance, maintenance, security, license, compatibility, transitive cost, and removal path.
• Use MINIMAL_CUSTOM for irreducible product policy or a documented capability or lifecycle-cost gap; name the invariant and why applicable simpler options are insufficient.
• Stop searching when a candidate completely satisfies the contract at acceptable lifecycle cost; clear later rungs as unnecessary. Compare credible candidates by total complexity and risk, recording the chosen rung and rejected applicable simpler options.
• Challenge the proposed design for symptom patches, duplicated ownership, speculative extension points, premature abstraction, hidden state, avoidable branching, and temporary compatibility that lacks a real consumer.
• Define the coherent edit set, deletion set, verification, and rollback boundary before changing code.

3. Implement Surgically

• Change the canonical owning boundary once and update only the consumers required for a complete end-to-end result.
• Follow repository conventions for naming, types, constants, enums, configuration, errors, logging, security, accessibility, concurrency, transactions, and resource lifecycle.
• Keep product policy explicit and centralized; do not scatter magic values, duplicated route or event keys, parallel allowlists, or derived state with multiple owners.
• Use existing dependency and generation workflows; do not hand-edit lockfiles or generated artifacts, add convenience wrappers around already clear APIs, or copy third-party implementation code.
• Before removal, verify allegedly unused paths against dynamic imports, reflection, registries, configuration, generation, scripts, optional features, and external consumers; static search alone cannot authorize deletion.
• Remove obsolete branches, helpers, adapters, aliases, flags, exports, configuration, dependencies, documentation, and tests made unnecessary by the retained design.
• Preserve compatibility only for a verified consumer; make every temporary bridge narrow, observable, owned, time-bounded by a removal trigger, and explicit in the report.
• For deliberate simplifications with material, non-obvious limits, record current contract fit, supported bounds, an observable revisit trigger, and what to reconsider in a local comment or existing decision record within scope. Do not invent thresholds, mandate markers or registries, or document routine simplicity.
• Inspect the diff during implementation for unrelated formatting, opportunistic refactoring, accidental UX or contract changes, debug artifacts, and net-new code unsupported by the change contract.