Back to Details

agile-refinement

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Refinement

优化评审

Use this skill to validate planning artifacts and review code quality. It operates in two modes: planning lint and code review.
Initial context received via slash: $ARGUMENTS
If 
$ARGUMENTS
is filled (e.g., file path, branch, "planning", "code"), use as starting point to determine mode. If empty, ask the user what they want to validate: planning artifacts or code changes.
使用该Skill验证规划工件并评审代码质量。它支持两种模式：规划检查（planning lint）和代码评审。
通过slash命令接收的初始上下文：$ARGUMENTS
若
$ARGUMENTS
已填写（例如：文件路径、分支、"planning"、"code"），以此为起点确定运行模式。 若为空，则询问用户要验证的内容：规划工件还是代码变更。

Language

语言要求

Write any report output in the user's language. Apply correct grammar and any required diacritics or script-specific characters. If the user's language is unclear, ask before generating output.
报告输出需使用用户的语言，语法正确，包含必要的变音符号或特定脚本字符。若用户语言不明确，需先询问再生成输出。

Objective

目标

  • Validate planning artifacts for consistency, completeness, and correctness
  • Review code changes for security, coherence, scope, and quality
  • Catch issues before they become problems in execution
  • Provide actionable, specific feedback — not generic observations
  • 验证规划工件的一致性、完整性和正确性
  • 评审代码变更的安全性、连贯性、范围和质量
  • 在问题演变为执行阶段的风险前及时发现
  • 提供可落地的具体反馈，而非泛泛而谈的观察

When to use

使用场景

  • Before starting implementation — lint the planning artifacts
  • Before committing code — review the diff
  • When opening a pull request — quality gate
  • When reviewing AI-generated code — human-equivalent review
  • Periodically — check for stale content, broken cross-references, or orphaned artifacts
  • When merging or completing an epic — validate all pieces fit together
  • 开始实施前——检查规划工件
  • 提交代码前——评审代码差异
  • 发起pull request时——作为质量门槛
  • 评审AI生成的代码时——提供等效于人工评审的结果
  • 定期执行——检查过时内容、失效的交叉引用或孤立工件
  • 合并或完成epic时——验证所有组件是否匹配

When NOT to use

非使用场景

  • Creating planning artifacts — use 
    /agile-intake
    , 
    /agile-epic
    , 
    /agile-story
    , 
    /agile-roadmap
  • Decomposing work into stories — use 
    /agile-epic
    (which now handles decomposition)
  • Tracking delivery progress — use 
    /agile-status
  • Planning a sprint — use 
    /agile-sprint
  • 创建规划工件——使用
    /agile-intake
    、
    /agile-epic
    、
    /agile-story
    、
    /agile-roadmap
  • 将工作分解为story——使用
    /agile-epic
    （目前已支持分解功能）
  • 跟踪交付进度——使用
    /agile-status
  • 规划sprint——使用
    /agile-sprint

Mode 1: Planning Lint

模式1：规划检查（Planning Lint）

Validates planning artifacts against the following checks:
针对以下检查项验证规划工件：

Cross-references

交叉引用

  • Origin fields point to existing files
  • Referenced epics, stories, and tasks exist
  • File paths in cross-references are correct and files are present
  • 来源字段指向已存在的文件
  • 引用的epic、story和task真实存在
  • 交叉引用中的文件路径正确且文件已存在

Dependencies

依赖关系

  • Declared dependencies between stories/tasks exist
  • No circular dependencies
  • Dependency order is consistent with the roadmap/epic sequence
  • story/task之间声明的依赖真实存在
  • 无循环依赖
  • 依赖顺序与路线图/epic序列一致

Completeness

完整性

  • Required sections are present (Context, Files, Detail, Tasks, Verification)
  • No empty required fields
  • Acceptance criteria are defined and verifiable
  • Tasks are specific and actionable (not vague)
  • 包含必填章节（上下文、文件、细节、任务、验证）
  • 必填字段无空值
  • 验收标准已定义且可验证
  • 任务具体且可执行（无模糊表述）

