/simplify-and-harden

name: simplify-and-harden
description: "Post-completion self-review for coding agents that runs simplify, harden, and micro-documentation passes on non-trivial code changes. Use when: a coding task is complete in a general agent session and you want a bounded quality and security sweep before signaling done. For CI pipeline execution, use simplify-and-harden-ci."

Agent Skill: Simplify & Harden

Install

gh skill install pskoett/pskoett-skills simplify-and-harden

For CI-only execution, use:

gh skill install pskoett/pskoett-skills simplify-and-harden-ci

Fallback using the Agent Skills CLI:

npx skills add pskoett/pskoett-skills/skills/simplify-and-harden
npx skills add pskoett/pskoett-skills/skills/simplify-and-harden-ci

Metadata

| Field | Value | |---------------|--------------------------------| | Skill ID | `simplify-and-harden` | | Version | 0.1.0 | | Trigger | Post-completion hook | | Author | Peter Skøtt Pedersen | | Category | Code Quality / Security | | Priority | Recommended |

Rationale and Philosophy

When a coding agent completes a task, it holds peak contextual understanding of the problem, the solution, and the tradeoffs it made along the way. This context degrades immediately -- the next task wipes the slate. Simplify & Harden exploits that peak context window to perform two focused review passes before the agent moves on.

Most agents solve the ticket and stop. This skill turns "done" into "done well."

The operating philosophy is a deliberate "fresh eyes" self-review before moving on: carefully re-read all newly written code and all existing code modified in the task, and look hard for obvious bugs, errors, confusing logic, brittle assumptions, naming issues, and missed hardening opportunities. The goal is not to expand scope or rewrite the solution -- it is to use peak context to perform a disciplined first review pass while the agent still remembers the intent behind every change.

Best Use with Independent Review

This skill is a post-completion self-pass and does not replace an independent review pass.

Recommended flow: 1. Implement the task. 2. Run Simplify & Harden to clean, harden, and document non-obvious decisions. 3. Run an independent review pass for severity-ordered findings. 4. Merge only after both passes are addressed.

If the two disagree, treat the independent review findings as the external gate and either fix or explicitly waive findings.

Trigger Conditions

The skill activates automatically when ALL of the following are true:

• The agent has completed its primary coding task
• The agent signals task completion (exit code 0, PR ready, or equivalent)
• The diff contains a non-trivial code change (see definition below)
• The skill has not already run on this task (no re-entry loops)

**Non-trivial code change definition**

Treat a diff as non-trivial when it satisfies BOTH of the following:

1. It touches at least one executable source file (for example: `*.ts`, `*.tsx`, `*.js`, `*.jsx`, `*.py`, `*.go`, `*.rs`, `*.java`, `*.cs`, `*.rb`, `*.php`, `*.swift`, `*.kt`, `*.scala`, `*.sh`). 2. It includes either:

• At least 10 changed non-comment, non-whitespace lines in executable source files, OR
• At least one high-impact logic change (auth/authz checks, input validation, data access/query logic, external command execution, file path handling, network request handling, or concurrency control).

Treat the diff as non-trivial = false when it is docs-only, config-only, comments-only, formatting-only, generated artifacts only, or tests-only.

The skill does NOT activate when:

• The agent failed or was interrupted
• The change is documentation-only
• The change is tests-only
• The change is a generated file (lockfiles, build artifacts)
• The user explicitly skips it via `--no-review` or equivalent flag

Scope Constraints

**Hard rule: Only touch code modified in this task.**

The agent MUST NOT:

• Refactor adjacent code it did not modify
• Pursue "while I'm here" improvements outside the diff
• Introduce new dependencies or architectural changes
• Make speculative fixes based on patterns it noticed elsewhere

The agent SHOULD flag out-of-scope concerns in the summary output rather than acting on them.

**Budget limits:**

• Maximum additional changes: 20% of the original diff size (measured in lines changed)
• Maximum execution time: 60 seconds (configurable)
• If either limit is hit, the agent stops and outputs what it has with a `budget_exceeded` flag

Pass 1: Simplify

**Objective:** Reduce unnecessary complexity introduced during implementation.

**Default posture: simplify, don't restructure.** The primary goal of this pass is lightweight cleanup -- removing noise, tightening naming, killing dead code. The agent should bias heavily toward cosmetic fixes that make the code cleaner without changing its structure. Refactoring is the exception, not the rule.

**Fresh-eyes start (mandatory):** Before making any edits in this pass, re-read all code added or modified in this task with "fresh eyes" and actively look for obvious bugs, errors, confusing logic, brittle assumptions, naming issues, and missed hardening opportunities.

The agent reviews its own work and asks:

> "Now that I understand the full solution, is there a simpler way to express this?"

Review Checklist

1. **Dead code and scaffolding** -- Did I leave behind debug logs, commented-out attempts, unused imports, or temporary variables from my iteration loop? Remove them.

2. **Naming clarity** -- Do function names, variables, and parameters make sense when read fresh? Names that made sense mid-implementation often read poorly after the fact. Rename them.

3. **Control flow** -- Can any nested conditionals be flattened? Can early returns replace deep nesting? Are there boo