Finalize and commit

Skill: Finalize Changes and Commit (Cleanup, Deduplication, Hardcoded Audit)

Type: Execution

Purpose

Finalize current changes for production readiness.

Tasks:

• Remove duplicate logic
• Eliminate unnecessary code
• Audit and resolve hardcoded values
• Ensure consistency and build integrity
• Prepare structured commits

---

When to Use

• Before committing finalized work to a shared branch
• Before submitting a pull request for review
• After completing a refactoring session that touched multiple files
• When preparing a clean commit history from messy working changes

---

When NOT to Use

• Work-in-progress code that is still actively being developed
• Trivial single-line fixes (typo, formatting) that need no audit
• Initial prototyping or exploratory coding phases
• Changes already reviewed and approved through another skill

---

Inputs Required

Do not run this skill without:

• Working tree with uncommitted or staged changes
• Access to project build, lint, and test commands
• Knowledge of project commit conventions (if any)

Optional but recommended:

• Target branch context (e.g., main, release)
• List of intended change scope (files or modules)

---

Output Format

1. Issues Found
2. Actions Taken
3. Verification Results
4. Commit Plan
5. Final Commit Messages

---

Procedure

Gate 0 – Working Set Validation

CRITICAL: The working tree may contain changes from other agent sessions or manual edits. This gate must isolate only the current session's changes without disturbing anything else.

Step 0-1: Identify current session scope

• Review the conversation history and edit history of this session.
• Build an explicit list of files that were created, modified, or deleted by this session.
• If the user provided a scope list (files or modules), use that as the authoritative source.

Step 0-2: Inspect full working tree state

• Run git status and git diff --name-only to enumerate all uncommitted changes in the working tree.

Step 0-3: Classify changes

• In-scope: Files that appear in both the session scope (Step 0-1) and the working tree (Step 0-2).
• Out-of-scope: Files that appear in the working tree but were NOT modified by this session. These may belong to other agent sessions, manual edits, or background tooling.

Step 0-4: Protect out-of-scope changes

• NEVER revert, restore, checkout, stash, or discard out-of-scope changes.
• Out-of-scope files must be left exactly as they are in the working tree.
• The only correct action is to exclude them from staging (git add).

Step 0-5: Confirm with the user

• Present a summary to the user:
  • Files to be committed (in-scope)
  • Files left untouched (out-of-scope), if any
• Proceed only after the user confirms the commit target set.
• Validate that new/deleted in-scope files do not break entrypoints.

---

Gate 1 – Duplicate & Dead Code Detection

SCOPING RULE: Focus analysis on in-scope files only (from Gate 0). When checking for duplicates, search for similar patterns in the immediate module/directory first, then expand to adjacent modules only if duplication signals are found.

• Identify repeated logic blocks
  • If repeated ≥ 3 times → extract helper
  • Avoid over-abstraction
• Remove:
  • Unused variables
  • Dead branches
  • Debug prints
  • Stale TODOs without references

---

Gate 2 – Hardcoded Value Audit

SCOPE ADJUSTMENT: If all in-scope changes are limited to test files, documentation, or type definitions, perform a quick scan (search for numeric literals and string constants in the diff) instead of a full classification audit. The full audit is required when production logic files are in scope.

Classify hardcoded values into:

A) Algorithmic constants → Extract to named constant + documentation
B) Operational policies → Move to config/env + default fallback
C) Test-only values → Restrict to test scope

Ensure:

• No hidden policy decisions remain hardcoded
• Retry limits, timeouts, thresholds are explicit

---

Gate 3 – Consistency & Quality Review

Verify:

• Error handling patterns consistent
• Logging structure aligned with project conventions
• No PII/secrets exposed
• Public interface compatibility preserved
• No accidental performance regression

---

Gate 4 – Verification Proof

Run relevant project checks:

• Tests
• Lint
• Typecheck
• Build

If failures occur:

• Fix root cause
• Do not silence or bypass checks

---

Gate 5 – Commit Structuring

Staging rule: Stage only in-scope files confirmed in Gate 0. Use git add <specific-file> for each file individually. Never use git add ., git add -A, or git add --all.

Separate commits logically:

1. Refactor (no behavior change)
2. Functional change
3. Tests / documentation

Use Conventional Commits:

• fix(scope):
• feat(scope):
• refactor(scope):
• test(scope):
• docs(scope):
• chore(scope):

Each commit must explain:

• What changed
• Why it changed
• Risk considerations (if any)
• Test proof

---

Guardrails

• Do not silence or bypass failing checks.
• Do not combine unrelated changes in a single commit.
• Do not over-abstract when extracting helpers (repeated ≥ 3 times threshold).
• Explicitly state assumptions when classifying hardcoded values.
• If context is insufficient to determine intent, ask for clarification.
• Do not remove code without verifying it is truly unused.
• Respect existing project conventions for commit messages and structure.
• NEVER use git checkout -- <file>, git restore, git stash, git reset --hard, or any other command that discards or reverts uncommitted changes to files outside the current session's scope. Other sessions or agents may own those changes.
• NEVER use git add ., git add -A, or git add --all. Always stage files individually with git add <specific-file> to avoid accidentally including out-of-scope changes.
• Working tree changes from other sessions, agents, or manual edits must be left completely untouched.

---

Failure Patterns

Common bad outputs:

• Lumping all changes into a single large commit without logical separation
• Skipping build/lint/test verification before committing
• Ignoring hardcoded values because they "look fine"
• Over-extracting helpers for code repeated only once or twice
• Removing code that appears dead but is used via reflection or dynamic imports
• Producing commit messages that describe "what" but not "why"
• Reverting or discarding uncommitted changes that belong to other sessions or agents
• Using git add . or git add -A which accidentally stages out-of-scope changes
• Treating "ensure no unintended changes" as "revert unrelated files" instead of "exclude from staging"

---

Example 1 (Minimal Context)

Input:

3 files changed: a utility function was refactored, an unused import was found, and a debug console.log was left in.

Output:

1. Issues Found: unused import in utils/parse.ts, debug log in api/handler.ts
2. Actions Taken: removed unused import, removed debug log
3. Verification Results: lint pass, tests pass, build pass
4. Commit Plan: single refactor commit (scope is small)
5. Final Commit Messages: refactor(utils): clean up unused import and debug log

---

Example 2 (Realistic Scenario)

Input:

12 files changed across 3 modules. Includes a retry timeout hardcoded as 3000, duplicated validation logic in 4 handlers, and a new API endpoint.

Output:

1. Issues Found: hardcoded retry timeout (3000ms) in services/retry.ts, duplicated input validation in 4 route handlers, unused helper formatLegacy in utils/format.ts
2. Actions Taken: extracted retry timeout to config (RETRY_TIMEOUT_MS), created shared validateInput() helper, removed formatLegacy
3. Verification Results: all tests pass, lint pass, typecheck pass, build pass
4. Commit Plan: 3 commits — (a) refactor: extract shared validation, (b) refactor: move retry timeout to config, (c) feat: add new API endpoint
5. Final Commit Messages:
   • refactor(validation): extract shared validateInput helper from route handlers
   • refactor(retry): move hardcoded timeout to config as RETRY_TIMEOUT_MS
   • feat(api): add POST /items endpoint with input validation

---

Notes

FAST MODE (only if explicitly requested):

• Skip deep hardcoded classification
• Allow single commit only if scope is small