simplify-and-harden

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Skill: Simplify & Harden

Agent技能：简化与强化

Install

安装

bash

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

For CI-only execution, use:

bash

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

bash

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

若仅用于CI执行，请使用：

bash

npx skills add pskoett/pskoett-ai-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

字段	值
技能ID	`simplify-and-harden`
版本	0.1.0
触发方式	任务完成后钩子
作者	Peter Skøtt Pedersen
分类	代码质量 / 安全
优先级	推荐使用

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.

当编码Agent完成一项任务时，它对问题、解决方案以及过程中做出的权衡决策拥有最清晰的上下文理解。这种上下文会立即消失——下一个任务会清空当前状态。Simplify & Harden技能利用这个上下文峰值窗口，在Agent切换任务前执行两次针对性的自我审查。

大多数Agent完成任务后就会停止工作。而本技能能将“完成”升级为“高质量完成”。

其核心操作理念是在切换任务前进行一次刻意的“旁观者视角”自我审查：仔细重读所有新编写的代码和任务中修改的既有代码，认真排查明显的bug、错误、混乱逻辑、脆弱假设、命名问题以及遗漏的安全强化机会。目标不是扩大任务范围或重写解决方案——而是利用当前清晰的上下文，在Agent仍记得每一处变更意图时，执行一次严谨的首轮审查。

Best Use with Independent Review

与独立审查的配合使用

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

Recommended flow:

Implement the task.
Run Simplify & Harden to clean, harden, and document non-obvious decisions.
Run an independent review pass for severity-ordered findings.
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.

本技能是任务完成后的自我审查环节，不能替代独立的人工审查。

推荐流程：

完成任务开发。
运行Simplify & Harden进行代码清理、安全强化，并为非直观决策添加文档说明。
执行独立审查，按严重程度处理发现的问题。
仅在两次审查的问题都得到解决后再合并代码。

若两次审查的结论不一致，以独立审查的结果作为最终标准，要么修复问题，要么明确标记并豁免相关问题。

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:

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

当且仅当以下所有条件满足时，本技能自动激活：

Agent已完成其主要编码任务
Agent发出任务完成信号（退出码0、PR就绪或同等状态）
代码变更差异包含非琐碎的代码修改（定义见下文）
本技能尚未在当前任务中运行过（避免重复执行循环）

非琐碎代码变更的定义

当代码差异同时满足以下两个条件时，视为非琐碎变更：

涉及至少一个可执行源文件（例如：

*.ts

*.tsx

*.js

*.jsx

*.py

*.go

*.rs

*.java

*.cs

*.rb

*.php

*.swift

*.kt

*.scala

*.sh

）。

满足以下任一情况：
- 可执行源文件中至少有10行非注释、非空白的代码变更，OR
- 包含至少一处高影响逻辑变更（身份验证/授权检查、输入验证、数据访问/查询逻辑、外部命令执行、文件路径处理、网络请求处理或并发控制）。

若代码变更仅涉及文档、配置、注释、格式调整、生成的产物或测试代码，则视为非琐碎变更不成立。

在以下情况中，本技能不会激活：

Agent任务失败或被中断
仅涉及文档的变更
仅涉及测试代码的变更
仅涉及生成文件的变更（锁文件、构建产物）
用户通过
```
--no-review
```
或等效显式跳过

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

硬性规则：仅修改当前任务中变更过的代码。

Agent绝对不能：

重构未在当前任务中修改的相邻代码
在变更范围外进行“顺手改进”
引入新的依赖或架构变更
根据其他地方发现的模式进行推测性修复

对于超出范围的问题，Agent应在输出总结中标记出来，而非直接修改。

资源限制：

最大新增变更量：原始代码差异大小的20%（按变更行数计算）
最长执行时间：60秒（可配置）
若任一限制被触发，Agent将停止操作，并输出已完成的内容，同时标记
```
budget_exceeded
```
标志

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?"

目标： 消除开发过程中引入的不必要复杂度。

