duck-patch

Patch execution 🦆. Smallest safe diff first.

Purpose

Execute a narrowly scoped code change once the fix direction is known.

Philosophy Guardrails (skill-local)

Inherit shared guardrails from references/GUARDRAILS.md.

Comment and Documentation Integrity

• Document durable constraints, invariants, contracts, and behavior.
• Do not narrate development history in code comments or ordinary documentation.
• Remove or flag rejected approaches, “this used to be” history, recent-change context, and references to reviews, tests, or sessions when they only explain how the change was produced.
• Do not preserve session-only decisions, approval flags, or temporary markers in durable artifacts.
• Keep historical context only in a durable artifact intended for history, such as an ADR or changelog.
• Keep test or review references only when they state a durable constraint or verification requirement.

Skill-specific delta:

• Executes bounded implementation only; product and architecture decisions remain with user.

Activation

Use when user asks for a targeted code edit and scope is clear (or can be clarified quickly).

Method

Subagent execution mode

When running as a subagent without a user channel (e.g., via duckling): do not apply edits or run commands. Execute scope clarification, Duck Ladder, and patch derivation as analysis; replace "apply minimal safe diff" and "run smallest agreed check" with approval-package content: the derived per-file diff blocks and verification plan. Emit per the host wrapper's contract (preflight + diffs + approval ask + status footer).

1. Clarify scope (if incomplete)

• ask 1-3 targeted clarifying questions when context is incomplete
• state assumptions explicitly when evidence is missing

Mutating action gate: Workspace-changing actions (require approval based on change type):

Semantic changes (require full execution approval):

• Code/logic changes
• Documentation/planning changes (README, markdown docs, ADRs, CONTEXT.md, runbooks, design notes), except typo-only fixes in non-code text files
• Config/schema changes (settings, env vars, build config)
• Dependency changes (package.json, requirements.txt, etc.)
• File operations (create, delete, move)
• Mutating commands (git commit, install, build, deploy)
• Task delegation for implementation/patching

Cosmetic changes (require lightweight confirmation):

• Formatting/whitespace-only changes
• Typo fixes in non-code text files
• Confirmation phrase: "Confirm to proceed with [formatting change/typo fix]?"

Edge cases:

• JSDoc/docstring changes in code files are semantic (affects generated docs, code contracts)
• Comments explaining logic in code are semantic (affects maintainability understanding)
• Config comments are semantic (affects interpretation)
• Document updates (ADRs, CONTEXT.md) are semantic
• Examples in README that are code snippets are semantic (users copy-paste)

Approval workflow: Before any semantic change, require execution approval:

1. Preflight (required for every approval ask; if a field is missing, ask one clarifying question):
   • target phase:
     • Phase 1: stubs/skeleton/interfaces
     • Phase 2: wiring/integration
     • Phase 3: concrete implementation
   • phase-fit statement (why this diff matches phase constraints)
   • target files (bounded for selected phase)
   • expected behavior change
   • smallest verification check
2. Present list of changes broken down by file as formatted diff
   • File exists: unified diff (---/+++/@@ hunks, -/+ prefixes)
   • File does not exist: full content in fenced code block, file path as header
   • One file per diff block
   • Inline an annotation above the diff hunks explaining each change
   • If any file violates phase constraints, split and re-propose before approval ask
3. Approval ask: Approve this scope? (examples: approve/ok/confirm)
4. Wait for approval: do not proceed with edits/commands/task delegation until user replies with explicit approval intent

Rules:

• No workspace-changing action without user approval/confirmation Approval intent tokens:

• Accept as approval intent: "approve", "approved", "ok", "go ahead", "confirm", "yes"

• Also accept option-referencing approval sentences: "Proceed with option B in files X and Y.", "Approved. Run verification plan as proposed."

• Examples are non-exhaustive. Any clear approval intent is accepted.

• Do not treat non-approval continuation signals as approval: bare "continue", bare option letters ("B"), "next". No approval verb, no scope reference — not approval.

Scope rules:

• Phase caps (default):

  • Phase 1 (stubs/skeleton/interfaces): up to 6 files
  • Phase 2 (wiring/integration): up to 4 files
  • Phase 3 (concrete implementation): up to 2 files

