pdd-skills 3.0.0

package/skills/core/pdd-doc-change/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: pdd-doc-change
+description: PDD框架下的文档变更管理Skill，管理开发规格文档修改工作流。当需求变更需要更新规格文档时调用。支持中文触发：文档变更、规格修改、需求变更、变更管理。
+license: MIT
+compatibility: 需要已有的开发规格文档
+metadata:
+  author: "neuqik@hotmail.com"
+  version: "1.0"
+  parent: pdd-main
+---
+
+# PDD 文档变更管理 (pdd-doc-change) / Document Change Management
+
+## 核心概念 / Core Concepts
+
+### 🇨🇳 核心概念
+
+本Skill是PRD驱动开发(PDD)框架下的文档变更管理组件,专门用于管理开发规格文档的修改工作流,确保文档变更的系统性、完整性和可追溯性。
+
+### 🇺🇸 Core Concepts
+
+This Skill is a document change management component within the PRD-Driven Development (PDD) framework, specifically designed to manage the modification workflow of development specification documents, ensuring systematic, complete, and traceable document changes.
+
+## 触发时机 / Trigger Conditions
+
+### 🇨🇳 触发时机
+
+**自动触发**: 需求变更需要更新开发规格 | 功能点实现过程中发现规格问题
+
+**手动触发**: 用户输入`/analyze`/`/audit`/`/doc`等命令 | 用户明确要求修改设计文档
+
+### 🇺🇸 Trigger Conditions
+
+**Auto-triggered**: Requirement changes require updating development specs | Specification issues discovered during feature point implementation
+
+**Manual trigger**: User inputs `/analyze`/`/audit`/`/doc` commands | User explicitly requests design document modifications
+
+## 核心能力 / Core Capabilities
+
+### 🇨🇳 核心能力
+
+1. **文档导入与分析**: 解析现有规格文档 | 提取变更关键点 | 建立文档结构索引 | 识别文档间依赖关系
+
+2. **修改计划生成**: 对比分析现有规格 | 生成系统性修改计划(修改范围/内容/优先级P0-P2/实施步骤)
+
+3. **TODO.md生成**: 结构化任务清单(任务ID/修改内容/关联文档/优先级/状态/修改说明)
+
+4. **文档修改执行**: 根据TODO.md对指定规格文档进行修改 | 确保符合技术规范 | 保持文档风格一致性
+
+5. **CHANGELOG.md维护**: 记录详细变更信息(时间/文档/内容摘要/前后对比/关联需求ID)
+
+6. **变更校验与核对**: 比对TODO.md与CHANGELOG.md | 验证所有计划修改已实施并记录 | 检查文档间一致性
+
+7. **结果报告生成**: 总体完成情况 | 已完成/未完成项 | 一致性校验结果 | 后续建议
+
+### 🇺🇸 Core Capabilities
+
+1. **Document Import & Analysis**: Parse existing specification documents | Extract key change points | Build document structure index | Identify inter-document dependencies
+
+2. **Modification Plan Generation**: Comparative analysis of existing specs | Generate systematic modification plan (scope/content/priority P0-P2/implementation steps)
+
+3. **TODO.md Generation**: Structured task list (task ID/modification content/associated document/priority/status/modification notes)
+
+4. **Document Modification Execution**: Modify specified spec documents per TODO.md | Ensure compliance with technical standards | Maintain consistent document style
+
+5. **CHANGELOG.md Maintenance**: Record detailed change information (time/document/content summary/before-after comparison/associated requirement ID)
+
+6. **Change Verification & Validation**: Compare TODO.md with CHANGELOG.md | Verify all planned modifications implemented and documented | Check inter-document consistency
+
+7. **Result Report Generation**: Overall completion status | Completed/incomplete items | Consistency verification results | Follow-up recommendations
+
+## 工作流程 / Workflow
+
+### 🇨🇳 工作流程
+
+接收修改需求 → 分析变更文档/需求 → 对比现有规格文档 → 生成修改计划 → 创建TODO.md → 执行文档修改 → 更新CHANGELOG.md → 变更校验 → [全部完成?] → 是:生成结果报告 | 否:继续执行修改
+
+### 🇺🇸 Workflow
+
+Receive modification request → Analyze change documents/requirements → Compare with existing spec documents → Generate modification plan → Create TODO.md → Execute document modifications → Update CHANGELOG.md → Change verification → [All complete?] → Yes:Generate result report | No:Continue modifications
+
+## 与PDD流程集成 / PDD Process Integration
+
+### 🇨🇳 与PDD流程集成
+
+需求变更发生 → pdd-doc-change分析变更影响 → 确定需要修改的规格文档 → 生成修改计划和TODO → 执行文档修改 → 更新CHANGELOG → 校验变更完整性 → 通知相关功能点重新验证
+
+### 🇺🇸 PDD Process Integration
+
+Requirement change occurs → pdd-doc-change analyzes change impact → Determine spec documents to modify → Generate modification plan and TODO → Execute document modifications → Update CHANGELOG → Verify change completeness → Notify related feature points for re-validation
+
+## 使用场景 / Use Cases
+
+### 🇨🇳 使用场景
+
+1. **需求变更管理**: 业务需求变化时系统性更新相关规格文档
+2. **版本迭代更新**: 产品版本迭代时的规格文档同步更新
+3. **问题修复记录**: 基于用户反馈修复文档中的错误或遗漏
+4. **合规性调整**: 根据新法规或内部制度调整规格内容
+5. **流程优化**: 业务流程优化后的规格文档更新
+
+### 🇺🇸 Use Cases
+
+1. **Requirement Change Management**: Systematically update related specification documents when business requirements change
+2. **Version Iteration Updates**: Synchronize specification document updates during product version iterations
+3. **Issue Fix Records**: Fix errors or omissions in documents based on user feedback
+4. **Compliance Adjustments**: Adjust specification content according to new regulations or internal policies
+5. **Process Optimization**: Update specification documents after business process optimization
+
+## 操作规范 / Operational Standards
+
+### 🇨🇳 操作规范
+
+#### 文档命名规范
+TODO.md: `dev-specs/`目录下 | CHANGELOG.md: `dev-specs/`目录下 | 修改计划:`变更计划.md` | 结果报告:`变更完成报告.md`
+
+#### 任务优先级定义
+
+| 优先级 | 定义 | 处理方式 |
+|--------|------|----------|
+| P0 | 紧急且重要(影响核心业务流程或合规性) | 立即执行 |
+| P1 | 重要不紧急(重要的功能改进) | 短期内完成 |
+| P2 | 可优化(体验优化或补充说明) | 可延后处理 |
+
+#### 变更日志格式
+```markdown
+### [版本号] - YYYY-MM-DD
+#### 新增 | #### 修改 | #### 删除 | #### 修复
+```
+
+### 🇺🇸 Operational Standards
+
+#### Document Naming Conventions
+TODO.md: Under `dev-specs/` directory | CHANGELOG.md: Under `dev-specs/` directory | Modification Plan:`变更计划.md` | Result Report:`变更完成报告.md`
+
+#### Task Priority Definition
+
+| Priority | Definition | Handling |
+|----------|------------|----------|
+| P0 | Urgent & Critical (affects core business processes or compliance) | Execute immediately |
+| P1 | Important but Not Urgent (important feature improvements) | Complete within short term |
+| P2 | Can Optimize (experience optimization or supplementary notes) | Can be deferred |
+
+#### Change Log Format
+```markdown
+### [Version] - YYYY-MM-DD
+#### Added | #### Modified | #### Deleted | #### Fixed
+```
+
+## 输出模板 / Output Templates
+
+### 🇨🇳 输出模板
+
+#### TODO.md模板
+```markdown
+# 规格文档修改任务清单
+## 修改背景 | ## 关联功能点(FP-XXX)
+## 任务列表: ### [任务ID]-[任务名称](优先级/关联文档/修改内容/状态/备注)
+```
+
+#### 变更完成报告模板
+```markdown
+# 规格文档变更完成报告
+## 基本信息(变更主题/日期/负责人/关联需求)
+## 完成情况(总任务数/已完成/完成率)
+## 已完成修改项 | ## 文档一致性校验
+## 影响的功能点(FP-ID/名称/影响程度/需要重新验证)
+## 后续建议
+```
+
+### 🇺🇸 Output Templates
+
+#### TODO.md Template
+```markdown
+# Specification Document Modification Task List
+## Modification Background | ## Associated Feature Points (FP-XXX)
+## Task List: ### [Task ID]-[Task Name](Priority/Associated Document/Modification Content/Status/Notes)
+```
+
+#### Change Completion Report Template
+```markdown
+# Specification Document Change Completion Report
+## Basic Information (Change Topic/Date/Owner/Associated Requirement)
+## Completion Status (Total Tasks/Completed/Completion Rate)
+## Completed Modifications | ## Document Consistency Verification
+## Affected Feature Points (FP-ID/Name/Impact Level/Re-validation Required)
+## Follow-up Recommendations
+```
+
+## 最佳实践 / Best Practices
+
+### 🇨🇳 最佳实践
+
+1. **修改前备份**: 执行修改前创建文档备份
+2. **小步快跑**: 将大修改分解为多个小任务,逐个完成
+3. **及时记录**: 每完成一个修改立即更新CHANGELOG
+4. **交叉验证**: 修改完成后进行文档间的一致性检查
+5. **相关方确认**: 重要修改需经相关方确认后再提交
+
+### 🇺🇸 Best Practices
+
+1. **Backup Before Modification**: Create document backup before executing modifications
+2. **Small Steps Fast**: Break down large modifications into smaller tasks, complete one by one
+3. **Timely Recording**: Update CHANGELOG immediately after each modification is completed
+4. **Cross-validation**: Perform inter-document consistency checks after modifications are complete
+5. **Stakeholder Confirmation**: Important modifications require stakeholder confirmation before submission
+
+## 注意事项 / Notes
+
+### 🇨🇳 注意事项
+
+保持文档风格一致 | 避免过度修改(只改必要内容) | 术语一致性 | 链接有效性 | 版本兼容性考虑
+
+### 🇺🇸 Notes
+
+Maintain consistent document style | Avoid over-modification (only modify necessary content) | Terminology consistency | Link validity | Version compatibility considerations
+
+## Guardrails / Guardrails
+
+### 🇨🇳 Guardrails
+
+- 修改规格文档必须同步更新CHANGELOG
+- 修改后必须通知相关功能点进行重新验证
+- 必须保持文档间的一致性
+- 必须记录变更影响范围
+
+### 🇺🇸 Guardrails
+
+- Modifying specification documents requires synchronous CHANGELOG update
+- After modification, must notify related feature points for re-validation
+- Must maintain inter-document consistency
+- Must record change impact scope
+
+---
+
+## Iron Law / 铁律
+
+### 🇨🇳 Iron Law (中文)
+
+1. **变更必须有据**: 每次文档修改都必须关联到明确的需求变更ID或沟通记录,不得基于模糊的"感觉需要改"而修改规格。
+
+2. **影响分析前置**: 执行任何修改前必须先完成影响分析(哪些功能点、哪些文档会受影响),不得直接修改后再看影响范围。
+
+3. **变更可追溯**: 所有修改操作必须记录到CHANGELOG.md中,包含修改前后对比、修改原因、关联的需求变更ID。
+
+4. **一致性强制校验**: 修改完成后必须执行文档间一致性检查(接口定义、数据模型、业务规则在不同文档间是否一致),不一致的变更不得标记为完成。
+
+5. **通知下游不可省略**: 规格文档变更后必须通知相关功能点进行重新验证,不得静默更新规格而期望下游自动感知。
+
+**违规示例**: ❌ 直接修改spec.md而不记录到CHANGELOG | ❌ 修改接口字段后未检查前端API调用是否同步更新 | ❌ 变更影响范围未评估就执行了修改 | ❌ 修改了规格但未通知相关的功能点重新验证 | ❌ CHANGELOG中只写"修改了接口"而没有具体说明改了什么
+
+**合规示例**: ✅ 每个修改任务都关联需求变更REQ-CHANGE-20260322-001 | ✅ 修改前生成影响分析报告:涉及FP-001和FP-002 | ✅ CHANGELOG详细记录:"v1.1-2026-03-22:新增evaluationMethod字段(String),源自需求变更REQ-xxx" | ✅ 修改后自动检查spec.md与checklist.md的一致性 | ✅ 变更完成后输出通知清单:需要FP-001和FP-002重新执行验证
+
+### 🇺🇸 Iron Law (English)
+
+1. **Changes Must Be Grounded**: Every document modification must be linked to a clear requirement change ID or communication record; never modify specifications based on vague "feeling it needs change."
+
+2. **Impact Analysis First**: Before executing any modification, complete impact analysis first (which feature points, which documents will be affected); never modify first and check impact scope later.
+
+3. **Changes Must Be Traceable**: All modification operations must be recorded in CHANGELOG.md, including before/after comparison, modification reason, and associated requirement change ID.
+
+4. **Mandatory Consistency Verification**: After modifications are complete, must execute inter-document consistency checks (whether interface definitions, data models, and business rules are consistent across documents); inconsistent changes cannot be marked as complete.
+
+5. **Downstream Notification Cannot Be Omitted**: After specification document changes, must notify related feature points for re-validation; never silently update specifications expecting downstream to automatically detect changes.
+
+**Violation Examples**: ❌ Directly modifying spec.md without recording in CHANGELOG | ❌ Modified interface fields without checking if frontend API calls were synchronized | ❌ Executed modifications without evaluating change impact scope | ❌ Modified specifications but did not notify related feature points for re-validation | ❌ CHANGELOG only says "modified interface" without specifying what was changed
+
+**Compliance Examples**: ✅ Every modification task is linked to requirement change REQ-CHANGE-20260322-001 | ✅ Generated impact analysis report before modification: involves FP-001 and FP-002 | ✅ CHANGELOG detailed record: "v1.1-2026-03-22: Added evaluationMethod field (String), sourced from requirement change REQ-xxx" | ✅ Automatically checked consistency between spec.md and checklist.md after modification | ✅ Output notification list after change completion: FP-001 and FP-002 need to re-execute verification
+
+---
+
+## Rationalization Table / 理性化对照表
+
+### 🇨🇳 Rationalization Table (中文)
+
+| 你可能的想法 | 请问自己 | 应该怎么做 |
+|-------------|---------|-----------|
+| "这个改动很小,不用走正式流程吧" | 小改动也可能引发连锁反应,且缺乏追踪会导致后续排查困难 | 所有规格文档变更都必须走完整流程:分析→计划→TODO→执行→记录→校验 |
+| "CHANGELOG后面再补" | 延迟记录会导致遗漏或记忆偏差,失去追溯价值 | 边修改边记录,每完成一个TODO项就更新一次CHANGELOG |
+| "这个文档改了,那个应该差不多吧" | 文档间的不一致是PDD流程中最常见的缺陷来源 | 修改后强制执行交叉引用检查,确保所有相关文档同步更新 |
+| "通知验证太麻烦了,他们应该能看到" | 下游技能不会主动监控上游文档变化,必须显式通知 | 变更完成后生成通知清单,明确列出需要重新验证的功能点 |
+| "原来的内容反正不对,直接覆盖吧" | 覆盖式修改会丢失历史信息,无法回溯和审计 | 保留修改历史,在CHANGELOG中记录修改前后的关键差异 |
+
+**常见陷阱**:
+1. **"随意变更"陷阱**: 缺乏正式变更请求就直接修改规格 → 强制要求变更必须有明确的变更源(需求变更单/沟通记录/问题报告)
+2. **"孤岛修改"陷阱**: 只修改了一个文档而未同步更新关联文档 → 建立"文档依赖图",修改时自动识别所有受影响的文档
+3. **"记录缺失"陷阱**: 执行了修改但没有完整的变更记录 → 将CHANGELOG更新作为TODO完成的必要条件
+4. **"静默变更"陷阱**: 更新了规格但未通知下游重新验证 → 变更完成报告必须包含"下游通知清单"作为必填项
+
+### 🇺🇸 Rationalization Table (English)
+
+| # | Trap / 陷阱 | Question / 请问自己 | Action / 应该怎么做 |
+|---|-------------|-------------------|-------------------|
+| 1 | "This change is small, no need for formal process" / "这个改动很小,不用走正式流程吧" | Small changes can also trigger chain reactions, and lack of tracking makes future troubleshooting difficult | All specification document changes must follow the complete process: Analyze → Plan → TODO → Execute → Record → Verify |
+| 2 | "I'll update CHANGELOG later" / "CHANGELOG后面再补" | Delayed recording leads to omissions or memory bias, losing traceability value | Record while modifying; update CHANGELOG after each TODO item is completed |
+| 3 | "This doc changed, that one should be fine" / "这个文档改了,那个应该差不多吧" | Inter-document inconsistency is the most common defect source in PDD process | Enforce cross-reference checks after modification to ensure all related documents are synchronized |
+| 4 | "Notification is too troublesome, they should see it" / "通知验证太麻烦了,他们应该能看到" | Downstream skills don't proactively monitor upstream document changes; explicit notification is required | Generate notification list after change completion, clearly listing feature points needing re-validation |
+| 5 | "The original content was wrong anyway, just overwrite" / "原来的内容反正不对,直接覆盖吧" | Overwrite modifications lose historical information, making rollback and auditing impossible | Preserve modification history and record key differences before/after in CHANGELOG |
+
+**Common Traps**:
+1. **"Arbitrary Change" Trap / "随意变更"陷阱**: Modifying specifications without formal change request → Require changes to have clear change source (change request form/communication record/issue report)
+2. **"Isolated Modification" Trap / "孤岛修改"陷阱**: Only modified one document without synchronizing related documents → Build "document dependency map" to automatically identify all affected documents during modification
+3. **"Missing Records" Trap / "记录缺失"陷阱**: Executed modifications without complete change records → Make CHANGELOG update a mandatory condition for TODO completion
+4. **"Silent Change" Trap / "静默变更"陷阱**: Updated specifications without notifying downstream for re-validation → Change completion report must include "downstream notification list" as a required field
+
+---
+
+## Red Flags / 红旗警告
+
+### 🇨🇳 Red Flags (中文)
+
+#### Layer 1: 输入检查
+- **INPUT-DC-001**: 变更需求描述为空或过于模糊(如"优化一下接口") → 🔴 CRITICAL → 终止并要求提供具体的变更描述
+- **INPUT-DC-002**: 目标规格文档不存在或路径不正确 → 🔴 CRITICAL → 终止并提示检查文档路径
+- **INPUT-DC-003**: 缺少变更依据(无需求变更ID、无问题报告编号) → 🟡 WARN → 记录为"临时变更"并在报告中标注缺少正式变更依据
+
+#### Layer 2: 执行检查
+- **EXEC-DC-001**: 未完成影响分析就开始执行修改 → 🔴 CRITICAL → 暂停执行,先完成影响范围评估
+- **EXEC-DC-002**: 修改了文档但未同步更新CHANGELOG → 🟡 WARN → 立即补充变更记录
+- **EXEC-DC-003**: 发现文档间不一致(spec.md改了字段但checklist.md未更新) → 🔴 CRITICAL → 暂停修改,先制定完整的同步修改计划
+- **EXEC-DC-004**: TODO列表中有未完成任务但标记变更为完成 → 🔴 CRITICAL → 修正状态为进行中或部分完成
+
+#### Layer 3: 输出检查
+- **OUTPUT-DC-001**: 变更完成报告缺少影响的功能点列表 → 🔴 CRITICAL → 补充受影响的功能点及建议的处理方式
+- **OUTPUT-DC-002**: CHANGELOG与实际修改内容不一致 → 🔴 CRITICAL → 核对并修正CHANGELOG
+- **OUTPUT-DC-003**: 缺少文档一致性校验结果 → 🟡 WARN → 补充一致性检查结果或说明未检查的原因
+
+#### 触发Red Flag时的处理流程
+🔴 CRITICAL → 立即停止,报告问题详情,等待指示 | 🟡 WARN → 记录警告到变更日志,尝试自动修复,在最终报告中标注 | 🔵 INFO → 记录信息,正常继续
+
+### 🇺🇸 Red Flags (English)
+
+#### Layer 1: Input Validation Guards / 输入检查防护
+- **INPUT-DC-001**: Change requirement description is empty or too vague (e.g., "optimize the interface") → 🔴 CRITICAL → Terminate and request specific change description / 终止并要求提供具体的变更描述
+- **INPUT-DC-002**: Target specification document does not exist or path is incorrect → 🔴 CRITICAL → Terminate and prompt to check document path / 终止并提示检查文档路径
+- **INPUT-DC-003**: Missing change basis (no requirement change ID, no issue report number) → 🟡 WARN → Record as "temporary change" and note in report that formal change basis is missing / 记录为"临时变更"并在报告中标注缺少正式变更依据
+
+#### Layer 2: Execution Validation Guards / 执行检查防护
+- **EXEC-DC-001**: Started modifications without completing impact analysis → 🔴 CRITICAL → Pause execution, complete impact scope assessment first / 暂停执行,先完成影响范围评估
+- **EXEC-DC-002**: Modified document but did not synchronously update CHANGELOG → 🟡 WARN → Immediately supplement change records / 立即补充变更记录
+- **EXEC-DC-003**: Discovered inter-document inconsistency (spec.md field changed but checklist.md not updated) → 🔴 CRITICAL → Pause modification, formulate complete synchronization plan first / 暂停修改,先制定完整的同步修改计划
+- **EXEC-DC-004**: TODO list has incomplete tasks but marked as complete → 🔴 CRITICAL → Correct status to in-progress or partially complete / 修正状态为进行中或部分完成
+
+#### Layer 3: Output Validation Guards / 输出检查防护
+- **OUTPUT-DC-001**: Change completion report missing list of affected feature points → 🔴 CRITICAL → Supplement affected feature points and recommended handling methods / 补充受影响的功能点及建议的处理方式
+- **OUTPUT-DC-002**: CHANGELOG inconsistent with actual modification content → 🔴 CRITICAL → Verify and correct CHANGELOG / 核对并修正CHANGELOG
+- **OUTPUT-DC-003**: Missing document consistency verification results → 🟡 WARN → Supplement consistency check results or explain why checks were not performed / 补充一致性检查结果或说明未检查的原因
+
+#### Red Flag Trigger Handling / 触发Red Flag时的处理流程
+🔴 CRITICAL → Stop immediately, report problem details, await instructions / 立即停止,报告问题详情,等待指示 | 🟡 WARN → Record warning in change log, attempt auto-fix, annotate in final report / 记录警告到变更日志,尝试自动修复,在最终报告中标注 | 🔵 INFO → Record information, continue normally / 记录信息,正常继续