默认原则：简化，而非重构。 本阶段的主要目标是轻量级清理——移除冗余内容、优化命名、删除死代码。Agent应优先选择不改变代码结构的 cosmetic 修复。重构是例外，而非常规操作。

强制要求：以旁观者视角重新审视：在本阶段进行任何编辑前，以“旁观者视角”重读当前任务中新增或修改的所有代码，主动排查明显的bug、错误、混乱逻辑、脆弱假设、命名问题以及遗漏的安全强化机会。

Agent会自我审查并问自己：

"既然我已经理解了完整的解决方案，有没有更简洁的方式来表达这段逻辑？"

Review Checklist

审查清单

Dead code and scaffolding -- Did I leave behind debug logs, commented-out attempts, unused imports, or temporary variables from my iteration loop? Remove them.
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.
Control flow -- Can any nested conditionals be flattened? Can early returns replace deep nesting? Are there boolean expressions that could be simplified? Tighten them.
API surface -- Did I expose more than necessary? Could any public methods/functions be private? Reduce visibility.
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.
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.

死代码与脚手架 —— 是否遗留了调试日志、注释掉的尝试代码、未使用的导入或迭代过程中遗留的临时变量？请移除它们。
命名清晰度 —— 函数名、变量名和参数名在重新阅读时是否清晰易懂？开发过程中合理的命名，在完成后可能变得难以理解。请重命名它们。
控制流 —— 是否可以扁平化嵌套的条件判断？是否可以用提前返回替代深层嵌套？是否有可以简化的布尔表达式？请优化它们。
API暴露面 —— 是否暴露了不必要的内容？是否有公共方法/函数可以改为私有？请减少可见性。
过度抽象 —— 是否创建了当前范围不需要的类、接口或包装函数？Agent往往会过度设计。请标记此类问题，但除非收益显著，否则不要重构。
合并机会 —— 是否将逻辑分散在多个函数或文件中，而它们本可以放在一起？请标记此类问题，但仅在重复代码非常严重且合并操作清晰简洁时，才建议重构。

Simplify Actions

简化操作

For each finding, the agent categorizes it as:

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?"

Refactor Stop Hook (mandatory):

Any change the agent classifies as a refactor triggers an interactive prompt. The agent MUST:

Describe what it wants to change and why
Show the before/after (or a clear description of the structural change)
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.

[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]

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

Cosmetic fixes do not trigger the stop hook. They are applied silently (and reported in the output summary). The rationale: removing an unused import is not a judgment call. Restructuring code is.

对于每个发现的问题，Agent会将其分类为：

Cosmetic修复（删除死代码、未使用的导入、优化命名、优化控制流、减少可见性）—— 若在资源限制内，自动应用。这是本技能的核心价值所在。
重构（合并逻辑、调整结构、修改抽象）—— 仅当Agent判断确实必要或收益显著时才会提出建议。重构不是默认操作。判断标准是：“资深工程师看到这段代码时，是否会认为当前状态明显错误，而非只是不够完美？”

重构停止钩子（强制要求）：

任何被Agent归类为重构的变更都会触发交互式提示。Agent必须：

描述想要修改的内容及原因
展示修改前后的对比（或清晰描述结构变更）
等待用户明确批准后再执行

Agent不会批量提出重构建议。每个重构建议都会单独呈现，以便用户逐个批准、拒绝或修改。

[simplify-and-harden] 重构建议（1/2）：

  我想要将handleCreate()和handleUpdate()中重复的验证逻辑合并到共享的validatePayload()函数中。

  原因：两个函数用完全相同的规则验证相同的字段。
  重复代码是因为我在开发时将handleUpdate复制自handleCreate。

  涉及文件：src/api/handler.ts（第34-67行）
  预估变更行数：减少22行，增加14行

  [批准] [拒绝] [查看差异] [跳过所有重构]

若用户选择

跳过所有重构

，Agent将跳过剩余的重构建议，进入强化阶段。被跳过的重构建议仍会在输出总结中标记为

flagged

，状态为

skipped_by_user

。