• Phase content constraints (hard gate):

  • Phase 1 (stubs/skeleton/interfaces) must contain only:
    • file/module skeleton shape (folders, exports, section layout)
    • type/interface declarations
    • function/class signatures
    • placeholder returns/errors/TODO markers
    • minimal no-op wiring with no business logic
  • Phase 1 must not contain:
    • full feature/business logic
    • side-effectful flows (DB/network/auth/file writes)
    • complete UI behavior beyond placeholders
  • Phase 2 (wiring/integration) can contain:
    • route registration, DI/container wiring, module composition, event hookups
    • adaptation glue between existing components
  • Phase 2 must not contain:
    • substantial new business logic blocks
  • Phase 3 (concrete implementation) contains:
    • business logic, algorithms, side effects, full behavior completion

• New-file bootstrap rule:

  • If scope introduces new feature files, first approval pass must be Phase 1 stubs/skeleton/interfaces only.
  • Implement bodies in later Phase 2/3 approvals.
  • If a new file exceeds stub/skeleton intent, split that file into stub-first then implementation follow-up.

• If a phase exceeds its cap, split into smaller bounded approvals before executing.

• Review-fatigue triggers (objective):

  • Phase 1 (stubs/skeleton/interfaces):
    • If proposed diff in one approval exceeds 180 changed lines (additions + deletions) total, reduce current phase cap by at least 1 file (minimum cap is 1 file).
    • If any single file exceeds 90 changed lines (additions + deletions), split that file into a separate approval or smaller sequential edits.
  • Phase 2 (wiring/integration):
    • If proposed diff in one approval exceeds 120 changed lines (additions + deletions) total, reduce current phase cap by at least 1 file (minimum cap is 1 file).
    • If any single file exceeds 60 changed lines (additions + deletions), split that file into a separate approval or smaller sequential edits.
  • Phase 3 (concrete implementation):
    • If proposed diff in one approval exceeds 80 changed lines (additions + deletions) total, reduce current phase cap by at least 1 file (minimum cap is 1 file).
    • If any single file exceeds 40 changed lines (additions + deletions), split that file into a separate approval or smaller sequential edits.
  • If reviewer requests clarification on more than 2 files in same batch, reduce next batch by at least 1 file.

• If complexity or review fatigue increases, reduce cap further and continue in smaller batches.

• Reopen execution approval between phases, even when objective stays same.

• If scope changes after approval, reopen scope confirmation before continuing.

• Phase examples (application):

  • Phase 1 example: 5 files, 170 changed lines (additions + deletions) total, max single file 80 changed lines (additions + deletions). This is within cap and thresholds, so one approval can proceed.
  • Phase 2 example: 4 files, 130 changed lines (additions + deletions) total. This exceeds phase total threshold, so split into 2 approvals before execution.
  • Phase 3 example: 2 files, one file at 45 changed lines (additions + deletions). This exceeds single-file threshold, so split into smaller sequential edits.

2. Apply Duck Ladder

Before introducing new constructs, stop at first rung that holds:

1. No change needed (YAGNI)
2. Reuse existing local helper/pattern
3. Replace with stdlib/native
4. Use already-installed dependency
5. Shrink to smallest safe diff
6. Only then add new code/abstraction

When adding or modifying comments, write only the durable constraint or behavior a later reader needs.

3. Execute patch

1. Restate bounded scope and expected behavior.
2. Touch the smallest shared fix location (avoid caller-by-caller patching).
3. Reuse existing local helpers/patterns before adding new abstraction.
4. Apply minimal safe diff.
5. Run smallest agreed check.
6. Report exactly: changed files, behavior delta, verification result.

Output:

• one-line execution plan (file(s) + expected behavior)
• minimal patch summary (what changed, not a full essay)
• one smallest verification check and result
• if blocked: one-line blocker + next required input

Boundaries

• Do not weaken security, trust boundaries, data-loss prevention, accessibility, or explicit user requirements.
• If root cause is unclear, hand back to duck-debug (trace mode if needed) instead of speculative edits.
• If verification cannot run locally, provide exact command user should run and expected signal.