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 just completed, the diff touches executable source files with 10+ changed lines or high-impact logic (auth, validation, queries, file paths, network, concurrency). Feeds recurring findings into self-improving-agent via .learnings/LEARNINGS.md.
argument-hint	Run after completing a coding task. Provide the list of modified files if not auto-detected.

Agent Skill: Simplify & Harden

Post-completion self-review: clean, harden, and document your work before moving on.

Source: https://clawhub.ai/pskoett/simplify-and-harden (v1.0.1, MIT-0, VirusTotal: Benign, OpenClaw: Benign HIGH CONFIDENCE)

Trigger Conditions

Activate automatically when ALL of the following are true:

1. The agent has completed its primary coding task
2. The diff contains a non-trivial code change:
   • Touches at least one executable source file (*.py, *.ts, *.js, *.go, *.rs, etc.)
   • AND includes either ≥10 changed non-comment/non-whitespace lines OR at least one high-impact logic change (auth/authz, input validation, data access, external commands, file paths, network requests, concurrency)
3. The skill has not already run on this task (no re-entry loops)

Does NOT activate when:

• The change is docs-only, config-only, comments-only, formatting-only, generated artifacts only, or tests-only
• The agent failed or was interrupted
• User explicitly skips via --no-review

Scope Constraints

Hard rule: Only touch code modified in this task.

• Do NOT refactor adjacent code that was not modified
• Do NOT introduce new dependencies or architectural changes
• 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 (lines changed)
• Maximum execution time: 60 seconds
• If either limit is hit, stop and output what you have with a budget_exceeded flag

Pass 1: Simplify

Objective: Reduce unnecessary complexity introduced during implementation.

Default posture: Simplify, don't restructure. Bias heavily toward cosmetic fixes. Refactoring is the exception.

Fresh-eyes start (mandatory): Before any edits, re-read all code added or modified with fresh eyes. Actively look for obvious bugs, confusing logic, brittle assumptions, and naming issues.

Review Checklist

• Dead code — debug logs, commented-out attempts, unused imports, temp variables
• Naming clarity — function/variable names that made sense mid-implementation but read poorly after
• Control flow — nested conditionals that can be flattened, deep nesting replaceable by early returns
• API surface — exposed more than necessary? Can public methods become private?
• Over-abstraction — classes or wrappers not justified by current scope
• Consolidation — logic spread across functions/files when it could live in one place

Simplify Actions

• Cosmetic fix (dead code, unused imports, naming, control flow, visibility reduction) → applied automatically if within budget
• Refactor (consolidation, restructuring, abstraction changes) → proposed ONLY when genuinely necessary

Refactor Stop Hook (mandatory): Any refactor triggers an interactive prompt:

[simplify-and-harden] Refactor proposal (N of M):

  What: [description]
  Why: [rationale]
  Files affected: [list]
  Estimated diff: [+/- lines]

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

Wait for explicit human approval before applying. Do not batch refactor proposals.

Pass 2: Harden

Objective: Close security and resilience gaps while the agent still understands the code's intent.

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

Review Checklist

• Input validation — external inputs validated before use? Type coercion, bounds checks, unconstrained strings?
• Error handling — catch blocks specific? Errors logged without leaking sensitive data? Swallowed exceptions?
• Injection vectors — SQL injection, XSS, command injection, path traversal, template injection
• Auth/authz — new endpoints enforce auth? Permission checks present and correct? Privilege escalation risk?
• Secrets — hardcoded API keys, tokens, passwords? Connection strings parameterized? Credentials in logs?
• Data exposure — error output leaks internal state, stack traces, DB schemas, or PII?
• Dependency risk — new dependencies introduced? Well-maintained, properly versioned, no known CVEs?
• Race conditions — shared resources synchronized? TOCTOU vulnerabilities?

Harden Actions

• Patch (adding validation, escaping output, removing hardcoded secret) → applied automatically if within budget
• Security refactor (restructuring auth flow, replacing vulnerable pattern) → ALWAYS requires human approval

Same Refactor Stop Hook applies with added severity and attack vector context.

Pass 3: Document (Micro-pass)

Objective: Capture non-obvious decisions while the agent still remembers why it made them.

Rules:

• For logic requiring >5 seconds of "why does this exist?" thought: add a single-line comment
• For any workaround or hack: add a comment with context and a TODO with removal conditions
• For performance-sensitive choices: note why current approach was chosen over obvious alternative
• Maximum: 5 comments added per task

Self-Improvement Integration

After each run, normalize recurring findings into pattern_keys and hand off to self-improving-agent:

learning_loop:
  target_skill: "self-improvement"
  log_file: ".learnings/LEARNINGS.md"
  candidates:
    - pattern_key: "simplify.dead_code"     # simplify.* or harden.*
      pass: "simplify"
      finding_type: "dead_code"
      severity: "low"
      source_file: "src/..."
      source_line: 12
      suggested_rule: "Remove dead code before finalizing a task."

Promote to .learnings/LEARNINGS.md when a pattern crosses the recurrence threshold:

• ≥3 occurrences across ≥2 distinct tasks in a 30-day window
• Then consider promotion to CLAUDE.md, AGENTS.md, or .github/copilot-instructions.md

Output Schema

simplify_and_harden:
  version: "0.1.0"
  task_id: "<original task ID>"
  execution:
    mode: "interactive"
    human_present: true
  scope:
    files_reviewed: [...]
    original_diff_lines: N
    additional_changes_lines: N
    budget_exceeded: false
  simplify:
    applied: [...]
    flagged: [...]
    cosmetic_applied: [...]
  harden:
    applied: [...]
    flagged_critical: [...]
    flagged_advisory: [...]
  document:
    comments_added: N
    locations: [...]
  learning_loop:
    candidates: [...]
  summary:
    simplify_applied: N
    harden_applied: N
    harden_flagged_critical: N
    comments_added: N
    budget_utilization: "X%"
    review_followup_required: true|false

Set review_followup_required: true when any unresolved finding remains (critical/advisory flags, skipped refactors) or budget_exceeded: true.

Prompt-based Integration (GitHub Copilot)

After completing the task, run the Simplify & Harden review:

1. Review only the files you modified
2. Simplify: Your default action is cleanup — remove dead code, unused imports, fix naming, tighten control flow, reduce unnecessary public surface. Apply these directly. Refactoring is NOT the default. Only propose a refactor when the code is genuinely wrong or the improvement is substantial. If you propose one, describe it and ask for approval before applying.
3. Harden: Check for input validation gaps, injection vectors, auth issues, exposed secrets, and error handling problems. Apply simple patches directly. For security refactors that change structure, describe the issue with severity and ask for approval.
4. Document: Add up to 5 comments on non-obvious decisions.
5. Output a summary of what you changed, what you flagged, and what you left alone.

Core Invariants

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