package/skills/core/pdd-doc-change/_meta.json

@@ -0,0 +1 @@
+{"name": "pdd-doc-change", "version": "1.0.0", "category": "core", "description": "Manage specification document changes within the PDD workflow, tracking modifications and maintaining consistency. Invoke when requirements change, specs need updating, tracking document modifications, or handling change requests. 支持中文触发：文档变更、规格修改、需求变更、变更管理、文档修改。", "triggers": ["文档变更", "规格修改", "需求变更", "变更管理", "文档修改", "doc change", "spec update", "requirement change", "change management", "update spec"]}

package/skills/core/pdd-doc-change/evals/default-evals.json

@@ -0,0 +1 @@
+[{"name": "SKILL.md-exists", "description": "技能文件存在且格式正确", "type": "structure", "expect": {"exists": true, "hasDescription": true}, "checks": {"file_exists": "SKILL.md"}}, {"name": "_meta.json-valid", "description": "元数据文件格式正确", "type": "structure", "expect": {"exists": true, "hasName": true, "hasVersion": true, "hasTriggers": true}, "checks": {"file_exists": "_meta.json"}}, {"name": "has-behavior-shaping", "description": "包含完整的行为塑造章节", "type": "quality", "expect": {"complete": true}, "contains": ["Iron Law", "Rationalization", "Red Flags"]}, {"name": "change-workflow-defined", "description": "定义了文档变更工作流(请求/审批/执行)", "type": "content", "contains": ["变更", "工作流", "请求", "审批", "跟踪"]}, {"name": "version-tracking-defined", "description": "定义了版本追踪和变更记录机制", "type": "content", "contains": ["版本", "追踪", "记录", "history", "changelog"]}]