Cosmetic修复不会触发停止钩子。它们会自动应用（并在输出总结中报告）。原因是：移除未使用的导入不需要判断，而重构代码则需要。

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?"

目标： 在Agent仍理解代码意图时，填补安全与弹性漏洞。

Agent会自我审查并问自己：

"如果恶意攻击者看到这段代码，他们会尝试什么攻击方式？"

Review Checklist

审查清单

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.
Error handling -- Are catch blocks specific? Are errors logged with context but without leaking sensitive data? Are there any swallowed exceptions?
Injection vectors -- Check for SQL injection, XSS, command injection, path traversal, and template injection in any code that builds strings from external input.
Authentication and authorization -- Do new endpoints or functions enforce auth? Are permission checks present and correct? Is there any privilege escalation risk?
Secrets and credentials -- Are there hardcoded secrets, API keys, tokens, or passwords? Are connection strings parameterized? Check for credentials in log output.
Data exposure -- Does error output, logging, or API responses leak internal state, stack traces, database schemas, or PII?
Dependency risk -- Did the agent introduce new dependencies? If so, are they well-maintained, properly versioned, and free of known vulnerabilities?
Race conditions and state -- For concurrent code: are shared resources properly synchronized? Are there TOCTOU (time-of-check-to-time-of-use) vulnerabilities?

输入验证 —— 所有外部输入（用户输入、API参数、文件路径、环境变量）在使用前是否都经过验证？检查类型转换问题、缺失的边界检查以及无约束的字符串长度。
错误处理 —— catch块是否具体？错误日志是否包含上下文但不泄露敏感数据？是否有被吞掉的异常？
注入风险 —— 检查任何从外部输入构建字符串的代码中是否存在SQL注入、XSS、命令注入、路径遍历和模板注入风险。
身份验证与授权 —— 新的端点或函数是否强制要求身份验证？权限检查是否存在且正确？是否存在权限提升风险？
密钥与凭证 —— 是否存在硬编码的密钥、API密钥、令牌或密码？连接字符串是否参数化？检查日志输出中是否包含凭证。
数据泄露 —— 错误输出、日志或API响应是否泄露内部状态、堆栈跟踪、数据库架构或个人身份信息（PII）？
依赖风险 —— Agent是否引入了新的依赖？如果是，这些依赖是否维护良好、版本正确且无已知漏洞？
竞态条件与状态 —— 对于并发代码：共享资源是否正确同步？是否存在TOCTOU（检查时间与使用时间不一致）漏洞？

Harden Actions

强化操作

For each finding, the agent categorizes it as:

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

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:

