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.

• 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)

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).

• 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

• 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

• 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

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

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.

• Cosmetic fix (dead code removal, unused imports, naming, control flow tightening, visibility reduction) -- applied automatically if within budget. This is the bread and butter of the skill.
• 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?"

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

[simplify-and-harden] Refactor proposal (1 of 2):

  I want to merge duplicated validation logic from handleCreate() and 
  handleUpdate() into a shared validatePayload() function.

  Why: Both functions validate the same fields with identical rules.
  The duplication was introduced because I built handleUpdate as a 
  copy of handleCreate during implementation.

  Files affected: src/api/handler.ts (lines 34-67)
  Estimated diff: -22 lines, +14 lines

  [approve] [reject] [show diff] [skip all refactors]

skip all refactors

flagged

skipped_by_user

"If someone malicious saw this code, what would they try?"

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?

• Patch (adding a validation check, escaping output, removing a hardcoded secret) -- applied automatically if within budget
• Security refactor (restructuring auth flow, replacing a vulnerable pattern with a new approach, changing data handling architecture) -- ALWAYS requires human approval before proceeding

[simplify-and-harden] Security refactor proposal:

  The new /admin/export endpoint inherits base authentication but has 
  no role-based access check. Any authenticated user can trigger a 
  full data export.

  Severity: HIGH
  Vector: Privilege escalation
  
  Proposed fix: Add role guard requiring 'admin' role before the 
  handler executes. This changes the middleware chain for this route.

  Files affected: src/api/routes/admin.ts (line 12)
  Estimated diff: +8 lines

  [approve] [reject] [show diff] [skip all security refactors]

• 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

• 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.

self-improvement

1. Normalize each finding into a

   pattern_key

   :
   • Simplify examples:

     simplify.dead_code

     ,

     simplify.naming

     ,

     simplify.control_flow

   • Harden examples:

     harden.input_validation

     ,

     harden.authorization

     ,

     harden.error_handling

2. Emit those pattern candidates in

   simplify_and_harden.learning_loop.candidates

   .
3. Hand off candidates to

   self-improvement

   , which logs or updates entries in

   .learnings/LEARNINGS.md

   (instead of creating duplicate one-off notes).
4. Mark candidates as promotion-ready when they cross the recurrence threshold:

   >= 3

   occurrences across

   >= 2

   distinct tasks in a 30-day window.
5. Promote promotion-ready patterns into the agent context/system prompt files (

   CLAUDE.md

   ,

   AGENTS.md

   ,

   .github/copilot-instructions.md

   , or equivalent) to reduce repeat issues.

self-improvement

• Refactor proposals are shown one at a time with clear rationale
• The agent pauses and waits for

  [approve]

  ,

  [reject]

  ,

  [show diff]

  , or

  [skip all refactors]

• Cosmetic fixes and straightforward security patches are applied automatically

simplify-and-harden-ci

references/agent-context-snippets.md

1. Scope lock -- only files modified in the current task
2. Budget cap -- 20% max additional diff
3. Simplify-first posture -- cleanup is the default, refactoring is the exception
4. Refactor stop hook -- structural changes always require human approval
5. Three passes -- simplify, harden, document (in that order)
6. Structured output -- summary of applied, approved, rejected, and flagged items

• Claude Code, GitHub Copilot Workspace, Codex, Opencode, OpenClaw, Cursor Agent, Windsurf, Aider, SWE-Agent, OpenHands, Devin, and any agent exposing a task completion lifecycle event

• Any LLM-based coding assistant that accepts post-task instructions -- the skill's logic can be injected as a follow-up prompt after the agent signals completion

agent.on('task:complete', async (context) => {
  if (context.diff.isNonTrivial() && !context.flags.includes('no-review')) {
    const result = await skills.run('simplify-and-harden', {
      diff: context.diff,
      files: context.modifiedFiles,
      budget: { maxLines: context.diff.linesChanged * 0.2, maxTime: 60000 }
    });
    context.appendOutput(result.summary);
  }
});

• Access to the diff produced by the completed task
• A list of modified files with full content
• The ability to present interactive prompts (for interactive mode)
• An output channel for the structured summary (stdout, PR comment, or equivalent)

• Team calibration: Allow teams to weight the review checklist (e.g., "we care more about injection vectors than naming")
• Diff-aware context loading: For large codebases, intelligently load only the files and symbols relevant to the diff rather than the full project
• Cross-skill composition: Simplify & Harden could feed into a "PR Description" skill that uses its summary to auto-generate meaningful PR descriptions