package/skills/core/pdd-doc-gardener/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: pdd-doc-gardener
+description: 文档园丁技能，定期扫描识别过时或废弃文档，保持知识库新鲜度。当用户需要文档一致性检查、文档更新或清理时自动触发。支持中文触发：文档清理、文档一致性、更新文档。
+license: MIT
+compatibility: 需要文档目录 (docs/)
+metadata:
+  author: "neuqik@hotmail.com"
+  version: "1.0"
+  parent: pdd-entropy-reduction
+---
+
+# 文档园丁 / Document Gardener (pdd-doc-gardener)
+
+## 核心理念 / Core Philosophy
+
+### 🇨🇳 中文
+
+> "文档即代码，保持同步。文档过时即视为技术债务。" —— PDD 黄金原则
+
+定期扫描代码仓库中的 `docs/` 目录,识别不再反映真实代码行为的过时或废弃文档。
+
+### 🇺🇸 English
+
+> "Documentation is code — keep it in sync. Outdated documentation is technical debt." —— PDD Golden Principle
+
+Periodically scan the `docs/` directory in the code repository to identify outdated or deprecated documents that no longer reflect actual code behavior.
+
+## 检测项 / Detection Items
+
+### 🇨🇳 中文
+
+### 1. 代码与文档不一致
+解析文档中的代码引用(文件路径/函数名/API端点) → 检查代码是否存在及行为是否一致
+
+**示例**: 文档描述"API /api/users返回用户列表" | 实际代码返回用户详情(含订单) → 检测结果:文档过时
+
+### 2. 注释过时
+扫描TODO/FIXME/HACK注释 → 检查存在时间 → 标记超过N天的注释为过时
+
+**示例**: 代码注释"// TODO: implement this later"(30天前创建) → 检测结果:注释过时
+
+### 3. 文档引用的代码已删除
+解析文档中的文件路径引用 → 检查文件是否存在 → 标记引用已删除文件的文档
+
+**示例**: 文档引用"参见src/utils/helper.js" | 实际状态:文件已删除 → 检测结果:引用失效
+
+### 4. API文档与实现不匹配
+解析API文档端点定义 → 扫描代码实际实现 → 对比参数/返回值/错误码
+
+**示例**: API文档:"POST /api/users,参数{name,email}" | 实际代码:"{name,email,phone}" → 检测结果:文档缺失phone参数
+
+### 🇺🇸 English
+
+### 1. Code-Documentation Inconsistency
+Parse code references in documentation (file paths / function names / API endpoints) → Check whether code exists and behavior is consistent
+
+**Example**: Document states "API /api/users returns user list" | Actual code returns user details (including orders) → Result: Documentation outdated
+
+### 2. Outdated Comments
+Scan TODO/FIXME/HACK comments → Check creation time → Mark comments older than N days as stale
+
+**Example**: Code comment "// TODO: implement this later" (created 30 days ago) → Result: Comment outdated
+
+### 3. Referenced Code Deleted
+Parse file path references in documentation → Check if files exist → Flag documents referencing deleted files
+
+**Example**: Document references "see src/utils/helper.js" | Actual status: File deleted → Result: Broken reference
+
+### 4. API Documentation Mismatch
+Parse API endpoint definitions in docs → Scan actual code implementation → Compare parameters / return values / error codes
+
+**Example**: API doc: "POST /api/users, params {name,email}" | Actual code: "{name,email,phone}" → Result: Doc missing phone parameter
+
+## 执行流程 / Execution Workflow
+
+### 🇨🇳 中文
+
+扫描(文档目录/代码注释/API文档) → 对比(代码引用/API定义/行为描述) → 分类(问题类型/严重程度/优先级) → 执行(更新文档/创建PR/删除废弃)
+
+### 🇺🇸 English
+
+Scan (documentation directory / code comments / API docs) → Compare (code references / API definitions / behavior descriptions) → Classify (issue type / severity / priority) → Execute (update documentation / create PR / delete deprecated)
+
+## 输出格式 / Output Format
+
+### 🇨🇳 中文
+
+### 文档园丁报告
+
+```markdown
+# 文档园丁报告 - YYYY-MM-DD
+## 扫描范围: docs/(XX文件) / src/
+## 发现问题
+### Critical(必须修复): 文件 | 问题 | 建议
+### Warning(建议修复): 文件 | 问题 | 建议
+### Info(可选修复): 文件 | 问题 | 建议
+## 执行结果: 更新X项 | 创建PR X项 | 跳过X项
+```
+
+### 🇺🇸 English
+
+### Document Gardener Report
+
+```markdown
+# Document Gardener Report - YYYY-MM-DD
+## Scan Scope: docs/(XX files) / src/
+## Issues Found
+### Critical(Must Fix): File | Issue | Suggestion
+### Warning(Should Fix): File | Issue | Suggestion
+### Info(Optional Fix): File | Issue | Suggestion
+## Execution Results: Updated X items | Created PR X items | Skipped X items
+```
+
+## 配置选项 / Configuration Options (`doc-gardener-config.yaml`)
+
+### 🇨🇳 中文
+
+```yaml
+doc_gardener:
+  scan:
+    docs_paths: ["docs/", "*.md"]
+    code_paths: ["src/"]
+    exclude: ["node_modules/", "dist/"]
+  staleness:
+    todo_max_age_days: 30
+    doc_max_age_days: 90
+  execution:
+    auto_update: true
+    create_pr: true
+    max_pr_per_run: 3
+```
+
+### 🇺🇸 English
+
+```yaml
+doc_gardener:
+  scan:
+    docs_paths: ["docs/", "*.md"]
+    code_paths: ["src/"]
+    exclude: ["node_modules/", "dist/"]
+  staleness:
+    todo_max_age_days: 30
+    doc_max_age_days: 90
+  execution:
+    auto_update: true
+    create_pr: true
+    max_pr_per_run: 3
+```
+
+## 与其他技能协作 / Integration with Other Skills
+
+### 🇨🇳 中文
+
+- **pdd-entropy-reduction**: 作为子技能被协调调用
+- **pdd-doc-change**: 调用此技能创建文档变更PR
+- **expert-entropy-auditor**: 接收审计结果,执行文档修复
+
+### 🇺🇸 English
+
+- **pdd-entropy-reduction**: Invoked as a sub-skill by the coordinator
+- **pdd-doc-change**: Called to create documentation change PRs
+- **expert-entropy-auditor**: Receives audit results, executes documentation fixes
+
+---
+
+## Iron Law / 铁律
+
+### 🇨🇳 中文
+
+1. **证据先行**: 标记文档为"过时"前必须有明确证据(代码已删除/API已变更/行为已修改),不得基于猜测判定。
+
+2. **最小化干预**: 文档修复采用最小改动原则,只更新确实过时的部分,不得借机重写整个文档。
+
+3. **分类处置**: 按Critical/Warning/Info三级分类,Critical立即修复,Warning创建任务,Info记录观察。
+
+4. **不删除仅标记**: 废弃文档应标记"Deprecated"而非直接删除,删除需用户确认。
+
+5. **闭环追踪**: 每个问题都必须有明确状态(已修复/待修复/已忽略)和处置记录。
+
+**违规示例**: ❌ 因为"看起来很久没更新"就标记过时 | ❌ 发现一个过时就重写整个文档 | ❌ 全部标为Critical | ❌ 直接删除引用已删除文件的段落 | ❌ 生成问题清单但不跟踪
+
+**合规示例**: ✅ 标记过时时附证据:"引用的src/utils/helper.js在commit abc123中被删除" | ✅ 只更新过时参数,保留其余部分 | ✅ Critical=影响功能运行,Warning=误导理解,Info=形式问题 | ✅ 先归档到deprecated/目录 | ✅ 报告每个问题都有状态列
+
+### 🇺🇸 English
+
+1. **Evidence First**: Before marking a document as "outdated", there must be clear evidence (code deleted / API changed / behavior modified). Never mark based on speculation.
+
+2. **Minimal Intervention**: Document fixes follow the principle of minimal changes — only update truly outdated parts. Do not use this as an opportunity to rewrite the entire document.
+
+3. **Classified Disposition**: Classify into three levels: Critical / Warning / Info. Critical = fix immediately, Warning = create task, Info = record and observe.
+
+4. **Mark, Don't Delete**: Deprecated documents should be marked "Deprecated" rather than directly deleted. Deletion requires user confirmation.
+
+5. **Closed-Loop Tracking**: Every issue must have a clear status (fixed / pending / ignored) and disposition record.
+
+**Violation Examples**: ❌ Mark as outdated because "looks like it hasn't been updated in a while" | ❌ Rewrite entire document upon finding one outdated item | ❌ Mark everything as Critical | ❌ Directly delete paragraphs referencing deleted files | ❌ Generate issue list without tracking
+
+**Compliant Examples**: ✅ When marking outdated, attach evidence: "Referenced src/utils/helper.js was deleted in commit abc123" | ✅ Only update outdated parameters, preserve the rest | ✅ Critical = affects functionality, Warning = misleading understanding, Info = formatting issue | ✅ Archive to deprecated/ directory first | ✅ Report includes status column for every issue
+
+---
+
+## Rationalization Table / 理性化对照表
+
+| # | Trap / 陷阱 | Question | Action |
+|---|-------------|----------|--------|
+| 1 | "这个文档肯定过时了,直接标吧" / "This doc is definitely outdated, just mark it" | 无证据判断可能错误,误标浪费时间 / Uninformed judgment may be wrong, wasting time on false positives | 必须找到具体的代码/文档不一致证据 / Must find specific code/documentation inconsistency evidence |
+| 2 | "趁机会把文档重写了吧" / "Let's rewrite the doc while we're at it" | 重写会引入新错误且超出职责 / Rewriting introduces new errors and exceeds scope | 只做必要修正,大规模重构单独建议 / Only make necessary fixes; suggest large refactoring separately |
+| 3 | "都是小问题,统一标Warning吧" / "These are all minor, just mark them Warning" | 失去分级导致严重问题得不到及时处理 / Losing severity levels causes serious issues to go unaddressed | 严格按影响程度分级 / Classify strictly by impact severity |
+| 4 | "旧文档占空间,删掉算了" / "Old docs waste space, just delete them" | 删除不可逆,可能丢失有价值信息 / Deletion is irreversible, may lose valuable information | 先归档deprecated/,保留期(如90天)后再确认 / Archive to deprecated/ first, confirm after retention period (e.g., 90 days) |
+| 5 | "报告生成了工作就完成了" / "Report generated, job done" | 发现问题不跟踪等于没做 / Finding issues without tracking is as good as doing nothing | 报告必须含处置建议和跟踪机制 / Report must include disposition suggestions and tracking mechanism |
+
+**常见陷阱 / Common Traps**:
+
+1. **"过度标记"陷阱 / "Over-marking" Trap**: 大量非关键问题标记过时,制造"狼来了"效应 → 严格证据标准:每个标记必须附具体证据 / Mass non-critical issues marked outdated creates "cry wolf" effect → Strict evidence standard: every mark must attach specific evidence
+
+2. **"大修诱惑"陷阱 / "Major Overhaul" Trap**: 借清理之名行重构之实 → 单次修改比例上限(如不超过20%) / Using cleanup as excuse for refactoring → Single-change modification cap (e.g., max 20%)
+
+3. **"分级扁平"陷阱 / "Flat Classification" Trap**: 所有问题同一级别 → 量化标准:Critical=影响功能,Warning=误导理解,Info=形式 / All issues same level → Quantified standard: Critical=affects function, Warning=misleading understanding, Info=formatting
+
+4. **"删除冲动"陷阱 / "Deletion Impulse" Trap**: 倾向删除而非归档 → 强制流程:删除前必须移至deprecated并保留一周期 / Tendency to delete rather than archive → Mandatory process: must move to deprecated before deletion with retention period
+
+---
+
+## Red Flags / 红旗警告
+
+### Layer 1: 输入检查 / Input Validation Guards
+- **INPUT-DG-001**: docs/目录不存在或为空 → 🔴 CRITICAL → 终止并提示目录不存在 / Terminate and report directory does not exist
+- **INPUT-DG-002**: src/目录不存在无法交叉验证 → 🟡 WARN → 降级为仅检查文档内部一致性 / Degrade to internal documentation consistency check only
+- **INPUT-DG-003**: doc-gardener-config.yaml缺失 → 🔵 INFO → 使用默认配置 / Use default configuration
+
+### Layer 2: 执行检查 / Execution Validation Guards
+- **EXEC-DG-001**: 标记过时但未提供具体证据 → 🔴 CRITICAL → 补充证据或移除标记 / Provide evidence or remove the mark
+- **EXEC-DG-002**: 单次修改超过文档内容的30% → 🟡 WARN → 警告可能属重构范畴,建议拆分 / Warning: may be refactoring scope, suggest splitting
+- **EXEC-DG-003**: 直接删除文档而非先归档 → 🔴 CRITICAL → 先移至deprecated/并添加Deprecated标记 / Move to deprecated/ first and add Deprecated marker
+- **EXEC-DG-004**: Critical问题未生成修复建议 → 🟡 WARN → 为每个Critical补充人工修复指导 / Add manual fix guidance for each Critical issue
+
+### Layer 3: 输出检查 / Output Validation Guards
+- **OUTPUT-DG-001**: 报告缺少分级统计(Critical/Warning/Info数量) → 🔴 CRITICAL → 补充分级汇总 / Add severity classification summary
+- **OUTPUT-DG-002**: 报告缺少处置建议或后续计划 → 🟡 WARN → 补充建议处理方式 / Add suggested disposition actions
+- **OUTPUT-DG-003**: 执行结果与问题清单不匹配 → 🔴 CRITICAL → 说明未处理原因和状态 / Explain reasons and status for unaddressed items
+
+### 触发Red Flag时的处理流程 / Trigger Handling Workflow
+
+🔴 **CRITICAL** → 立即停止,报告问题详情,等待指示 / Stop immediately, report problem details, await instructions
+
+🟡 **WARN** → 记录警告,尝试自动修复,在报告中标注 / Log warning, attempt auto-fix, annotate in report
+
+🔵 **INFO** → 记录信息,正常继续 / Log information, continue normally