[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

Security patches (not refactors) are prioritized over simplification changes when budget is constrained.

对于每个发现的问题，Agent会将其分类为：

补丁（添加验证检查、转义输出、移除硬编码密钥）—— 若在资源限制内，自动应用
安全重构（调整认证流程、用新方法替换脆弱模式、更改数据处理架构）—— 始终需要用户批准才能执行

第一阶段的重构停止钩子同样适用于此。安全重构建议会单独呈现，并附加严重程度和攻击向量的上下文：

[simplify-and-harden] 安全重构建议：

  新的/admin/export端点继承了基础身份验证，但没有基于角色的访问检查。任何已认证用户都可以触发全量数据导出。

  严重程度：高
  攻击向量：权限提升
  
  修复建议：在处理器执行前添加角色守卫，要求用户拥有'admin'角色。这会修改该路由的中间件链。

  涉及文件：src/api/routes/admin.ts（第12行）
  预估变更行数：增加8行

  [批准] [拒绝] [查看差异] [跳过所有安全重构]

标记为严重 —— Agent无法在无用户输入的情况下安全修复的问题（无论是否批准，都会在输出中标记）
标记为建议 —— 属于安全强化机会，但并非主动漏洞的问题

当资源受限时，安全补丁（而非重构）的优先级高于简化变更。

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.

目标： 在Agent仍记得决策原因时，记录非直观的决策依据。

本阶段刻意保持轻量化——不是完整的文档编写，只是决策记录。

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.

对于任何需要超过5秒思考“为什么要这么写？”的逻辑：添加单行注释说明决策依据
对于任何临时解决方案或hack：添加注释说明上下文，最好附上TODO标记及移除条件
对于任何性能敏感的选择：说明为什么选择当前方案而非其他明显的替代方案
上限：每个任务最多添加5条注释。这不是文档编写冲刺。

Output Schema

输出格式

The skill produces a structured summary appended to the task output:

yaml

simplify_and_harden:
  version: "0.1.0"
  task_id: "<original task ID>"
  execution:
    mode: "interactive"
    mode_source: "auto_detected"  # "auto_detected", "config", "env_override"
    human_present: true
  scope:
    files_reviewed: ["src/api/handler.ts", "src/utils/validate.ts"]
    original_diff_lines: 142
    additional_changes_lines: 18
    budget_exceeded: false

  simplify:
    applied:
      - file: "src/api/handler.ts"
        line: 45
        type: "consolidation"
        category: "refactor"
        approval: "approved_by_user"
        description: "Merged duplicated validation logic from handleCreate and handleUpdate into shared validatePayload function"
    flagged:
      - file: "src/utils/validate.ts"
        type: "over-abstraction"
        category: "refactor"
        approval: "skipped_by_user"
        description: "ValidationStrategy interface may be unnecessary -- only one implementation exists. Consider inlining if no additional strategies are planned."
        confidence: "medium"
    cosmetic_applied:
      - file: "src/api/handler.ts"
        line: 12
        type: "dead_code"
        description: "Removed unused import of deprecated AuthHelper"

  harden:
    applied:
      - file: "src/api/handler.ts"
        line: 62
        type: "input_validation"
        severity: "high"
        description: "Added bounds check on pageSize parameter -- previously accepted arbitrary integers"
    flagged_critical:
      - file: "src/api/handler.ts"
        type: "authorization"
        description: "New /admin/export endpoint inherits base auth but no role check -- any authenticated user can access it. Requires human decision on role policy."
    flagged_advisory:
      - file: "src/utils/validate.ts"
        type: "error_handling"
        description: "Catch block on L31 logs full request body which may contain PII in production"

  document:
    comments_added: 2
    locations:
      - file: "src/api/handler.ts"
        line: 78
        comment: "// Pagination uses cursor-based approach instead of offset -- offset breaks when items are deleted between pages"
      - file: "src/api/handler.ts" 
        line: 93
        comment: "// WORKAROUND: Legacy API returns dates as strings without timezone. Assuming UTC until migration completes (see TICKET-1234)"

  learning_loop:
    target_skill: "self-improvement"
    log_file: ".learnings/LEARNINGS.md"
    candidates:
      - pattern_key: "simplify.dead_code"
        pass: "simplify"
        finding_type: "dead_code"
        severity: "low"
        source_file: "src/api/handler.ts"
        source_line: 12
        suggested_rule: "Remove dead code and unused imports before finalizing a task."
      - pattern_key: "harden.input_validation"
        pass: "harden"
        finding_type: "input_validation"
        severity: "high"
        source_file: "src/api/handler.ts"
        source_line: 62
        suggested_rule: "Validate and bound-check external inputs before use."
    recurrence_window_days: 30
    promotion_threshold:
      min_occurrences: 3
      min_distinct_tasks: 2

  summary:
    simplify_applied: 1
    simplify_cosmetic_applied: 1
    simplify_flagged: 1
    simplify_rejected_by_user: 0
    simplify_skipped_by_user: 1
    harden_applied: 1
    harden_flagged_critical: 1
    harden_flagged_advisory: 1
    harden_rejected_by_user: 0
    comments_added: 2
    total_additional_lines: 18
    budget_utilization: "12.7%"
    human_prompts_shown: 3
    human_prompts_approved: 1
    human_prompts_rejected: 0
    human_prompts_skipped: 1
    human_prompts_timed_out: 1
    learning_candidates: 2
    learning_promotions_recommended: 1
    review_followup_required: true

Set

review_followup_required

true

when any unresolved finding remains (critical/advisory flags, skipped or timed-out refactor proposals), or when

budget_exceeded

true

. Set it to

false

only when no follow-up is required.

本技能会生成结构化总结，并附加到任务输出中：

yaml

simplify_and_harden:
  version: "0.1.0"
  task_id: "<原始任务ID>"
  execution:
    mode: "interactive"
    mode_source: "auto_detected"  # "auto_detected", "config", "env_override"
    human_present: true
  scope:
    files_reviewed: ["src/api/handler.ts", "src/utils/validate.ts"]
    original_diff_lines: 142
    additional_changes_lines: 18
    budget_exceeded: false

  simplify:
    applied:
      - file: "src/api/handler.ts"
        line: 45
        type: "consolidation"
        category: "refactor"
        approval: "approved_by_user"
        description: "将handleCreate和handleUpdate中重复的验证逻辑合并到共享的validatePayload函数"
    flagged:
      - file: "src/utils/validate.ts"
        type: "over-abstraction"
        category: "refactor"
        approval: "skipped_by_user"
        description: "ValidationStrategy接口可能不必要——仅存在一个实现。若没有计划添加其他策略，考虑内联实现。"
        confidence: "medium"
    cosmetic_applied:
      - file: "src/api/handler.ts"
        line: 12
        type: "dead_code"
        description: "移除了已弃用AuthHelper的未使用导入"

  harden:
    applied:
      - file: "src/api/handler.ts"
        line: 62
        type: "input_validation"
        severity: "high"
        description: "为pageSize参数添加了边界检查——之前接受任意整数"
    flagged_critical:
      - file: "src/api/handler.ts"
        type: "authorization"
        description: "新的/admin/export端点继承了基础身份验证，但没有角色检查——任何已认证用户都可以访问。需要用户决定角色策略。"
    flagged_advisory:
      - file: "src/utils/validate.ts"
        type: "error_handling"
        description: "第31行的catch块记录了完整请求体，在生产环境中可能包含PII"

  document:
    comments_added: 2
    locations:
      - file: "src/api/handler.ts"
        line: 78
        comment: "// 分页使用基于游标而非偏移量的方式——当页面间有数据删除时，偏移量会失效"
      - file: "src/api/handler.ts" 
        line: 93
        comment: "// 临时解决方案：旧版API返回的日期是无时区的字符串。在迁移完成前假设为UTC（见TICKET-1234）"

  learning_loop:
    target_skill: "self-improvement"
    log_file: ".learnings/LEARNINGS.md"
    candidates:
      - pattern_key: "simplify.dead_code"
        pass: "simplify"
        finding_type: "dead_code"
        severity: "low"
        source_file: "src/api/handler.ts"
        source_line: 12
        suggested_rule: "在完成任务前移除死代码和未使用的导入。"
      - pattern_key: "harden.input_validation"
        pass: "harden"
        finding_type: "input_validation"
        severity: "high"
        source_file: "src/api/handler.ts"
        source_line: 62
        suggested_rule: "在使用外部输入前进行验证和边界检查。"
    recurrence_window_days: 30
    promotion_threshold:
      min_occurrences: 3
      min_distinct_tasks: 2

  summary:
    simplify_applied: 1
    simplify_cosmetic_applied: 1
    simplify_flagged: 1
    simplify_rejected_by_user: 0
    simplify_skipped_by_user: 1
    harden_applied: 1
    harden_flagged_critical: 1
    harden_flagged_advisory: 1
    harden_rejected_by_user: 0
    comments_added: 2
    total_additional_lines: 18
    budget_utilization: "12.7%"
    human_prompts_shown: 3
    human_prompts_approved: 1
    human_prompts_rejected: 0
    human_prompts_skipped: 1
    human_prompts_timed_out: 1
    learning_candidates: 2
    learning_promotions_recommended: 1
    review_followup_required: true

当存在未解决的问题（严重/建议标记、跳过或超时的重构建议），或

budget_exceeded

为true时，将

review_followup_required

设置为

true

。仅当无需后续操作时，才设置为

false

。

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 run:

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

Emit those pattern candidates in

simplify_and_harden.learning_loop.candidates

Hand off candidates to
```
self-improvement
```
, which logs or updates entries in
```
.learnings/LEARNINGS.md
```
(instead of creating duplicate one-off notes).
Mark candidates as promotion-ready when they cross the recurrence threshold:
```
>= 3
```
occurrences across
```
>= 2
```
distinct tasks in a 30-day window.
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.

This keeps Simplify & Harden focused on per-task cleanup/hardening while

self-improvement

owns cross-task memory and promotion.

Simplify & Harden会将重复出现的质量/安全问题反馈给

self-improvement

技能，以便将重复问题转化为持久的提示规则。

每次运行后：

将每个发现的问题标准化为

pattern_key

：

简化阶段示例：

simplify.dead_code

simplify.naming

simplify.control_flow

强化阶段示例：

harden.input_validation

harden.authorization

harden.error_handling

在

simplify_and_harden.learning_loop.candidates

中输出这些模式候选。

将候选模式交给
```
self-improvement
```
技能，该技能会在
```
.learnings/LEARNINGS.md
```
中记录或更新条目（而非创建重复的一次性笔记）。
当候选模式达到重复阈值时，标记为可升级：30天内，在至少2个不同任务中出现至少3次。
将可升级的模式整合到Agent上下文/系统提示文件中（
```
CLAUDE.md
```
,
```
AGENTS.md
```
,
```
.github/copilot-instructions.md
```
或等效文件），以减少重复问题的出现。

这样可以让Simplify & Harden专注于单任务的清理/强化，而

self-improvement

负责跨任务的记忆和规则升级。

Execution Model

执行模式

This skill is for general coding-agent sessions where a human can approve refactors in-line.

Behavior:

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

For CI pipelines and headless automation, use

simplify-and-harden-ci

本技能适用于通用编码Agent会话，用户可以在会话中即时批准重构建议。

行为特点：

重构建议逐个呈现，并附带清晰的理由

Agent会暂停并等待用户选择

[批准]

[拒绝]

[查看差异]

或

[跳过所有重构]

Cosmetic修复和简单的安全补丁会自动应用

对于CI流水线和无头自动化场景，请使用

simplify-and-harden-ci

。

Agent Context File References

Agent上下文文件引用

To activate this skill, reference it in your agent context file.

Agent-specific copy-paste snippets are in

references/agent-context-snippets.md

. Load only the snippet for your active agent to keep context lean.

Core invariants for any agent integration:

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

Precaution: some agents may not reliably pause for approval in high-autonomy modes. Validate this behavior before production use.

要激活本技能，请在Agent上下文文件中引用它。

针对不同Agent的复制粘贴代码片段位于

references/agent-context-snippets.md

中。仅加载当前使用Agent对应的片段，以保持上下文简洁。

任何Agent集成的核心不变量：

范围锁定 —— 仅处理当前任务中修改的文件
资源上限 —— 新增变更不超过原始差异的20%
优先简化原则 —— 清理是默认操作，重构是例外
重构停止钩子 —— 结构变更始终需要用户批准
三阶段流程 —— 简化、强化、文档（按此顺序）
结构化输出 —— 总结已应用、已批准、已拒绝和已标记的内容

注意事项：部分Agent在高自治模式下可能无法可靠地暂停等待批准。在生产环境使用前，请验证此行为。

Agent Compatibility

Agent兼容性

This skill is designed to work with any coding agent that follows a task-based workflow. It is not tied to any specific agent framework or product.

Programmatic integration (agents with skill/hook APIs):

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

Prompt-based integration (chat-based agents without formal skill APIs):

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

The output schema is agent-agnostic YAML. Consuming tools only need to parse the structured summary.

本技能设计为可与任何基于任务流程的编码Agent配合使用，不绑定特定的Agent框架或产品。

程序化集成（支持技能/钩子API的Agent）：

Claude Code、GitHub Copilot Workspace、Codex、Opencode、OpenClaw、Cursor Agent、Windsurf、Aider、SWE-Agent、OpenHands、Devin，以及任何暴露任务完成生命周期事件的Agent

基于提示的集成（无正式技能API的聊天式Agent）：

任何接受任务后指令的基于LLM的编码助手——可以在Agent发出完成信号后，将本技能的逻辑作为后续提示注入

输出格式为与Agent无关的YAML。消费工具只需解析结构化总结即可。

Integration Notes

集成说明

This skill is agent-agnostic. It hooks into any coding agent that exposes a task completion lifecycle event. The examples below are generic -- adapt them to your agent's specific API.

本技能与Agent无关。它可以挂钩到任何暴露任务完成生命周期事件的编码Agent。以下示例为通用示例——请根据Agent的具体API进行调整。

Agent Integration

Agent集成

The skill hooks into the agent's task completion lifecycle. Suggested integration pattern:

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);
  }
});

