Post-completion self-review for coding agents that runs simplify, harden, re-verification, and micro-documentation passes on non-trivial code or high-impact configuration changes. Use when a task is complete in a general agent session and you want a bounded quality and security sweep before signalin

Agent Skill: Simplify & Harden Install For CI only execution, use: Fallback using the Agent Skills CLI: 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 either condition is true: 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 ) and 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). 2. It changes configuration, workflow, permissions, deployment, or security policy in a way that can alter who may act, what executes, what is deployed, or which protections apply. Treat the diff as non trivial = false when it is docs only, low impact 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 files 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 that is demonstrably behavior preserving. 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 boolean expressions that could be simplified? Tighten them. 4. API surface Did I expose more than necessary? Could any public methods/functions be private? Reduce visibility. 5. Over abstraction Did I create classes, interfaces, or wrapper functions that aren't justified by the current scope? Agents tend to over engineer. Flag it, but don't restructure unless the win is significant. 6. Consolidation opportunities Did I spread logic across multiple functions or files when it could live in one place? Flag it, but only propose a refactor if the duplication is egregious and the consolidation is clean. Simplify Actions For each finding, the agent categorizes it as: Behavior preserving fix (for example, removing a provably unused import or task created dead code) applied automatically if within budget. Observable or uncertain change (including naming, control flow, visibility, API, policy, permission, deployment, or security behavior) proposed for human approval even when the diff is small. Refactor (consolidation, restructuring, abstraction changes) proposed ONLY when the agent determines it is genuinely necessary or the benefit is substantial. A refactor is not the default action. The bar is: "Would a senior engineer look at this and say the current state is clearly wrong, not just imperfect?" Refactor Stop Hook (mandatory): Any change the agent classifies as a refactor triggers an interactive prompt. The agent MUST: 1. Describe what it wants to change and why 2. Show the before/after (or a clear description of the structural change) 3. Wait for explicit human approval before applying The agent does not batch refactor proposals. Each refactor is presented individually so the human can approve, reject, or modify on a case by case basis. If the human selects skip all refactors , the agent skips remaining refactor proposals and moves to the Harden pass. Skipped refactors still appear in the output summary as flagged with status skipped by user . Only changes proven behavior preserving do not trigger the stop hook. The category label never overrides observable behavior: a rename, branch rewrite, or visibility reduction may be externally significant and must be approved when its effect is uncertain. Pass 2: Harden Objective: Close security and resilience gaps while the agent still understands the code's intent. The agent reviews its own work and asks: "If someone malicious saw this code, what would they try?" Review Checklist 1. Input validation Are all external inputs (user input, API params, file paths, environment variables) validated before use? Check for type coercion issues, missing bounds checks, and unconstrained string lengths. 2. Error handling Are catch blocks specific? Are errors logged with context but without leaking sensitive data? Are there any swallowed exceptions? 3. Injection vectors Check for SQL injection, XSS, command injection, path traversal, and template injection in any code that builds strings from external input. 4. Authentication and authorization Do new endpoints or functions enforce auth? Are permission checks present and correct? Is there any privilege escalation risk? 5. Secrets and credentials Are there hardcoded secrets, API keys, tokens, or passwords? Are connection strings parameterized? Check for credentials in log output. 6. Data exposure Does error output, logging, or API responses leak internal state, stack traces, database schemas, or PII? 7. Dependency risk Did the agent introduce new dependencies? If so, are they well maintained, properly versioned, and free of known vulnerabilities? 8. Race conditions and state For concurrent code: are shared resources properly synchronized? Are there TOCTOU (time of check to time of use) vulnerabilities? Harden Actions For each finding, the agent categorizes it as: Patch (adding a validation check, escaping output, removing a hardcoded secret) applied automatically only when the approved acceptance contract already requires it and targeted verification can prove the result; otherwise request human approval Security refactor (restructuring auth flow, replacing a vulnerable pattern with a new approach, changing data handling architecture) ALWAYS requires human approval before proceeding The same Refactor Stop Hook from the Simplify pass applies here. Security refactors are presented individually with the added context of severity and attack vector: Flagged as critical findings the agent cannot safely patch without human input (noted in output regardless of approval) Flagged as advisory hardening opportunities that are not active vulnerabilities Security patches (not refactors) are prioritized over simplification changes when budget is constrained. Pass 3: Document (Micro pass) Objective: Capture non obvious decisions while the agent still remembers why it made them. This is deliberately lightweight not a documentation pass, just decision capture. Rules For any logic that requires more than 5 seconds of "why does this exist?" thought: add a single line comment explaining the decision For any workaround or hack: add a comment with context and ideally a TODO with conditions for removal For any performance sensitive choice: note why the current approach was chosen over the obvious alternative Maximum: 5 comments added per task. This is not a documentation sprint. Pass 4: Re verify Re verification is mandatory before signaling completion. 1. If Simplify & Harden changed any file, re run the smallest existing tests, checks, linters, or behavioral acceptance that cover those edits. 2. If it made no edits, the immediately preceding verify gate evidence may be reused when it still covers the reviewed diff. 3. If verification fails, return to implementation with the diagnostics; do not emit a successful completion. 4. If no applicable verification exists, record not run , set review followup required: true , and do not claim the task is fully verified. Output Schema The skill produces a structured summary appended to the task output: Set review followup required to true when any unresolved finding remains (critical/advisory flags, skipped or timed out refactor proposals), when budget exceeded is true , or when verification is not pass . Set it to false only when no follow up is required. Self Improvement Integration (Learning Loop) Simplify & Harden feeds its recurring quality/security findings into the self improvement skill so repeated issues can become durable prompt rules. After each

simplify-and-harden