package/skills/core/pdd-doc-gardener/_meta.json

@@ -0,0 +1 @@
+{"name": "pdd-doc-gardener", "version": "1.0.0", "category": "core", "description": "Periodically scan and clean up outdated documentation to keep the knowledge base fresh and consistent with code. Call this Skill when docs become stale, need consistency checks, require pruning, or detecting orphaned documents. 支持中文触发：文档清理、文档一致性、更新文档、文档整理、过时文档。", "triggers": ["文档清理", "文档一致性", "更新文档", "文档整理", "过时文档", "doc cleanup", "doc gardener", "stale docs", "documentation hygiene", "prune docs"]}

package/skills/core/pdd-doc-gardener/evals/default-evals.json

@@ -0,0 +1 @@
+[{"name": "SKILL.md-exists", "description": "技能文件存在且格式正确", "type": "structure", "expect": {"exists": true, "hasDescription": true}, "checks": {"file_exists": "SKILL.md"}}, {"name": "_meta.json-valid", "description": "元数据文件格式正确", "type": "structure", "expect": {"exists": true, "hasName": true, "hasVersion": true, "hasTriggers": true}, "checks": {"file_exists": "_meta.json"}}, {"name": "has-behavior-shaping", "description": "包含完整的行为塑造章节", "type": "quality", "expect": {"complete": true}, "contains": ["Iron Law", "Rationalization", "Red Flags"]}, {"name": "scan-rules-defined", "description": "定义了文档扫描规则(过时/废弃/孤立)", "type": "content", "contains": ["扫描", "过时", "废弃", "孤立", "一致"]}, {"name": "cleanup-actions-defined", "description": "定义了文档清理操作类型", "type": "content", "contains": ["清理", "更新", "归档", "删除", "action"]}]