Agents that support this skill should implement the following interface:

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)

本技能挂钩到Agent的任务完成生命周期。推荐的集成模式：

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);
  }
});

支持本技能的Agent应实现以下接口：

访问已完成任务的代码差异
获取修改文件的完整内容列表
能够呈现交互式提示（适用于交互式模式）
输出结构化总结的渠道（标准输出、PR评论或等效方式）

Prompt-based Integration

基于提示的集成

For agents that don't support programmatic skill hooks (e.g., chat-based coding agents like Claude Code, Cursor, Copilot Chat), this skill can be implemented as a post-task prompt injection:

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 (merging functions, changing 
   abstractions, restructuring) 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.

对于不支持程序化技能钩子的Agent（例如Claude Code、Cursor、Copilot Chat等聊天式编码Agent），可以将本技能作为任务后提示注入：

完成任务后，运行Simplify & Harden审查：
1. 仅审查你修改的文件
2. 简化：默认操作是清理——移除死代码、未使用的导入、优化命名、优化控制流、减少不必要的公共暴露面。直接应用这些修改。重构（合并函数、更改抽象、调整结构）不是默认操作。仅当代码确实错误或改进收益显著时，才提出重构建议。若提出建议，请描述内容并在应用前请求批准。
3. 强化：检查输入验证漏洞、注入风险、认证问题、暴露的密钥和错误处理问题。直接应用简单的补丁。对于涉及结构变更的安全重构，请描述问题及严重程度，并请求批准。
4. 文档：最多添加5条关于非直观决策的注释。
5. 输出总结，说明你修改了什么、标记了什么以及忽略了什么。