Product traceability

产品可追溯性

  • UI-heavy epics/stories reference prototype routes/screens when prototypes exist
  • Domain behavior references 
    business/*.md
    rule IDs/files when business rules exist
  • Prototypes do not carry internal implementation or business-rule explanations as visible product copy
  • Business rules discovered during prototype review were captured outside the prototype
  • No raw secrets, provider keys, tokens, or credentials appear in planning artifacts
  • 侧重UI的epic/story在原型存在时引用原型路由/页面
  • 领域行为在业务规则存在时引用
    business/*.md
    规则ID/文件
  • 原型中不会将内部实现或业务规则说明作为可见的产品文案
  • 原型评审中发现的业务规则已在原型外记录
  • 规划工件中无原始密钥、提供商密钥、令牌或凭证

Consistency

一致性

  • Sizing is consistent across related artifacts (stories within an epic)
  • Status fields are up to date
  • Naming conventions match across files
  • 相关工件的规模估算一致（同一epic下的story）
  • 状态字段已更新
  • 文件命名规则统一

Format

格式

  • File naming follows convention (
    00-overview.md
    , 
    NN-story-name.md
    )
  • Folder structure follows convention (
    planning/<initiative>/epics/NN-<epic>/
    )
  • Templates are properly filled (no leftover placeholder text)
  • 文件命名遵循约定（如
    00-overview.md
    、
    NN-story-name.md
    ）
  • 文件夹结构遵循约定（如
    planning/<initiative>/epics/NN-<epic>/
    ）
  • 模板已正确填写（无残留占位文本）

Scope conflicts

范围冲突

  • No overlapping scope between stories in the same epic
  • Out-of-scope items are not referenced as tasks
  • 同一epic下的story无范围重叠
  • 超出范围的内容未被作为task引用

Stale content

过时内容

  • No artifacts with all tasks completed but status still "in progress"
  • No referenced files that have been deleted or moved
  • No plans older than 30 days with incomplete tasks and no recent daily
  • 不存在所有任务已完成但状态仍为“进行中”的工件
  • 无已删除或移动的被引用文件
  • 不存在超过30天且任务未完成、近期无更新的规划

Process

流程

  1. Identify the scope: a single file, an epic folder, or the entire 
    planning/
    tree.
  2. Read all artifacts in scope.
  3. Run each check category above.
  4. Produce an inline report grouped by category with specific issues and locations.
  1. 确定范围：单个文件、epic文件夹或整个
    planning/
    目录树。
  2. 读取范围内的所有工件。
  3. 执行上述各分类的检查。
  4. 生成按分类分组的内嵌报告，包含具体问题及位置。

Mode 2: Code Review

模式2：代码评审

Reviews changed code applying the checklist from 
~/.agents/rules/code-review.md
:
应用
~/.agents/rules/code-review.md
中的检查清单评审变更代码：

Security

安全性

  • Inputs validated and sanitized
  • No SQL injection, XSS, command injection, or SSRF
  • No hardcoded secrets
  • Authentication and authorization correct when applicable
  • Sensitive data not exposed in logs or responses
  • 输入已验证和清理
  • 无SQL注入、XSS、命令注入或SSRF漏洞
  • 无硬编码密钥
  • 认证与授权逻辑正确（如适用）
  • 敏感数据未暴露在日志或响应中

Project Coherence

项目连贯性

  • Follows repository patterns and conventions
  • Uses existing components, utilities, and helpers
  • Did not reinvent the wheel
  • Naming consistent with codebase
  • Imports follow project conventions
  • 遵循仓库的模式与约定
  • 使用现有组件、工具函数和辅助类
  • 未重复造轮子
  • 命名与代码库保持一致
  • 导入规则符合项目约定

Over-engineering

过度设计

  • No premature abstractions
  • No error handling for impossible scenarios
  • No generalization for hypothetical requirements
  • 无过早抽象
  • 不为不可能的场景添加错误处理
  • 不为假设性需求做泛化设计

Scope

范围

  • Code does only what was requested
  • No refactoring of unrelated code
  • No additional features not requested
  • 代码仅实现需求内容
  • 未重构无关代码
  • 无额外的未请求功能

Quality

质量

  • Tests cover acceptance scenarios
  • Code readable without explanatory comments
  • Small functions with single responsibility
  • No logic duplication
  • Errors handled at system boundaries
  • 测试覆盖验收场景
  • 代码无需注释即可读懂
  • 函数粒度小且单一职责
  • 无逻辑重复
  • 在系统边界处理错误

Completeness

完整性

  • Lint passes
  • Typecheck passes
  • Tests pass
  • Diff read in full
  • Lint检查通过
  • 类型检查通过
  • 测试用例全部通过
  • 已完整阅读代码差异

Process

流程

  1. Identify the scope: branch, files, or working tree changes.
  2. Read the complete diff before issuing any output.
  3. Apply each check category.
  4. Produce an inline report grouped by category.
  5. Highlight red flags that justify immediate rejection.
  1. 确定范围：分支、文件或工作区变更。
  2. 先完整读取代码差异再输出内容。
  3. 执行上述各分类的检查。
  4. 生成按分类分组的内嵌报告。
  5. 高亮显示需要立即拒绝的红色警告项。

Output

输出

This skill does NOT produce a saved artifact. It produces an inline report with:
  • Issues grouped by category
  • Severity: red flag (reject), warning (fix before proceeding), info (consider)
  • Specific file and line references where applicable
  • Actionable suggestions for each issue
该Skill不会生成保存的工件，仅生成内嵌报告，包含：
  • 按分类分组的问题
  • 严重程度：红色警告（拒绝）、警告（推进前修复）、信息（建议考虑）
  • 适用情况下的具体文件和行号引用
  • 每个问题的可落地建议

Rules

规则

  • Read everything in scope before producing any output.
  • Be specific. "Code looks bad" is not actionable. "Replace 
    RateLimitError
    with 
    HttpError
    on line 42 of 
    src/middleware/rate-limit.ts
    " is.
  • AI code review does not replace human code review. This is an additional gate.
  • Planning lint can be run at any time — it's a health check, not a ceremony.
  • Never produce vague, generic feedback. Every issue must be verifiable.
  • 生成输出前需读取范围内的所有内容。
  • 反馈要具体。“代码看起来不好”不可落地，而“将
    src/middleware/rate-limit.ts
    第42行的
    RateLimitError
    替换为
    HttpError
    ”是可落地的。
  • AI代码评审不能替代人工代码评审，这是额外的质量门槛。
  • 规划检查可随时执行——它是健康检查，而非形式化流程。
  • 绝不输出模糊、泛泛的反馈。每个问题必须可验证。

Relationship with the flow

与流程的关系

mermaid
flowchart LR
    A["/agile-epic"] --> B["/agile-refinement<br>(planning lint)"]
    C["/agile-story"] --> D[execution]
    D --> E["/agile-refinement<br>(code review)"]
    E --> F["/agile-status"]
This skill validates artifacts and code at any point in the flow. For creating planning artifacts, use 
/agile-epic
or 
/agile-story
. For tracking delivery, use 
/agile-status
.
mermaid
flowchart LR
    A["/agile-epic"] --> B["/agile-refinement<br>(planning lint)"]
    C["/agile-story"] --> D[execution]
    D --> E["/agile-refinement<br>(code review)"]
    E --> F["/agile-status"]
该Skill可在流程的任意阶段验证工件和代码。创建规划工件请使用
/agile-epic
或
/agile-story
。跟踪交付进度请使用
/agile-status
。