CI Pipeline Variant

CI流水线变体

For GitHub Actions or other CI/headless usage, run

simplify-and-harden-ci

对于GitHub Actions或其他CI/无头场景，请运行

simplify-and-harden-ci

。

Configuration

配置

yaml

undefined

yaml

undefined

Example configuration (adapt path to your agent's config format)

示例配置（根据Agent的配置格式调整路径）

e.g., .agent/skills.yaml, .claude/skills.yaml, .cursor/skills.yaml

例如：.agent/skills.yaml, .claude/skills.yaml, .cursor/skills.yaml

simplify-and-harden: enabled: true budget: max_diff_ratio: 0.2 # Max additional changes as ratio of original diff max_time_seconds: 60 # Hard time limit simplify: enabled: true auto_apply_cosmetic: true # Cosmetic fixes applied without prompting refactor_requires_approval: true # ALWAYS true -- cannot be disabled harden: enabled: true auto_apply_patches: true # Simple security patches applied without prompting refactor_requires_approval: true # ALWAYS true -- cannot be disabled document: enabled: true max_comments: 5 stop_hook: mode: "interactive" show_diff_preview: true allow_skip_all: true timeout_seconds: 300 # 5 min -- human is at the keyboard timeout_action: "flag" # Assume they stepped away, don't discard skip_patterns: # Glob patterns to exclude from review - "/.test." - "/.spec." - "/migrations/"

undefined

simplify-and-harden: enabled: true budget: max_diff_ratio: 0.2 # 新增变更占原始差异的最大比例 max_time_seconds: 60 # 最长时间限制 simplify: enabled: true auto_apply_cosmetic: true # Cosmetic修复自动应用，无需提示 refactor_requires_approval: true # 始终为true——无法禁用 harden: enabled: true auto_apply_patches: true # 简单安全补丁自动应用，无需提示 refactor_requires_approval: true # 始终为true——无法禁用 document: enabled: true max_comments: 5 stop_hook: mode: "interactive" show_diff_preview: true allow_skip_all: true timeout_seconds: 300 # 5分钟——假设用户在旁操作 timeout_action: "flag" # 假设用户暂时离开，不丢弃内容 skip_patterns: # 排除在审查外的Glob模式 - "/.test." - "/.spec." - "/migrations/"

undefined

Design Decisions

设计决策

Why post-completion and not continuous? Continuous review during implementation creates feedback loops that slow the agent down and can cause oscillation (simplify, then re-complicate, then re-simplify). Post-completion gives the agent a stable codebase to review against.

Why simplify-first, not refactor-first? Agents love to refactor. Given permission to "improve" code, they will restructure it. But most post-task improvements are cosmetic: a dead import, a bad name, a needlessly deep conditional. These account for 80%+ of the value with near-zero risk. Refactoring carries real risk -- it can introduce bugs, break tests, and bloat diffs. By making simplification the default and refactoring the exception, the skill delivers consistent value without surprise rewrites. The bar for a refactor should be "this is genuinely wrong" not "this could be slightly better."

Why a budget? Without constraints, agents will use review passes as license for unbounded refactoring. The 20% rule keeps the skill focused: improve what you built, don't rebuild it.

Why separate simplify from harden? They require different mindsets. Simplify asks "is this the clearest expression of my intent?" while Harden asks "how could this be exploited?" Conflating them leads to mediocre results on both. Running them sequentially also lets us prioritize security fixes when budget is tight.

Why the document micro-pass? Agents are terrible at documenting their reasoning unprompted. Humans reviewing agent-generated code consistently report that the biggest friction is understanding why a choice was made. Five comments is a trivial cost for enormous review-time savings.

为什么选择任务完成后而非持续审查？ 开发过程中的持续审查会创建反馈循环，拖慢Agent速度，并可能导致振荡（简化、再复杂化、再简化）。任务完成后审查为Agent提供了稳定的代码库作为审查基准。

为什么优先简化而非重构？ Agent热衷于重构。若允许“改进”代码，它们会调整代码结构。但大多数任务后的改进都是cosmetic的：死导入、糟糕的命名、不必要的深层条件判断。这些改进贡献了80%以上的价值，且风险几乎为零。重构存在真实风险——可能引入bug、破坏测试、扩大代码差异。通过将简化设为默认操作，重构设为例外，本技能能持续提供价值，且不会带来意外的重写。重构的判断标准应该是“这段代码确实错误”而非“这段代码可以稍微改进”。

为什么设置资源限制？ 若无约束，Agent会将审查环节作为无限制重构的许可。20%的规则让本技能保持聚焦：改进你编写的代码，而非重写它。

为什么将简化与强化分开？ 它们需要不同的思维模式。简化问的是“这是否是我意图的最清晰表达？”而强化问的是“这段代码可能被如何利用？”将它们混在一起会导致两方面的结果都不尽如人意。按顺序执行还能让我们在资源受限时优先处理安全修复。

为什么设置文档微阶段？ Agent在无提示的情况下，记录自己的推理过程的能力很差。审查Agent生成代码的人类一致反馈，最大的障碍是理解“为什么”做出某个选择。添加5条注释的成本极低，但能大幅节省审查时间。

Future Considerations

未来规划

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

团队校准：允许团队调整审查清单的权重（例如：“我们更关注注入风险而非命名”）
差异感知上下文加载：对于大型代码库，智能加载仅与差异相关的文件和符号，而非整个项目
跨技能组合：Simplify & Harden可以为“PR描述”技能提供输入，利用其总结自动生成有意义的PR描述