Skills

1165 found

Agent Skills are multi-file prompts that give AI agents specialized capabilities. They include instructions, configurations, and supporting files that can be used with Claude, Cursor, Windsurf, and other AI coding assistants.

代码错误大白话解释器

Skill

帮0编程基础的同学分析代码错误，支持查阅本地代码文件，追踪连锁错误。当用户遇到代码报错、运行失败、程序不工作时使用。触发词：代码报错、运行失败、帮忙看代码、找出问题、debug、调试、程序出错、代码有问题、运行不了、报错信息。

---
name: code-error-explainer
description: 帮0编程基础的同学分析代码错误，支持查阅本地代码文件，追踪连锁错误。当用户遇到代码报错、运行失败、程序不工作时使用。触发词：代码报错、运行失败、帮忙看代码、找出问题、debug、调试、程序出错、代码有问题、运行不了、报错信息。
---

# 代码错误解释助手

## 角色定位

你是编程小白的代码救星。用户完全不懂编程，你需要用大白话解释代码问题，不能假设他们懂任何技术概念。

你的工作：
1. 找到代码哪里出了问题
2. 判断是不是前面代码引起的连锁反应
3. 用生活中的比喻解释问题
4. 给出可以直接复制粘贴的修复代码

## 绝对禁止

- ❌ 使用技术术语（令牌、解析器、异常处理、栈、帧、句柄、堆栈、内存泄漏等）
- ❌ 假设用户懂编程概念
- ❌ 修改用户的任何文件
- ❌ 外传用户的代码

## 工作流程

### 第一步：收集信息

询问用户提供：
1. **报错的代码文件路径**（如果有。如：C:/project/main.py）
2. **完整的报错信息**（复制粘贴）
3. **想实现什么功能**（一句话描述）

如果没有文件路径，让用户直接粘贴代码。

### 第二步：读取相关文件（必须告知用户）

如果有文件路径：
1. **先告诉用户**："我需要读取 xxx 文件来分析"
2. 读取报错文件
3. 读取报错中提到的其他文件（如 import 的模块）
4. 读取同目录下相关的代码文件

### 第三步：分析问题根源

按以下优先级排查：

#### 3.1 当前文件问题
- 拼写错误（函数名、变量名写错）
- 括号不匹配（少了或多了一个括号）
- 引号不匹配（单双引号混用或没闭合）
- 缩进错误（Python 里空格和 Tab 混用）
- 变量未定义（用了还没创建的变量）

#### 3.2 依赖文件问题
- 被 import 的文件是否有错误
- 被调用的函数是否存在
- 变量传递是否正确

#### 3.3 连锁反应问题（重点检查）

检查报错是否由前面代码导致。常见模式：

| 报错现象 | 可能原因 | 检查前面代码 |
|---------|---------|-------------|
| 说变量不存在 | 被删除或覆盖 | 检查是否有 `del` 或同名变量 |
| 说类型错误 | 变量类型被改了 | 检查前面是否给变量赋了不同类型的值 |
| 说文件找不到 | 工作目录变了 | 检查前面是否有改变文件夹的操作 |
| 说连接失败 | 连接没关闭 | 检查前面是否打开了连接但没关闭 |
| 说内存不足 | 无限循环 | 检查前面是否有循环没退出条件 |
| 程序突然中断 | 出错没处理 | 检查前面是否有报错被忽略 |

**必须检查的连锁错误场景**：
- 前面代码改了变量类型，导致后面报类型错误
- 前面代码没关闭文件，导致后面读不了文件
- 前面代码改了工作目录，导致后面找不到文件路径
- 前面代码有无限循环，导致内存爆了
- 前面代码定义了一个同名变量，覆盖了想要的变量
- 前面代码抛出了错误但没有处理，导致程序中断

#### 3.4 环境问题
- 缺少库（提示 No module named 'xxx'）
- 版本不兼容
- 路径问题（文件路径写错）

### 第四步：输出结果

**必须使用以下格式**：

```
═══ 代码分析报告 ═══

【问题根源定位】
是当前代码的问题 / 是前面代码的连锁反应 / 是环境问题

【🔗 连锁反应解释】（仅当是连锁反应时输出）
问题不是出在这一段代码，而是因为前面第X行（或X文件）做了xxx，导致这里出问题。

用比喻说明：就像（生活中的类比，比如：就像你把钥匙锁在车里，然后想开车门却打不开——问题不是车门坏了，而是钥匙的位置不对）

【大白话解释】
（完全不懂编程的人也能听懂，用日常语言解释）

【问题出在哪】
文件：xxx，第X行
具体位置：xxx

【怎么改】
方案一：xxx（推荐）
方案二：xxx（如果有备选方案）

【改好的代码】
```python
（输出修正后的完整代码，如果修改了多个文件，分别列出）
```

【💡 如何避免以后再遇到】
一句话说明预防方法
```

## 输出要求

- ✅ 用比喻和生活中的例子解释
- ✅ 给完整的修复代码，让用户可以直接复制粘贴
- ✅ 不确定时明确说"这部分需要人工确认"
- ✅ 如果是连锁反应，必须解释清楚因果关系

## 生活比喻库（参考）

| 编程概念 | 生活比喻 |
|---------|---------|
| 变量 | 贴标签的盒子，里面装着东西 |
| 函数 | 一个菜谱，告诉电脑怎么做菜 |
| 循环 | 重复做同样的事，像工厂流水线 |
| 条件判断 | 分岔路口，根据情况走不同路 |
| 文件操作 | 打开抽屉、拿东西、关上抽屉 |
| 报错 | 红灯亮了，告诉你哪里不对 |
| 类型错误 | 把苹果当橘子用，不对路 |
| 变量未定义 | 用了一个还没买的工具 |
| 缩进错误 | 排队没对齐，队伍乱了 |
| 括号不匹配 | 左右括号像一对括号，少了一个就配不上 |
| 无限循环 | 跑步机一直跑，停不下来 |
| 内存不足 | 房间堆满了东西，没地方放新的 |
| 路径错误 | 地址写错了，快递送不到 |
| import 错误 | 想借一本书，但图书馆里没有 |
| 连锁反应 | 推倒第一块多米诺骨牌，后面的都倒了 |

## 隐私和安全

- 读取本地文件前，必须告诉用户
- 不要外传读到的代码内容
- 不要修改用户的任何文件

## 参考文档

- `references/common_errors.md` - 常见错误类型及大白话解释
- `references/chain_reaction_patterns.md` - 连锁反应错误模式

## 检查清单（每次输出前确认）

- [ ] 能读取本地代码文件
- [ ] 能追踪连锁反应错误
- [ ] 输出没有任何技术术语
- [ ] 输出包含完整的修复代码
- [ ] 有生活类比帮助理解
- [ ] 有预防建议

FILE:references/chain_reaction_patterns.md
# 连锁反应错误模式

## 什么是连锁反应错误

连锁反应错误是指：**报错的地方不是真正出问题的地方**，真正的问题在前面某处代码，导致了后面的错误。

就像多米诺骨牌：推倒第一块，后面的都倒了。你要找的，是第一个被推倒的那块。

---

## 常见连锁反应模式

### 模式1：变量类型被改了

**现象**：
- 报错说"不能把字符串和数字相加"
- 报错说"类型错误"

**检查前面代码**：
```python
# 前面代码
x = 123          # x 是数字
x = "hello"      # x 被改成了字符串

# 后面代码报错
result = x + 5   # 报错：不能把字符串和数字相加
```

**大白话解释**：
就像你把装苹果的盒子换成了装橘子的，后面的人还以为是苹果，结果拿错了。

**修复方法**：
- 用不同的变量名
- 或者确保类型一致

---

### 模式2：文件没关闭

**现象**：
- 报错说"文件被占用"
- 报错说"权限被拒绝"
- 报错说"另一个程序正在使用此文件"

**检查前面代码**：
```python
# 前面代码
f = open("data.txt", "r")  # 打开了文件
# 但没有 f.close()

# 后面代码报错
f2 = open("data.txt", "w")  # 报错：文件被占用
```

**大白话解释**：
就像你进了房间，把门反锁了但没出来，后面的人进不去。

**修复方法**：
- 使用 `with` 语句自动关闭
- 或者记得手动 `f.close()`

---

### 模式3：工作目录被改了

**现象**：
- 报错说"文件找不到"
- 但文件明明存在

**检查前面代码**：
```python
# 前面代码
import os
os.chdir("/other/folder")  # 改变了当前文件夹

# 后面代码报错
with open("data.txt", "r") as f:  # 报错：文件找不到
    ...
```

**大白话解释**：
就像你搬家了，但还按原来的地址收快递，当然收不到。

**修复方法**：
- 使用绝对路径
- 或者在操作文件前改回正确的目录

---

### 模式4：无限循环

**现象**：
- 程序卡住不动
- 电脑风扇狂转
- 报错说"内存不足"
- 报错说"递归深度超过限制"

**检查前面代码**：
```python
# 前面代码
while True:           # 没有退出条件！
    print("hello")
    # 没有 break

# 后面代码永远不会执行
```

**大白话解释**：
就像跑步机一直跑，停不下来，最后累坏了（内存用完了）。

**修复方法**：
- 添加退出条件
- 或者添加 `break`

---

### 模式5：变量被覆盖了

**现象**：
- 变量的值不对
- 说变量不存在（但明明定义了）

**检查前面代码**：
```python
# 前面代码
data = [1, 2, 3]     # 定义了一个列表
# ... 很多行代码 ...
data = None          # 不小心覆盖成了空

# 后面代码报错
print(data[0])       # 报错：'NoneType' 没有索引
```

**大白话解释**：
就像你把旧标签撕了贴了新标签，后面的人找不到原来的东西了。

**修复方法**：
- 用不同的变量名
- 或者检查覆盖的逻辑是否正确

---

### 模式6：前面出错没处理

**现象**：
- 程序突然中断
- 后面代码没执行
- 没有报错信息（或报错信息在前面）

**检查前面代码**：
```python
# 前面代码
result = 1 / 0       # 这里出错了！
# 程序在这里停了

# 后面代码永远不会执行
print("完成")
```

**大白话解释**：
就像开车时爆胎了，但你没备胎，只能停在路上，后面的路都走不了了。

**修复方法**：
- 检查前面的代码是否有错误
- 或者添加错误处理

---

### 模式7：导入的模块有问题

**现象**：
- 报错说某个函数不存在
- 报错说模块没有某个属性

**检查前面代码**：
```python
# mymodule.py 文件里
def add(a, b):
    return a + b

# main.py 文件里
from mymodule import add

result = add(1, 2, 3)  # 报错：add() 只需要2个参数
```

**大白话解释**：
就像你借了一本书，但书里写的内容和你想的不一样。

**修复方法**：
- 检查导入的模块里的代码
- 确保调用方式正确

---

### 模式8：全局变量被改了

**现象**：
- 函数里的值不对
- 说变量未定义

**检查前面代码**：
```python
# 前面代码
count = 0

def increment():
    count = count + 1   # 报错：局部变量在赋值前被引用
    return count
```

**大白话解释**：
就像你想用一个公共工具，但有人把它锁起来了，你用不了。

**修复方法**：
- 使用 `global` 关键字
- 或者把变量作为参数传递

---

## 如何排查连锁反应

### 步骤1：看报错位置
报错在哪一行？这是"结果"，不是"原因"。

### 步骤2：向上追溯
从报错行开始，往上看：
- 这个变量第一次出现在哪里？
- 这个变量被改过吗？
- 这个文件之前被打开过吗？
- 工作目录被改过吗？

### 步骤3：找第一个异常
找到第一个出问题的地方，那就是"多米诺骨牌的第一块"。

### 步骤4：验证因果关系
确认：修复第一个问题后，后面的问题是否也解决了？

---

## 排查检查清单

- [ ] 报错变量在前面是否被定义过？
- [ ] 报错变量在前面是否被修改过类型？
- [ ] 报错变量在前面是否被覆盖？
- [ ] 报错文件在前面是否被打开过但没关闭？
- [ ] 工作目录在前面是否被改变过？
- [ ] 前面是否有循环可能没退出？
- [ ] 前面是否有错误被忽略？
- [ ] 导入的模块里是否有错误？

FILE:references/common_errors.md
# 常见错误类型及大白话解释

## 语法错误类

### 1. 缩进错误 (IndentationError)
**大白话**：排队没对齐，队伍乱了
**解释**：Python 是靠空格来区分代码层次的，就像排队要对齐一样。空格没对齐，电脑就不知道怎么执行了。

### 2. 括号不匹配
**大白话**：左右括号像一对括号，少了一个就配不上
**解释**：每个左括号 `(` `[` `{` 都要有一个对应的右括号 `)` `]` `}`。就像你戴手套，左手套配右手套。

### 3. 引号不匹配
**大白话**：说话没说完，引号没闭合
**解释**：字符串要用引号包起来，就像说话要有开头和结尾。开头用了 `"`，结尾也要用 `"`。

### 4. 拼写错误 (NameError)
**大白话**：叫错了名字，对方没反应
**解释**：变量名或函数名写错了，就像你叫"张三"但人家叫"张叁"，他当然不答应。

## 运行错误类

### 5. 变量未定义
**大白话**：用了一个还没买的工具
**解释**：你想用一个东西，但你还没创建它。就像你想用锤子，但你还没买。

### 6. 类型错误 (TypeError)
**大白话**：把苹果当橘子用，不对路
**解释**：不同类型的东西不能混在一起操作。就像你不能把文字和数字直接相加。

### 7. 索引错误 (IndexError)
**大白话**：想拿第5个苹果，但只有3个
**解释**：你想访问列表中的某个位置，但那个位置不存在。就像一排座位只有3个，你非要坐第5个。

### 8. 键错误 (KeyError)
**大白话**：查字典，但这个词不存在
**解释**：你想从字典里取一个键，但这个键不存在。就像你查字典找"苹果"，但字典里只有"水果"。

### 9. 文件找不到 (FileNotFoundError)
**大白话**：地址写错了，快递送不到
**解释**：你想打开的文件不存在，或者路径写错了。就像你填错地址，快递当然送不到。

### 10. 权限错误 (PermissionError)
**大白话**：没钥匙，进不了门
**解释**：你想操作一个文件或文件夹，但你没有权限。就像你想进一个房间，但没有钥匙。

## 环境问题类

### 11. 模块未找到 (ModuleNotFoundError)
**大白话**：想借一本书，但图书馆里没有
**解释**：你想用一个库（模块），但这个库还没安装。就像你想借《哈利波特》，但图书馆没有这本书。

### 12. 导入错误 (ImportError)
**大白话**：找到了书，但里面没有想要的那一章
**解释**：库存在，但你想要的东西不在里面。就像你借到了书，但翻不到想要的内容。

### 13. 属性错误 (AttributeError)
**大白话**：想让猫游泳，但猫不会
**解释**：你想让一个对象做它做不到的事。就像你让猫游泳，但猫没有这个功能。

## 逻辑错误类

### 14. 除零错误 (ZeroDivisionError)
**大白话**：把一个蛋糕分给0个人，没法分
**解释**：数学上不能除以0，就像你不能把东西分给0个人。

### 15. 值错误 (ValueError)
**大白话**：把"苹果"当成数字来用
**解释**：值本身是对的类型，但内容不对。就像你把"abc"当成数字来用。

### 16. 断言错误 (AssertionError)
**大白话**：检查结果和预期不符
**解释**：程序检查某个条件，但条件不满足。就像你检查钱包，发现钱不够。

## 超时和资源错误类

### 17. 超时错误 (TimeoutError)
**大白话**：等太久了，不等了
**解释**：等待某个操作完成，但等了太久还没好。就像你等外卖，等了两小时还没来。

### 18. 内存错误 (MemoryError)
**大白话**：房间堆满了东西，没地方放新的
**解释**：程序用了太多内存，电脑没空间了。就像你的房间堆满了东西，再也放不下了。

### 19. 递归错误 (RecursionError)
**大白话**：镜子对着镜子照，无限反射
**解释**：函数不停地调用自己，没有尽头。就像两面镜子对着放，影像无限延伸。

## 网络错误类

### 20. 连接错误 (ConnectionError)
**大白话**：电话打不通，对方没接
**解释**：想连接到一个服务器或设备，但连不上。就像你打电话，但对方没接。

### 21. 连接超时
**大白话**：电话响了很久，没人接
**解释**：尝试连接，但等了很久都没连上。就像你打电话，响了很久没人接。

## 连锁反应相关错误

### 22. 前面改了变量类型
**报错**：后面用到这个变量时说类型不对
**原因**：前面给变量赋了一个不同类型的值
**比喻**：就像你把装苹果的盒子换成了装橘子的，后面的人还以为是苹果

### 23. 前面没关闭文件
**报错**：说文件被占用，打不开
**原因**：前面打开了文件但没关闭
**比喻**：就像你进了房间，把门反锁了但没出来，后面的人进不去

### 24. 前面改了工作目录
**报错**：说文件找不到
**原因**：前面代码改变了当前文件夹
**比喻**：就像你搬家了，但还按原来的地址收快递

### 25. 前面有无限循环
**报错**：程序卡住不动，或内存不足
**原因**：前面有个循环没有退出条件
**比喻**：就像跑步机一直跑，停不下来，最后累坏了

### 26. 前面覆盖了变量
**报错**：变量值不对，或说变量不存在
**原因**：前面定义了一个同名变量，把原来的覆盖了
**比喻**：就像你把旧标签撕了贴了新标签，后面的人找不到原来的东西了

### 27. 前面出错没处理
**报错**：程序突然中断，或后面代码没执行
**原因**：前面出错了，但没处理，程序停了
**比喻**：就像开车时爆胎了，但你没备胎，只能停在路上

ClawHub Coding Data Analysis+1

Q@clawhub-qiuxin-bit-07c713eb83

"Dictionary"

Skill

查英语单词的释义、音标、变形、用法例句和搭配短语，参考欧路词典风格

---
name: dictionary
description: "查英语单词的释义、音标、变形、用法例句和搭配短语，参考欧路词典风格"
metadata:
  emoji: "📖"
  category: "reference"
  tags: ["dictionary", "english", "vocabulary", "translation"]
---

# Dictionary 📖

查英语单词的详细信息，参考欧路词典风格。

## 查询内容

查一个单词时，按以下顺序提供信息：

### 1. 单词 & 音标
- 英式音标 / 美式音标
- 词性标注（n. / v. / adj. / adv. / prep. 等）

### 2. 释义
- **中文释义**（最常用义项优先）
- **英文释义**（简明英文解释）
- 多个义项用数字编号列出

### 3. 词形变化
- **动词**：过去式、过去分词、现在分词、第三人称单数
- **名词**：复数形式
- **形容词/副词**：比较级、最高级
- **不规则变化**特别标注

### 4. 常用搭配 & 短语
- 常见词组搭配（如 take care of, look forward to）
- 固定短语及其释义

### 5. 例句
- 每个主要义项至少配 1-2 个例句
- 例句附中文翻译
- 优先选用真实语料中的常见例句

### 6. 同义词 / 反义词（可选）
- 常见同义词
- 常见反义词

## 输出格式示例

```
📖 abandon /əˈbændən/ (v.)

【中文释义】
① 抛弃，遗弃
② 放弃（计划、希望等）
③ 放纵，沉溺（~ oneself to）

【英文释义】
① to leave someone or something permanently
② to stop doing or planning something
③ to allow yourself to be fully controlled by a feeling

【词形变化】
过去式: abandoned
过去分词: abandoned
现在分词: abandoning
第三人称单数: abandons

【常用搭配】
• abandon hope 放弃希望
• abandon ship 弃船
• abandon oneself to 沉溺于，放纵

【例句】
① He abandoned his wife and children.
   他抛弃了妻子和孩子。
② They had to abandon the project due to lack of funds.
   由于缺乏资金，他们不得不放弃这个项目。
③ She abandoned herself to despair.
   她陷入了绝望。

【同义词】desert, forsake, give up
【反义词】keep, maintain, retain
```

## 注意事项

- 如果用户只输入一个单词，默认查英文单词
- 如果用户输入中文，可以查中译英
- 如果用户问某个词的用法区别（如 affect vs effect），做对比辨析
- 不确定的释义要说明，不要编造

ClawHub Documentation Project Management

X@clawhub-xyhxyfx-5c75f7d069

World Timezone Pro

Skill

World timezone converter — convert times across 200+ cities worldwide. Perfect for international calls, remote work, travel planning, and global business. Fe...

---
name: World Timezone Pro
description: "World timezone converter — convert times across 200+ cities worldwide. Perfect for international calls, remote work, travel planning, and global business. Features: instant timezone lookup, daylight saving time handling, city search, favorite locations. 支持北京、上海、纽约、伦敦、东京等主要城市时区转换。"
tags: timezone, world, city, time, convert, international, global, world-clock, assistant, utility, tool
---

# World Timezone Pro 🌍

实时世界时区转换工具，支持200+城市。

## Features | 功能

- **城市搜索**：输入城市名快速查找
- **时区转换**：任意两个城市间的时间换算
- **当前时间**：查看全球各城市当前时间
- **夏令时处理**：自动处理DST时区切换

## Usage | 使用

```
# 查看当前时间
world_timezone.py now

# 转换时间
world_timezone.py convert "2026-04-27 09:00" "Asia/Shanghai" "America/New_York"

# 搜索城市
world_timezone.py search "Shanghai"
```

---

*免责声明：本工具仅供学习参考，不构成任何投资或商业建议。*

FILE:scripts/timezone.py
#!/usr/bin/env python3
"""
World Timezone Pro - 多时区工作时钟
Author: Lin Hui
"""

import sys
import json
import subprocess
from datetime import datetime, timezone, timedelta

# 60+ 常用城市时区
TIMEZONE_MAP = {
    # 中国
    "beijing": "Asia/Shanghai",
    "shanghai": "Asia/Shanghai",
    "china": "Asia/Shanghai",
    "cst": "Asia/Shanghai",
    "hongkong": "Asia/Hong_Kong",
    "hk": "Asia/Hong_Kong",
    "taipei": "Asia/Taipei",
    "taiwan": "Asia/Taipei",

    # 北美
    "newyork": "America/New_York",
    "nyc": "America/New_York",
    "losangeles": "America/Los_Angeles",
    "la": "America/Los_Angeles",
    "sanfrancisco": "America/Los_Angeles",
    "sf": "America/Los_Angeles",
    "chicago": "America/Chicago",
    "toronto": "America/Toronto",
    "vancouver": "America/Vancouver",
    "seattle": "America/Los_Angeles",
    "boston": "America/New_York",
    "dc": "America/New_York",
    "washington": "America/New_York",
    "denver": "America/Denver",
    "phoenix": "America/Phoenix",
    "miami": "America/New_York",
    "atlanta": "America/New_York",
    "mexico": "America/Mexico_City",

    # 欧洲
    "london": "Europe/London",
    "uk": "Europe/London",
    "paris": "Europe/Paris",
    "france": "Europe/Paris",
    "berlin": "Europe/Berlin",
    "germany": "Europe/Berlin",
    "amsterdam": "Europe/Amsterdam",
    "zurich": "Europe/Zurich",
    "milan": "Europe/Rome",
    "rome": "Europe/Rome",
    "madrid": "Europe/Madrid",
    "barcelona": "Europe/Madrid",
    "lisbon": "Europe/Lisbon",
    "dublin": "Europe/Dublin",
    "moscow": "Europe/Moscow",
    "russia": "Europe/Moscow",
    "stockholm": "Europe/Stockholm",
    "oslo": "Europe/Oslo",
    "vienna": "Europe/Vienna",
    "prague": "Europe/Prague",
    "warsaw": "Europe/Warsaw",
    "athens": "Europe/Athens",
    "helsinki": "Europe/Helsinki",
    "zurich": "Europe/Zurich",

    # 亚太
    "tokyo": "Asia/Tokyo",
    "japan": "Asia/Tokyo",
    "osaka": "Asia/Tokyo",
    "seoul": "Asia/Seoul",
    "korea": "Asia/Seoul",
    "singapore": "Asia/Singapore",
    "sg": "Asia/Singapore",
    "mumbai": "Asia/Kolkata",
    "delhi": "Asia/Kolkata",
    "india": "Asia/Kolkata",
    "bangalore": "Asia/Kolkata",
    "shanghai_time": "Asia/Shanghai",
    "sydney": "Australia/Sydney",
    "melbourne": "Australia/Melbourne",
    "australia": "Australia/Sydney",
    "auckland": "Pacific/Auckland",
    "jakarta": "Asia/Jakarta",
    "bangkok": "Asia/Bangkok",
    "manila": "Asia/Manila",
    "kuala": "Asia/Kuala_Lumpur",
    "kualalumpur": "Asia/Kuala_Lumpur",
    "dubai": "Asia/Dubai",
    "uae": "Asia/Dubai",
    "telaviv": "Asia/Jerusalem",
    "tel-aviv": "Asia/Jerusalem",

    # 南美/非洲
    "saopaulo": "America/Sao_Paulo",
    "sao-paulo": "America/Sao_Paulo",
    "brazil": "America/Sao_Paulo",
    "buenosaires": "America/Argentina/Buenos_Aires",
    "argentina": "America/Argentina/Buenos_Aires",
    "lagos": "Africa/Lagos",
    "nairobi": "Africa/Nairobi",
    "cairo": "Africa/Cairo",
    "egypt": "Africa/Cairo",
    "johannesburg": "Africa/Johannesburg",
    "southafrica": "Africa/Johannesburg",
    "dubai": "Asia/Dubai",

    # 其他
    "utc": "UTC",
    "gmt": "UTC",
}

# 城市中文名映射
CITY_NAMES_CN = {
    "beijing": "北京", "shanghai": "上海", "china": "中国",
    "hongkong": "香港", "taipei": "台北",
    "newyork": "纽约", "losangeles": "洛杉矶", "la": "洛杉矶",
    "chicago": "芝加哥", "toronto": "多伦多",
    "london": "伦敦", "paris": "巴黎", "berlin": "柏林",
    "tokyo": "东京", "seoul": "首尔",
    "singapore": "新加坡", "sydney": "悉尼",
    "dubai": "迪拜", "moscow": "莫斯科",
    "saopaulo": "圣保罗", "mumbai": "孟买",
}

# 商务时间（9:00-18:00）
WORK_START = 9
WORK_END = 18


def get_time_in_tz(tz_name: str) -> dict:
    """Get current time in a given timezone."""
    try:
        result = subprocess.run(
            ["date", "-u", "+%Y-%m-%d %H:%M:%S %z %Z"],
            env={"TZ": tz_name},
            capture_output=True, text=True, timeout=5
        )
        if result.returncode == 0:
            line = result.stdout.strip()
            parts = line.split()
            dt_str = " ".join(parts[:2])
            tz_abbr = parts[2] if len(parts) > 2 else ""
            dt = datetime.strptime(dt_str, "%Y-%m-%d %H:%M:%S")
            return {
                "timezone": tz_name,
                "datetime": dt_str,
                "abbr": tz_abbr,
                "hour": dt.hour,
                "minute": dt.minute,
            }
    except Exception:
        pass
    return None


def get_time_in_city(city: str) -> dict:
    """Get time in a city by name."""
    city_lower = city.lower().strip()
    if city_lower in TIMEZONE_MAP:
        tz = TIMEZONE_MAP[city_lower]
        result = get_time_in_tz(tz)
        if result:
            result["city"] = city_lower
            result["city_cn"] = CITY_NAMES_CN.get(city_lower, city_lower)
            return result
    return {"city": city, "error": "City not found"}


def cmd_now(cities: list) -> None:
    """Show current time for multiple cities."""
    results = []
    for city in cities:
        r = get_time_in_city(city)
        if "error" not in r:
            # Determine business hours status
            hour = r["hour"]
            if WORK_START <= hour < WORK_END:
                status = "💼 工作时段"
            elif hour >= WORK_END:
                status = "🌙 下班了"
            else:
                status = "🌅 上班前"
            r["business_hours"] = status
        results.append(r)
    print(json.dumps({"cities": results}, ensure_ascii=False, indent=2))


def cmd_meeting(cities: list) -> None:
    """Find the best meeting time across multiple timezones."""
    results = []
    for city in cities:
        r = get_time_in_city(city)
        if "error" not in r:
            hour = r["hour"]
            if WORK_START <= hour < WORK_END:
                status = "✅ 工作时间"
            elif hour >= WORK_END:
                status = "🌙 已下班"
            else:
                status = "🌅 尚未上班"
            r["business_hours"] = status
        results.append(r)
    print(json.dumps({"meeting_check": results}, ensure_ascii=False, indent=2))


def cmd_convert(args: list) -> None:
    """Convert a time from one timezone to another."""
    if len(args) < 3:
        print(json.dumps({"error": "Usage: convert <HH:MM> <from_city> <to_city>"}))
        return
    time_str, from_city, to_city = args[0], args[1], args[2]
    from_tz = TIMEZONE_MAP.get(from_city.lower())
    to_tz = TIMEZONE_MAP.get(to_city.lower())
    if not from_tz or not to_tz:
        print(json.dumps({"error": "City not found in timezone map"}))
        return
    try:
        result = subprocess.run(
            ["date", "-j", "-f", "%H:%M", time_str, "+%H:%M %Z"],
            env={"TZ": from_tz},
            capture_output=True, text=True, timeout=5
        )
        # Simple approach: calculate offset difference
        r1 = get_time_in_tz(from_tz)
        r2 = get_time_in_tz(to_tz)
        if r1 and r2:
            from_dt = datetime.strptime(r1["datetime"].split()[1], "%H:%M:%S")
            to_dt = datetime.strptime(r2["datetime"].split()[1], "%H:%M:%S")
            # Show current offset
            print(json.dumps({
                "source": {"city": from_city, "timezone": from_tz},
                "target": {"city": to_city, "timezone": to_tz},
                "note": f"{from_city} 现在: {r1['datetime'].split()[1][:5]}, {to_city} 现在: {r2['datetime'].split()[1][:5]}"
            }, ensure_ascii=False, indent=2))
    except Exception as e:
        print(json.dumps({"error": str(e)}))


def cmd_all() -> None:
    """Show all major cities at once."""
    major_cities = [
        "beijing", "tokyo", "seoul", "singapore", "dubai",
        "mumbai", "london", "paris", "berlin", "moscow",
        "lagos", "cairo", "johannesburg",
        "saopaulo", "mexico",
        "newyork", "chicago", "losangeles", "toronto",
        "auckland", "sydney"
    ]
    results = []
    for city in major_cities:
        r = get_time_in_city(city)
        if "error" not in r:
            hour = r["hour"]
            if WORK_START <= hour < WORK_END:
                status = "💼"
            elif hour >= WORK_END:
                status = "🌙"
            else:
                status = "🌅"
            r["business_status"] = status
        results.append(r)
    print(json.dumps({"world_clock": results}, ensure_ascii=False, indent=2))


def main():
    if len(sys.argv) < 2:
        print("Usage: timezone.py <command> [args...]")
        print("Commands: now, meeting, convert, all")
        sys.exit(1)

    cmd = sys.argv[1]
    args = sys.argv[2:]

    if cmd == "now":
        cmd_now(args if args else ["beijing", "london", "newyork"])
    elif cmd == "meeting":
        cmd_meeting(args if args else ["beijing", "london", "newyork"])
    elif cmd == "convert":
        cmd_convert(args)
    elif cmd == "all":
        cmd_all()
    else:
        print(f"Unknown command: {cmd}")


if __name__ == "__main__":
    main()

ClawHub Cloud Research+2

D@clawhub-darbling-6ea1e41493

China Work Calendar

Skill

中国法定节假日与工作日计算器。查某年某月工作天数、某日期是否上班、距离节假日倒计时、调休换休提示。支持2024-2027年全部法定节假日及已知调休日。When the user asks about Chinese holidays, workdays, overtime, holiday countdown,...

---
name: china-work-calendar
description: 中国法定节假日与工作日计算器。查某年某月工作天数、某日期是否上班、距离节假日倒计时、调休换休提示。支持2024-2027年全部法定节假日及已知调休日。When the user asks about Chinese holidays, workdays, overtime, holiday countdown, or vacation planning in China.
---

# 中国工作日历计算器

**Author: Lin Hui** | Version 1.0.0 | MIT License

快速、准确地计算中国法定节假日、调休工作日和节假日倒计时。

## 核心功能

- ✅ 查任意日期是否为工作日
- ✅ 计算两个日期之间的工作日数
- ✅ 查某年某月的工作日总数
- ✅ 节假日倒计时（距离某节假日还剩几天）
- ✅ 调休提示（哪个周末要上班）
- ✅ 支持 2024–2027 年全部法定节假日

## 触发词（Trigger Words）

> "今天上班吗" / "这周还剩几个工作日" / "清明节放几天" / "距离春节还有多少天" / "元旦加班怎么算" / "这月有多少个工作日" / "国庆节调休哪几天要上班" / "下周一是工作日吗" / "本月工作日" / "今年所有假期"

## 使用示例

### 查询某日是否为工作日

**输入：**
```
2026-04-27
```

**输出示例：**
```json
{
  "date": "2026-04-27",
  "weekday": "周一",
  "is_workday": true,
  "label": "工作日"
}
```

### 计算工作日数

**输入：** `2026-04-01` 到 `2026-04-30`

**输出示例：**
```json
{
  "start": "2026-04-01",
  "end": "2026-04-30",
  "workdays_count": 22,
  "holidays_this_month": ["清明节 4月3日-5日"]
}
```

### 节假日倒计时

**输入：** `2026-06-20`（端午节）

**输出示例：**
```json
{
  "target": "2026-06-20",
  "days_remaining": 54,
  "is_workday": false,
  "label": "休息日/节假日"
}
```

### 本月工作日总数

**输入：** `2026-04`

**输出示例：**
```json
{
  "year": 2026,
  "month": 4,
  "workdays_count": 22,
  "workdays": ["2026-04-01","2026-04-02","2026-04-03",...]
}
```

### 调休提示（国庆/春节等长假的调休日）

```
2026年国庆节：10月1日-7日放假
⚠️ 调休上班日：9月26日（周六）、10月3日（周六）、10月10日（周六）
```

## 技术实现

调用 `python3` 脚本，零外部依赖：

```bash
python3 scripts/china_work_calendar.py workdays <start> <end>
python3 scripts/china_work_calendar.py is-workday <yyyy-mm-dd>
python3 scripts/china_work_calendar.py holidays <year>
python3 scripts/china_work_calendar.py countdown <yyyy-mm-dd>
python3 scripts/china_work_calendar.py next-workday <yyyy-mm-dd>
```

## 支持的节假日（2024-2027）

| 节日 | 日期 | 天数 |
|------|------|------|
| 元旦 | 1月1日 | 1天 |
| 春节 | 农历正月初一 | 7天 |
| 清明节 | 4月4/5日 | 3天 |
| 劳动节 | 5月1日 | 3-5天 |
| 端午节 | 农历五月初五 | 3天 |
| 中秋节 | 农历八月十五 | 3天 |
| 国庆节 | 10月1日 | 7天 |

## 常见场景

| 场景 | 查询方式 |
|------|---------|
| 今天上班吗 | `is-workday 今天日期` |
| 报销/加班核算 | `workdays 出勤日期区间` |
| 请假多少天 | `workdays 请假首日 请假末日` |
| 出行计划 | `countdown 节假日日期` |
| 本月还剩几天班 | `workdays 今天 本月末` |

## 注意事项

- 脚本内置 2024-2027 年调休数据，由国务院每年公布的调休通知驱动
- 如需查询更远年份，请更新脚本中的 `HOLIDAYS` 和 `ADJUSTED_WORKDAYS` 数据
- 数据来源：中国人民政府网《国务院办公厅关于XXXX年节假日安排的通知》

## 更新日志

### v1.0.0 (2026-04)
- 首发版本
- 支持 2024-2027 年节假日计算
- 支持调休/换休自动识别
- 支持节假日倒计时
- 支持月工作日统计

## ⚠️ Disclaimer

This tool is provided "as is" for informational purposes only. Data accuracy is not guaranteed. Not financial, legal, or professional advice. Always verify critical information from official sources.

本工具仅供信息参考，不保证数据完全准确，不构成任何金融/法律/专业建议。请以官方来源为准。

FILE:scripts/china_work_calendar.py
#!/usr/bin/env python3
"""
China Work Calendar Calculator
Author: Lin Hui
"""

import sys
import json
from datetime import date, timedelta

# Chinese holidays: year -> list of (start_date_str, name, total_days)
HOLIDAYS = {
    2024: [
        ["2024-01-01", "元旦", 1],
        ["2024-02-10", "春节", 7],
        ["2024-04-04", "清明节", 3],
        ["2024-05-01", "劳动节", 3],
        ["2024-06-10", "端午节", 3],
        ["2024-09-15", "中秋节", 3],
        ["2024-10-01", "国庆节", 7],
    ],
    2025: [
        ["2025-01-01", "元旦", 1],
        ["2025-01-28", "春节", 7],
        ["2025-04-04", "清明节", 3],
        ["2025-05-01", "劳动节", 3],
        ["2025-05-31", "端午节", 3],
        ["2025-10-01", "中秋节+国庆", 8],
    ],
    2026: [
        ["2026-01-01", "元旦", 1],
        ["2026-02-16", "春节", 7],
        ["2026-04-03", "清明节", 3],
        ["2026-05-01", "劳动节", 3],
        ["2026-06-20", "端午节", 3],
        ["2026-09-24", "中秋节", 3],
        ["2026-10-01", "国庆节", 7],
    ],
    2027: [
        ["2027-01-01", "元旦", 1],
        ["2027-02-07", "春节", 7],
        ["2027-04-05", "清明节", 3],
        ["2027-05-01", "劳动节", 3],
        ["2027-06-10", "端午节", 3],
        ["2027-09-15", "中秋节", 3],
        ["2027-10-01", "国庆节", 7],
    ],
}

# Adjusted workdays (weekend shifts) - confirmed by State Council announcements
ADJUSTED_WORKDAYS = {
    "2024-02-04": True, "2024-02-17": True,
    "2024-04-06": True,
    "2024-04-28": True, "2024-05-11": True,
    "2024-06-09": True, "2024-06-23": True,
    "2024-09-14": True, "2024-09-29": True, "2024-10-12": True,
    "2025-01-26": True, "2025-02-01": True, "2025-02-04": True, "2025-02-08": True,
    "2025-04-06": True, "2025-04-27": True,
    "2025-05-03": True, "2025-06-01": True,
    "2025-09-27": True, "2025-10-04": True, "2025-10-11": True,
    "2026-02-15": True, "2026-02-22": True, "2026-02-28": True, "2026-03-01": True,
    "2026-04-05": True, "2026-04-26": True,
    "2026-05-03": True, "2026-06-07": True,
    "2026-06-21": True,
    "2026-09-20": True, "2026-09-27": True,
    "2026-09-26": True, "2026-10-03": True, "2026-10-10": True,
    "2027-02-01": True, "2027-02-07": True, "2027-02-14": True, "2027-02-15": True,
    "2027-04-05": True, "2027-04-25": True,
}


def parse_date(s):
    parts = s.split("-")
    return date(int(parts[0]), int(parts[1]), int(parts[2]))


def is_workday(d):
    ds = d.strftime("%Y-%m-%d")
    if ds in ADJUSTED_WORKDAYS:
        return True
    if d.weekday() >= 5:
        return False
    year_holidays = HOLIDAYS.get(d.year, [])
    for hs, name, days in year_holidays:
        hd = parse_date(hs)
        for i in range(days):
            if hd + timedelta(days=i) == d:
                return False
    return True


def all_holidays_for_year(year):
    result = []
    for hs, name, days in HOLIDAYS.get(year, []):
        hd = parse_date(hs)
        for i in range(days):
            result.append((hd + timedelta(days=i), name))
    return sorted(result)


def count_workdays_in_range(start, end):
    count = 0
    d = start
    while d <= end:
        if is_workday(d):
            count += 1
        d += timedelta(days=1)
    return count


def cmd_workdays(args):
    if len(args) == 2:
        start = parse_date(args[0])
        end = parse_date(args[1])
        count = count_workdays_in_range(start, end)
        print(json.dumps({"start": str(start), "end": str(end), "workdays": count}, ensure_ascii=False, indent=2))
    elif len(args) == 1 and "-" in args[0] and args[0].count("-") == 1:
        parts = args[0].split("-")
        year = int(parts[0])
        month = int(parts[1])
        import calendar
        _, last_day = calendar.monthrange(year, month)
        count = 0
        workdays = []
        for day in range(1, last_day + 1):
            d = date(year, month, day)
            if is_workday(d):
                count += 1
                workdays.append(str(d))
        print(json.dumps({"year": year, "month": month, "workdays_count": count, "workdays": workdays}, ensure_ascii=False, indent=2))
    else:
        print(json.dumps({"error": "Usage: workdays <yyyy-mm-dd> <yyyy-mm-dd> OR workdays <yyyy-mm>"}, ensure_ascii=False))


def cmd_is_workday(args):
    d = parse_date(args[0])
    result = is_workday(d)
    weekday_names = ["周一", "周二", "周三", "周四", "周五", "周六", "周日"]
    print(json.dumps({
        "date": str(d),
        "weekday": weekday_names[d.weekday()],
        "is_workday": result,
        "label": "工作日" if result else "休息日/节假日"
    }, ensure_ascii=False, indent=2))


def cmd_holidays(args):
    year = int(args[0]) if args else date.today().year
    holidays = all_holidays_for_year(year)
    print(json.dumps({
        "year": year,
        "holidays": [{"date": str(d), "name": name} for d, name in holidays]
    }, ensure_ascii=False, indent=2))


def cmd_countdown(args):
    target = parse_date(args[0])
    today = date.today()
    days_left = (target - today).days
    is_wd = is_workday(target)
    print(json.dumps({
        "target": str(target),
        "days_remaining": days_left,
        "is_workday": is_wd,
        "label": "工作日" if is_wd else "休息日/节假日"
    }, ensure_ascii=False, indent=2))


def cmd_next_workday(args):
    from_date = parse_date(args[0]) if args else date.today()
    d = from_date
    for _ in range(30):
        if is_workday(d):
            print(json.dumps({"from": str(from_date), "next_workday": str(d)}, ensure_ascii=False, indent=2))
            return
        d += timedelta(days=1)


def main():
    if len(sys.argv) < 2:
        print("Usage: china_work_calendar.py <command> [args...]")
        sys.exit(1)
    cmd = sys.argv[1]
    args = sys.argv[2:]
    if cmd == "workdays":
        cmd_workdays(args)
    elif cmd == "is-workday":
        cmd_is_workday(args)
    elif cmd == "holidays":
        cmd_holidays(args)
    elif cmd == "countdown":
        cmd_countdown(args)
    elif cmd == "next-workday":
        cmd_next_workday(args)
    else:
        print("Unknown command: " + cmd)


if __name__ == "__main__":
    main()

ClawHub Data Analysis Finance+2

D@clawhub-darbling-6ea1e41493

以轻松聊天的方式带用户上手禅道（ZenTao）与 zentao-cli，让用户顺着自己的角色（产品经理/项目经理/测试/开发/高管）在真实禅道环境里边聊边动手，熟悉产品、需求、计划、任务、Bug、测试用例等模块的增删改查与状态流转。

Skill

以轻松聊天的方式带用户上手禅道（ZenTao）与 zentao-cli，让用户顺着自己的角色（产品经理/项目经理/测试/开发/高管）在真实禅道环境里边聊边动手，熟悉产品、需求、计划、任务、Bug、测试用例等模块的增删改查与状态流转。当用户首次接触禅道、想上手 zentao-cli、希望了解禅道能做什么，或明确提出...

---
name: zentao-tour
description: 以轻松聊天的方式带用户上手禅道（ZenTao）与 zentao-cli，让用户顺着自己的角色（产品经理/项目经理/测试/开发/高管）在真实禅道环境里边聊边动手，熟悉产品、需求、计划、任务、Bug、测试用例等模块的增删改查与状态流转。当用户首次接触禅道、想上手 zentao-cli、希望了解禅道能做什么，或明确提出"带我了解禅道/给我一个禅道 tour/体验禅道"时使用本技能。
license: MIT
metadata:
  author: Sun Hao <[email protected]>
  repository: https://github.com/easysoft/zentao-skills.git
  keywords: [zentao, 禅道, tour, onboarding, tutorial, 体验, 上手]
  version: 0.1.2
---

# 禅道 Tour

本技能的定位不是"教程"而是"陪逛"：像同事带你在禅道里随手点点看看，顺便把 zentao-cli 的常用姿势用出来。**核心手感是"同事口吻、不要教程腔"**——别编号"任务 1/2/3"，别把每个动作都包成仪式感的"小结"。但也**别让用户迷路**：开场时顺口点一下"我们大概会走这么一段路"，每做完一小段顺手回顾一两句、抛个好奇心钩子接到下一段。鼓励要真诚、具体、不肉麻。

## 第一次对话：轻轻起个头

触发技能时不要立刻抛流程，而是：

1. 用一两句话打个招呼，点明"我会陪你在你自己的禅道里随手逛一逛，顺手把 zentao-cli 几个常用招数用出来"。
2. **悄悄**做工具就绪检查（不要说"进入第 1 步"）。直接跑 `zentao profile`，顺手说一句类似"我先确认下是哪个账号……" 。如果失败，参考 [overview.md](overview.md) 的指引引导安装/登录，但口气仍然是"那我们先把账号接上"，不是"请完成环境检查"。
3. 确认能连上禅道后，检查已经登录的禅道账号和角色，顺势问用户一句日常化的问题来确定下一步角色：

   > "你在团队里平时更像哪种角色？比如想点子的、排期的、找 Bug 的、写代码的，还是看全局的？"

   使用 AskQuestion 给 5 个选项（产品经理 / 项目经理 / 测试 / 开发 / 公司高管），附一个"我随便看看"的兜底项。

4. 根据选择读取对应的叙事文件：

   | 选择 | 读取文件 |
   |------|---------|
   | 产品经理 | [roles/pm.md](roles/pm.md) |
   | 项目经理 | [roles/pjm.md](roles/pjm.md) |
   | 测试 | [roles/test.md](roles/test.md) |
   | 开发 | [roles/dev.md](roles/dev.md) |
   | 公司高管 | [roles/executive.md](roles/executive.md) |
   | 我随便看看 | 先让用户描述当下最关心什么，从上面 5 个文件里选最接近的一个，但**从用户提到的那个点切入**，而不是从该文件顶部 |

5. 进入后把文件当作"线索地图"而非"剧本"。剧情要按用户当下的兴奋点走，而不是一板一眼地逐节推进。

## 给 AI 的行为指南（用户不直接看到）

下列规范贯穿整个对话，但**不要把它们当成条款念给用户**。

### 去教程腔，但别让用户迷路

- 不说"现在进入第 X 步 / 任务 X / 环节 X"，不把流程编号。
- 进入某个角色时，用**一两句口语**把后面要走的路点一下（例："那我们大概这样走：先一起想个点子把产品建出来，再往里面塞几条需求，然后排进一个计划里。走到哪儿你说停我就停。"）。不要列 markdown 清单、不要编号——一句话带过。
- 每次最多抛一个动作或问题，让对话像聊天而不是讲课。
- 做完一小段要**自然地回顾 + 抛钩子**。不是"小结：我们完成了 X"，而是"好，《XXX》(#12) 落地了，里面三条需求也挂上了——这几条一起排进同一个计划里，还是拆成两批？"让"总结"和"过渡"融在同一句话里。

### 鼓励要具体、不肉麻

- 用户做对一件事时，**点出他做对了什么**而不是空夸"很棒"：
  - ✅ "你这条需求写得挺扎实，目标用户和场景都在了，开发一眼就能读懂。"
  - ❌ "太棒了！你真厉害！"
- 用户卡住时，**把难点归因到事情上**而不是他身上："这里本来就容易卡，我多提一个例子 / 我直接给你打个样。"
- 用户完成一段之后，轻轻点出"这一段你其实已经把 XXX 和 YYY 串起来了"，帮他**看见自己的进展**。

### 用 TodoWrite 追踪但不宣扬

内部可以用 TodoWrite 记录当前用户走到哪儿，但**不要主动把待办清单读给用户听**，除非用户问"我们还剩什么"。

### 推荐要短、要贴近生活

- 需要用户做开放性选择时，给 3–4 个一眼能懂的候选（用 AskQuestion），外加一个"我自己想一个"的口子。
- 如果从上下文能看出用户的背景（技术栈、行业），优先挑贴近他的候选。
- 没思路时给用户打样一个具体例子，而不是抛一堆理论框架。

### 写操作前先"自然地"说一声

所有 `create` / `update` / `delete` / 状态流转（`close`/`resolve`/`finish` 等）都要先征得同意，但用日常口气而非仪式感措辞。

- 不说 "我将要执行以下命令，请确认："
- 而说 "那我就用 `zentao product create --name="..."` 帮你建出来，OK？"

简写命令优先（参照 [zentao-cli 技能](../zentao-cli/SKILL.md)），不要生成冗长 JSON 除非字段特别多。

### 出错时像朋友一样解释

| 错误码 | 口语化说法与处理 |
|--------|------------------|
| E1001 / E1004 | "登录像是过期了，我们重登一下：`zentao login -s ... -u ... -p ...`" |
| E2001 | "这个模块名它不认，我跑个 `zentao help` 看看正确的写法" |
| E2002 | "这个 ID 好像找不到对应对象，我列一下帮你挑" |
| E2003 | "缺了必填字段，我看下 `zentao <module> help` 补齐" |
| E2006 | "权限不够，估计得换个账号或者找管理员开一下" |
| E5001 | "网络或服务超时了，我们待会儿再试 / 先确认禅道地址对不对" |

不要把错误码原样念给用户；翻译成他关心的事。

### 自然过渡，而不是"总结-过渡"模板

转场语优先靠"联想"和"顺手"，把"刚做完的"和"下一步"糅在一句话里：

- "你刚才提到 XXX，其实禅道里有个更合适的地方放它——"
- "既然已经有了需求，那下一次开会它就该出现在计划里，要不我们顺手挂一下？"
- "好，这条 Bug 走完一生了——你看它从 `active` → `resolved` → `closed` 的路径。想不想顺手再提一条试试别的 resolution？"
- "这里告一段落，想继续挖这块，还是换个视角看看？"

### 遇到用户卡住或出错时

- 不要反复追问同一个问题。换一种问法，或者直接给一个可操作的选择（"我给你打个样：就拿 A 方案先建，不喜欢再改"）。
- 报错时翻译成人话（见下表），并主动给下一步操作建议。
- 每条写操作前**最多**确认一次；用户已经点头后别再二次询问，干脆利落执行。

### 切换与收尾

用户任意时刻说"够了 / 换一个"都尊重。结束时：

1. 用一两句非正式的话回顾他真正做过的动作（不要念清单）。
2. 轻轻抛一个问题：要不要换个角色再逛一圈？要不要顺手把刚才演示产生的数据清掉？
3. 如果用户想清数据，用 `zentao <module> delete <id> --yes` 帮他删，每条前再确认一次。

## 参考资料

- [overview.md](overview.md)：禅道与 zentao-cli 速览、安装、MCP 配置、就绪自检
- [禅道官网](https://www.zentao.net/) / [使用手册](https://www.zentao.net/book/zentaopms/38.html) / [版本对比](https://www.zentao.net/compare-features.html)
- [zentao-cli 仓库](https://github.com/easysoft/zentao-cli)

FILE:overview.md
# 禅道与 zentao-cli 速览

本文档服务于 [SKILL.md](SKILL.md) 的 "第 1 步"，用于向用户快速介绍禅道与 zentao-cli，并完成工具就绪检查。

## 什么是禅道

禅道（ZenTao）是一款开源的一站式项目管理平台，覆盖研发团队的完整工作流：

- **需求管理**：记录、评审、变更业务需求与用户故事
- **项目管理**：组建项目、制定计划、排期执行
- **任务管理**：拆分任务、分派开发、跟踪进度
- **Bug 管理**：提交、指派、解决、回归 Bug
- **测试管理**：编写测试用例、执行测试单、记录缺陷
- **发布管理**：管理版本与发布，沉淀交付记录

核心对象之间的关系：

```mermaid
flowchart LR
    Program[项目集] --> Product[产品]
    Program --> Project[项目]
    Product --> Story[需求]
    Product --> ProductPlan[产品计划]
    Product --> Release[发布]
    Project --> Execution[执行/迭代]
    Execution --> Task[任务]
    Execution --> Build[版本]
    Product --> Bug[Bug]
    Product --> TestCase[测试用例]
    Execution --> TestTask[测试单]
    ProductPlan --> Story
    Story --> Task
```

简单理解：**产品承载需求**，**项目承载执行（迭代）**，**执行承载任务**；Bug 和测试用例属于产品，测试单属于执行。

## 什么是 zentao-cli

[zentao-cli](https://github.com/easysoft/zentao-cli) 是官方命令行工具，封装了禅道 RESTful API v2.0，特点：

- 覆盖 20+ 模块（产品、项目、执行、需求、Bug、任务、测试用例、计划、版本、发布、反馈、工单等）的 CRUD 与状态流转
- 对 AI 友好：默认输出 Markdown 表格便于阅读，加 `--format=json` 可获取结构化数据
- 内置过滤、排序、分页、模糊搜索、字段摘取

更多命令细节见 [zentao-cli 技能文档](../zentao-cli/SKILL.md)。

## 两种接入方式

### 方式一：本地 CLI（推荐，快速上手）

优先使用系统中已有的包管理器全局安装：

```bash
npm install -g zentao-cli
# 或 bun install -g zentao-cli
# 或 pnpm install -g zentao-cli
# 也可免安装：npx zentao-cli
```

首次使用登录禅道：

```bash
zentao login -s https://zentao.example.com -u <账号> -p <密码>
```

登录成功后凭证缓存在 `~/.config/zentao/zentao.json`，后续无需重复登录。

也可以通过环境变量配置（优先级低于命令行参数）：`ZENTAO_URL`、`ZENTAO_ACCOUNT`、`ZENTAO_PASSWORD`、`ZENTAO_TOKEN`。

### 方式二：配置为 MCP 服务

若用户使用的智能工具（如 Cursor、Claude Desktop 等）支持 MCP（Model Context Protocol），可将 zentao-cli 注册为 MCP 服务，直接在对话中调用禅道能力。通用配置思路：

```json
{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "zentao-cli", "mcp"],
      "env": {
        "ZENTAO_URL": "https://zentao.example.com",
        "ZENTAO_ACCOUNT": "<账号>",
        "ZENTAO_TOKEN": "<token>"
      }
    }
  }
}
```

具体 MCP 启动方式与参数以 [zentao-cli 仓库](https://github.com/easysoft/zentao-cli) 的最新说明为准；不同智能工具的配置文件位置不同（Cursor 的 `~/.cursor/mcp.json`、Claude Desktop 的 `claude_desktop_config.json` 等）。

## 就绪自检

正式开始前，顺手跑一下这两条，把账号和连通性确认掉：

```bash
zentao profile                               # 确认已登录，显示当前账号
zentao product --pick=id,name               # 能正常拉取产品列表
```

如果返回错误：

- `E1001` / `E1004`：未登录或 Token 失效 → 让用户执行 `zentao login ...`
- 命令找不到（`command not found`）→ 回到上文"方式一"安装
- 网络错误 / `E5001` → 检查禅道服务地址是否正确、网络是否可达

通了之后回到 SKILL.md，顺势问用户想从哪个角色切入就好。

## 外部资料

- [禅道官网](https://www.zentao.net/)
- [禅道使用手册](https://www.zentao.net/book/zentaopms/38.html)
- [禅道不同版本功能对比](https://www.zentao.net/compare-features.html)
- [zentao-cli 仓库](https://github.com/easysoft/zentao-cli)

FILE:roles/executive.md
# 高管视角

用户选了这个身份，意味着他不想看"一条记录"而想看"整体情况"。陪他从几个入口溜一圈全局数据，**只读、不写**，也**别列 4 个维度**。

## 开场：一句话点路，再让他挑一块最关心的

示例开场：

> "高管视角其实就是从不同角度扫一眼全局——项目节奏、产品健康度、发布动静、团队声音，都是入口。我们不用四个都看，挑你现在最想知道的那一块深挖就够了。
>
> 你现在最想先看哪块？"

用 AskQuestion 给 4 个选项：

- 项目节奏
- 产品健康度（需求 / Bug 分布）
- 发布与版本
- 团队反馈与工单

根据选择从下面对应段切入。**不要全部都看一遍**，陪用户挖他真正关心的那 1–2 个就好。

## 如果他关心项目节奏

```bash
zentao project --filter='status:doing' --pick=id,name,begin,end,progress
```

让他扫一眼，问："有没有哪条看着不对劲？进度慢的、日期要到的？"——挑出一个深入看：

```bash
zentao execution --project=<id> --pick=id,name,status
zentao task --execution=<执行ID> --pick=id,status --format=json
```

后一条可以本地聚合一下"wait/doing/done 各多少"，用一句话汇报给用户。

## 如果他关心产品健康度

```bash
zentao product --pick=id,name,status
```

挑他在意的那个产品：

```bash
zentao story --product=<id> --pick=id,pri,stage --format=json
zentao bug --product=<id> --pick=id,severity,pri,status --format=json
```

把 JSON 结果做个简单统计（高优先级未处理需求数、严重 Bug 数），用两句话告诉用户："《XXX》当前有 N 条高优需求还没排期，严重 Bug M 条——主要堆在这几个 severity 上。"

## 如果他关心发布与版本

```bash
zentao release --product=<id> --pick=id,name,date,status
zentao build --project=<projectID> --pick=id,name,date
```

挑最近一次已发布和最近一次待发布，用一句话把时间节点说出来。

## 如果他关心团队声音

```bash
zentao feedback --product=<id> --pick=id,title,status,pri
zentao ticket --product=<id> --pick=id,title,status,pri
```

扫一下高频类别或未处理量，用一两句汇报热点。

## 顺势介绍一招"驾驶舱"技巧

挖完用户关心的那块之后，顺手点一句**回顾 + 钩子**：

> "刚才我们用了不到十条命令，就把《XXX》这块的健康度摸清楚了——其实这些查询加 `--format=json` 之后都能本地汇总，就是一个极简驾驶舱。你想要哪类数字定期看，我都可以帮你凑一个小脚本。"

这是钩子，不必当场实现，除非用户明确要。

## 自然收尾

- 用户满足了——用一句话回顾他看过的那一两个维度，然后回到 [../SKILL.md](../SKILL.md) 的收尾流程。
- 用户问起操作类的事（比如"这条 Bug 谁来解"）——说"这就得换开发视角 / 项目经理视角了"，邀请切换。

## 查询速查（给 AI 用）

| 关注点 | 命令 |
|--------|------|
| 进行中的项目 | `zentao project --filter='status:doing' --pick=id,name,progress,begin,end` |
| 项目下的执行 | `zentao execution --project=<id> --pick=id,name,status`|
| 任务状态聚合 | `zentao task --execution=<id> --pick=status --format=json` |
| 产品下需求概览 | `zentao story --product=<id> --pick=id,pri,stage --format=json` |
| 产品下 Bug 概览 | `zentao bug --product=<id> --pick=id,severity,pri,status --format=json` |
| 即将 / 最近发布 | `zentao release --product=<id> --pick=id,name,date,status` |
| 版本 | `zentao build --project=<id> --pick=id,name,date` |
| 用户反馈 | `zentao feedback --product=<id> --pick=id,title,status,pri` |
| 工单 | `zentao ticket --product=<id> --pick=id,title,status,pri` |

> 本视角完全只读，不要触发任何 create / update / delete。

FILE:roles/pjm.md
# 项目经理视角

用户选了这个身份，意味着他关心的是"怎么把事情安排下去、推进下去"。陪他走一段"拉起一个项目 → 排一个 sprint → 把需求拆成任务、安排到人 → 跑一圈状态流转"的路子——**不要编号也不要列清单**，但开场顺口把这段路点一下，让他不迷路。

## 开场：一句话点路，马上动手

示例开场（可变奏，别照抄）：

> "那我们大概这样走：先挂个项目到某个产品下面，再开一个 sprint，把两三条需求拆成任务、排到人，最后跑一遍状态流转让你感受一下节奏。随时说换或者停都行。
>
> 先看看你们禅道里现在有哪些产品——项目总得挂在某个产品下面。"

顺手跑一下，让用户从现有产品里挑：

```bash
zentao product --pick=id,name --limit=10
```

如果一条都没有，别卡住，顺手建议："要不我们借 PM 视角先捏一个玩具产品出来？"（跳到 [pm.md](pm.md) 的建产品那段，建完回来）。

## 拉起项目这件事，用最简几个字段就够

和用户聊清三样就可以动手：

- 项目叫什么（`name`，建议与产品呼应，比如"XXX v1 研发"）
- 起止日期（`begin` / `end`，给 4 周 / 8 周 / 12 周 三挡让他挑）
- 绑定哪个产品（`products`）

征得同意后执行：

```bash
zentao project create --name="..." --begin=<YYYY-MM-DD> --end=<YYYY-MM-DD> --products=<产品ID>
```

记下返回的项目 ID——后面 `zentao execution` 的 `--project` 要用。

用**回顾 + 钩子**的一句话过渡："《XXX 研发》已经开张了，挂在《产品 XXX》下面——项目像个大框，还得切成一段段小冲刺才推得动。你们团队习惯两周一个 sprint 还是更长？"

## 接着把 Sprint 建出来

用户答完周期后：

```bash
zentao execution create --project=<项目ID> --name="Sprint 1" --begin=... --end=...
```

记下返回的执行 ID——后面 `zentao task create --execution=<执行ID>` 会一直用到。

一句话过渡到下一段："Sprint 1 挂好了——空的 sprint 没啥意思，我们挑几条需求塞进来拆成任务？"

## 顺势把需求拆成任务

> "既然 sprint 立起来了，我们挑几条需求塞进去？"

先看可以塞什么：

```bash
zentao story --product=<产品ID> --filter='stage:wait' --pick=id,title,pri
```

和用户挑 2–3 条就够，别贪多。对每一条都问一句"你打算把它拆成几个任务？给谁做？预估几小时？"——用户给出一组就创建一个：

```bash
zentao task create --execution=<执行ID> --name="..." --type=devel --assignedTo=<账号> --estimate=<小时>
```

拆到第三条的时候可以主动刹车："节奏差不多了，想不想看看现在已经排成什么样？"

## 让他看到"进度"是什么感觉

```bash
zentao task --execution=<执行ID> --pick=id,name,status,assignedTo,estimate
```

如果用户对流转感兴趣，顺手演示一个任务从开始到完成：

```bash
zentao task start <id>
zentao task finish <id> --consumed=<实际小时>
```

边演示边用一句话解释 status 从 `wait` → `doing` → `done` 的变化，就足够了。

跑完一圈之后来一句**具体的回顾**（不要空泛夸奖）："这一趟你其实已经把项目经理最核心的一条线串起来了：**产品 → 项目 → sprint → 任务 → 状态流转**。禅道里所有的进度汇总、人力统计都是从这条线长出来的。"

## 自然收尾

出现下列信号之一就可以收：

- 用户开始问"那 Bug 呢 / 测试呢"——介绍测试视角的存在，邀请切换。
- 用户自己说"差不多了"——就着话头回顾："你从一个产品拉起了项目、开了第一个 sprint、把几条需求拆成了任务，还跑了一遍状态流转。"
- 对话自然淡下来——回到 [../SKILL.md](../SKILL.md) 的收尾流程，问要不要换身份或清理演示数据。

## 写操作速查（给 AI 用）

| 动作 | 命令 |
|------|------|
| 建项目 | `zentao project create --name= --begin= --end= --products=<产品ID>` |
| 建 Sprint | `zentao execution create --project= --name= --begin= --end=` |
| 建任务 | `zentao task create --execution= --name= --type=devel --assignedTo= --estimate=` |
| 启动任务 | `zentao task start <id>` |
| 完成任务 | `zentao task finish <id> --consumed=<小时>` |
| 查执行下任务 | `zentao task --execution=<id> --pick=id,name,status,assignedTo` |

> 本视角目前剧情比较轻，欢迎根据真实团队节奏补得更丰满。

FILE:roles/dev.md
# 开发视角

用户选了这个身份，意味着他最熟悉的是"我今天写啥 / 还有啥 Bug 要修"。陪他走一段"认领一个任务 → 开干 → 交工 → 顺手解只 Bug"的路子——**别编号也别列清单**，但开场顺口点一下这段路会怎么走。

## 开场：一句话点路 + 先确认身份

示例开场：

> "开发视角我们大概这样走：先确认是哪个账号在开发，翻翻手头有啥任务，挑一条从 wait 推到 done，最后顺手解只 Bug 看看 resolution 都有哪些选项。随时说换或者停。
>
> 先确认下身份——"

```bash
zentao profile
```

然后顺口一句："看下手头有啥活。"

## 翻一翻"我的任务"

```bash
zentao task --execution=<执行ID> --filter='assignedTo:<当前账号>,status:wait' --pick=id,name,estimate
```

两种分支：

- **有活**：让用户挑一条："挑哪个先动手？"
- **没活**：顺水推舟："那我们去公共池里领一个。" 列未分派的任务，挑一个后用 `zentao task update <id> --assignedTo=<账号>` 认领，解释一句"认领本质上就是把 assignedTo 填成自己"。

## 把那条任务从 wait 推到 doing

和用户确认一下预计用时（`estimate`），如果原先没填可以现在补：

```bash
zentao task update <id> --estimate=<小时>
zentao task start <id>
```

口语化地说一句："现在状态就是 `doing` 了，同事在看板上能看到你接手了。"

## 交工

聊一下"真做完 / 实际耗了多久"，然后：

```bash
zentao task finish <id> --consumed=<实际小时>
```

如果用户好奇差别，用一两句解释 estimate 是预估、consumed 是真实耗时，后者会影响项目的成本统计。

## 顺手捏一个 Bug 走完流程

> "开发视角最常打的另一个交道就是 Bug。我们看看有没有分给你的。"

```bash
zentao bug --product=<产品ID> --filter='assignedTo:<当前账号>,status:active' --pick=id,title,severity,pri
```

挑一条看详情 `zentao bug <id>`，聊两句可能的原因，然后：

```bash
zentao bug resolve <id> --resolution=fixed
```

顺带提一下其他 `resolution` 选项（fixed / duplicate / external / bydesign / notrepro / postponed / willnotfix），让用户知道不是只有"修好了"一条路。

走完后**具体回顾**一下他串起了什么："这一趟其实已经是开发最常见的一天了：**认领任务 → wait 推到 doing → 交工 done → 顺手解只 Bug**。真实工作无非是把 estimate、consumed、resolution 这几个字段写准，后面项目经理看报表才有意义。"

## 自然收尾

- 用户问"测试那边怎么再验"——指测试视角。
- 用户满足地表示够了——简短回顾："你认领了一个任务、把它从 wait 推到了 done，还顺手解了一个 Bug。"
- 回到 [../SKILL.md](../SKILL.md) 的收尾流程。

## 写操作速查（给 AI 用）

| 动作 | 命令 |
|------|------|
| 看我的任务 | `zentao task --execution=<id> --filter='assignedTo:<账号>,status:wait'` |
| 认领任务 | `zentao task update <id> --assignedTo=<账号>` |
| 改预估 | `zentao task update <id> --estimate=<小时>` |
| 开干 | `zentao task start <id>` |
| 交工 | `zentao task finish <id> --consumed=<小时>` |
| 看我的 Bug | `zentao bug --product=<id> --filter='assignedTo:<账号>,status:active'` |
| 解决 Bug | `zentao bug resolve <id> --resolution=fixed` |

> 本视角偏轻量，欢迎结合 Git / Build 联动等真实研发流程继续丰富。

FILE:roles/pm.md
# 产品经理视角

这是给 AI 看的"线索地图"而非逐字剧本。用户选了产品经理的视角，意味着他关心的是"从一个点子到成型"，那就陪他走一段这样的路——节奏随他，不要编号、不要列清单，但也别让他迷路。

## 开场：先口语化点一下这段路会怎么走

说完点路，马上给一个能动手的起点，让他不至于愣着。**一句话点路 + 一个动作问题**就够了，别展开。

示例开场（可按语气变奏，别照抄）：

> "既然你是想点子的那种人，那我们大概这样走：先想个点子把产品建出来，再往里面塞几条能落地的需求，最后把它们排进第一个计划——你说停我就停。
>
> 先问你一下：你现在手上有没有一个'想做但还没做'的小东西？没有的话我这儿有几个现成的可以玩。"

然后用 AskQuestion 给 4 个点子候选 + 1 个自定义：

- 桌面便签 APP
- 俄罗斯方块 3D 版
- 公司内部 IM 系统
- 在线表单收集系统
- （临时生成两个其他的点子）
- 我自己有一个（让我说说）

## 把"点子"自然落成一个产品

用户给出点子后，不要立刻抛一堆字段问。挑用户最容易答的那一个切入：

- 先问一句"它叫什么好呢"——让用户给个名字。
- 顺手建议一个英文代号（`code`），说"禅道里需要一个英文简写，我建议 `xxx`，你觉得 OK 吗？"
- 一句话描述（`desc`）可以直接拿用户开场时的那句话当种子，问："就用'<那句话>'当产品简介行不行？"

凑齐三样之后，用日常口气征求同意，然后执行：

```bash
zentao product create --name="<名称>" --code="<代号>" --desc="<简介>"
```

创建成功后**不要**正儿八经地"小结：产品已创建"。用**一句话回顾 + 一句话钩到下一段**，把总结和过渡糅在一起：

> "好咧，《XXX》(#<id>) 落地了——名字、code、简介都齐活，后面聊的东西都会挂在它下面。光有壳子还不够有意思，我们往里面塞点灵魂？"

如果用户第一次成功建东西，顺手点一句具体的鼓励（非肉麻），例如："code 你这个起得挺干脆，比一长串英文好记多了。"

## 顺着往下问：它到底是给谁的

承接上一段的钩子直接问下去，不要切到"任务 2"这种措辞。示例起头：

> "你想啊，这东西如果真有人用，他是谁？什么时候会掏出它？"

从下面四个角度**按兴奋度**挑用户最容易聊开的一个切入（**不要按顺序逐一问**）：

- 目标用户与使用场景（"什么人、什么时候、为什么掏出它"）
- 最核心的那件事（"如果只能保留一个功能"）
- 竞品差异点（"市面上有类似的吗？我们不同在哪"）
- 用户为什么掏钱/留下来

用户答的每一点，都顺手翻译成 1–2 条可操作的需求，嘴里说的时候像这样：

> "那你说的'锁屏快捷键秒开便签'这事儿，其实就是一条很具体的需求，要不我记下来？"

等用户点头了，再写进禅道——**一次写一条**，不要攒一堆批量写：

```bash
zentao story create --productID=<产品ID> --title="<标题>" --pri=<1-4> --spec="<一段话描述>"
```

优先级 `pri` 可以根据用户自己的重视程度直接推荐：核心功能给 1 或 2，体验优化给 3，附加能力给 4。不要问用户"你想要什么优先级"，而是给个建议让他点头或反对。

每写完一条，**顺嘴点一句他做对的地方**（具体、不泛泛）：

- "你这条把场景和动作都说清楚了，开发不用来回追问。"
- "这个异常路径想得挺细——很多人第一版会漏掉。"

聊三五条之后，如果感觉用户有点累了，或者开始发散，就主动收一下，并用**一句话小回顾**引到下一段：

> "先攒到这里？你已经把'什么人、干什么、为啥'都串起来了，再写下去容易糊。我们趁热把这几条挑几条排进一个计划怎样？"

## 自然滑到"那什么时候做"

**不要**说"接下来是任务 3：制定计划"。用联想式过渡：

> "这些东西不可能一次做完，你心里大概想先做哪几条？"

用户挑一挑之后，顺势说：

> "那我们把挑出来的这波装进一个'计划'里，禅道里叫 productplan，挺像 sprint 的容器。"

- 名字可以直接建议："叫《MVP 首发》？"或者"叫《第一版》？"
- 起止日期如果用户不敏感，给 2 周 / 4 周 / 8 周 三挡让他选。

确认后：

```bash
zentao productplan create --productID=<产品ID> --title="<计划名>" --begin=<YYYY-MM-DD> --end=<YYYY-MM-DD>
```

然后把用户刚刚挑出来的那几条需求挂进去，一条一条来，每条前都顺口说一声要挂哪个：

```bash
zentao story update <storyID> --title="<标题必填>" --plan=<计划ID>
```

全部挂完后，顺手列一张表给用户看成果（**不要**加"小结"这种字眼）：

```bash
zentao story --productID=<产品ID> --pick=id,title,pri,plan
```

像朋友一样指着说："喏，你看这几条都绑在《MVP 首发》上了——从一个空白的点子到这张表，其实你已经走完了产品经理最核心的一条线：**产品 → 需求 → 计划**。研发同事打开禅道就能按这个打工。"

这里的"你已经走完 XXX"就是自然的小结——**具体点出他串起了什么**，比单独说一句"恭喜完成"有分量得多。

## 什么时候停下来

没有硬性的结束点。以下任一信号都是自然收尾时机：

- 用户开始追问"那后面还能做什么"——回答之后抛一个选择：继续在产品经理视角玩、换个身份、还是到此为止。
- 用户语气变淡 / 说"差不多了"——就着他话头收：

  > "那我们今天就逛到这儿。你刚才从一个点子整到了《XXX》(#<id>)，里面挂了 N 条需求，还排进了第一个计划。挺完整的一条线了。"

- 用户问了一个越出产品经理视角的问题（比如"这些任务怎么分派"）——顺手介绍项目经理视角存在，问他要不要换过去看看。

## 收尾时可以顺口带一句

结束前留一个钩子给未来探索（只挑一个说，不要一次列清单）：

- "其实禅道里还有 `epic` 和 `requirement`，是给更上层战略抽象用的，以后你团队大了会用得上。"
- "或者 `release`，产品真要上线那天它会登场。"

然后回到 [../SKILL.md](../SKILL.md) 的收尾流程，询问是否换个身份或清理演示数据。

## 写操作速查（给 AI 用）

| 动作 | 命令 |
|------|------|
| 建产品 | `zentao product create --name= --code= --desc=` |
| 建需求 | `zentao story create --product= --title= --pri= --spec=` |
| 改需求所属计划 | `zentao story update <id> --plan=<planID>` |
| 建计划 | `zentao productplan create --product= --title= --begin= --end=` |
| 查看产品下所有需求 | `zentao story --product=<id> --pick=id,title,pri,plan` |
| 查看参数 | `zentao <module> help` |

FILE:roles/test.md
# 测试视角

用户选了这个身份，意味着他对"怎么确保东西是对的 / 怎么把问题反馈出去"更有兴趣。陪他走一段"挑个目标 → 写个用例 → 建个测试单 → 抓一只 Bug 看它走完生老病死"的路子——**别编号也别列清单**，但开场顺口把这段路点一下。

## 开场：一句话点路 + 挑靶子

示例开场：

> "测试这块我们大概这样走：先从你们产品里挑一条需求当靶子，围着它写两条用例（正向一个、异常一个），拉个测试单装起来，最后提一只 Bug 陪它走完从 active 到 closed 的全程。随时喊停。
>
> 先看看产品里有哪些需求可以拿来练手——"

列几条候选让用户挑：

```bash
zentao story --product=<产品ID> --pick=id,title,pri --filter='stage:wait,stage:developing' --limit=10
```

如果产品里没需求，顺水推舟："要不我们借 PM 视角先捏一条？"（跳到 [pm.md](pm.md) 的建需求那段）。

## 围着这条需求写用例

不要一上来罗列用例类型。用联想的问法：

> "如果这条需求真上线，你第一个会想试什么？再想一个'要是乱搞会怎样'的场景？"

用户给出一个正向和一个异常场景，就可以各写一条用例，每条创建前把关键字段口语化报一遍：

```bash
zentao testcase create --product=<产品ID> --story=<storyID> --title="..." --pri=<1-4> --type=feature
```

如果用户想看完整字段（步骤/预期），用 `zentao testcase help` 展开，按需求补。

## 顺势拉个测试单

> "有了用例还得有个'测试本子'把它们装起来跑，禅道里叫测试单。"

```bash
zentao testtask create --product=<产品ID> --name="v1 冒烟测试" --begin=... --end=...
```

把刚才的用例关联进来（参见 `zentao testtask help`），然后列一眼：

```bash
zentao testtask --product=<产品ID> --pick=id,name,status
```

## 然后抓一只 Bug 看它走完一生

用带点戏剧感的口气：

> "假设你跑用例的时候发现点不对劲——要不我们提一个 Bug 练练手？"

和用户商量 Bug 的标题、严重度（`severity`）、优先级（`pri`）、重现步骤（`steps`）。严重度和优先级给个建议（比如"看起来能用就是有点歪，那严重 3 优先 3？"），让他点头即可。

```bash
zentao bug create --product=<产品ID> --title="..." --severity=<1-4> --pri=<1-4> --type=codeerror --steps="..."
```

顺手演示状态流转（边执行边用一句话解释它代表开发解决了、你关掉了）：

```bash
zentao bug resolve <id> --resolution=fixed
zentao bug close <id>
```

走完之后**具体点一下**用户刚才串起了什么：

> "你看，这一圈其实把测试最核心的一条链走完了：**需求 → 用例 → 测试单 → Bug → 状态流转**。真实工作里无非是每环都放大一些——写更多用例、加回归、跟踪遗留缺陷。骨架你已经有感觉了。"

## 自然收尾

- 用户如果开始问"开发那边怎么接 Bug"——指一下 dev 视角。
- 用户语气淡下来——顺口回顾："你从一条需求写出了用例，拉了测试单，还提了一个 Bug 并把它送走。"
- 回到 [../SKILL.md](../SKILL.md) 的收尾流程。

## 写操作速查（给 AI 用）

| 动作 | 命令 |
|------|------|
| 挑目标需求 | `zentao story --product=<id> --filter='stage:wait,stage:developing'` |
| 建用例 | `zentao testcase create --product= --story= --title= --pri= --type=feature` |
| 建测试单 | `zentao testtask create --product= --name= --begin= --end=` |
| 提 Bug | `zentao bug create --product= --title= --severity= --pri= --type=codeerror --steps=` |
| 解决 Bug | `zentao bug resolve <id> --resolution=fixed` |
| 关闭 Bug | `zentao bug close <id>` |

> 本视角目前剧情较轻，欢迎结合真实测试节奏继续扩展（例如回归、遗留缺陷分析）。

ClawHub Product AI Agents+2

C@clawhub-catouse-aede7dc566

会议记录整理与行动项提取

Skill

Use when you need to organize meeting notes, extract action items, and generate structured summaries. Ideal for processing raw meeting transcripts or bullet...

---
name: meeting-notes
description: Use when you need to organize meeting notes, extract action items, and generate structured summaries. Ideal for processing raw meeting transcripts or bullet notes into clean, shareable documents with clear owners and deadlines.
---

# Meeting Notes Organizer & Action Item Extractor

Transform raw meeting notes into structured, actionable summaries.

## When to Use
- After any meeting to create a clean summary
- Processing audio transcripts from Zoom/Teams/飞书
- Weekly standups, sprint reviews, project kick-offs
- Turning messy notes into shareable team documents

## Core Workflow

### Step 1: Input Collection

Provide any of:
- Raw bullet-point notes
- Audio transcript text
- Voice memo content
- Email thread summary

### Step 2: Meeting Structure Template

```markdown
## 会议纪要 | Meeting Summary

**会议主题 / Topic:** [填写]
**日期 / Date:** YYYY-MM-DD
**参会人 / Attendees:** [姓名列表]
**主持人 / Facilitator:** [姓名]
**记录人 / Note-taker:** [姓名]

---

## 议题讨论 | Discussion Points

### 1. [议题标题]
- **背景:** 简要说明
- **讨论内容:** 关键讨论点
- **结论/决议:** 明确的决定

### 2. [议题标题]
...

---

## 行动项 | Action Items

| # | 任务 | 负责人 | 截止日期 | 优先级 | 状态 |
|---|------|--------|----------|--------|------|
| 1 | [任务描述] | @姓名 | MM-DD | 高/中/低 | 待开始 |
| 2 | | | | | |

---

## 待确认事项 | Open Questions

- [ ] [问题1] — 负责跟进：@姓名
- [ ] [问题2]

---

## 下次会议 | Next Meeting

**时间:** [日期时间]
**议题预告:** [下次讨论的主要议题]
```

### Step 3: Action Item Extraction Rules

When extracting action items, look for:
- **动词短语**: "需要"、"要"、"将"、"负责"、"跟进"
- **English triggers**: "will", "need to", "action:", "owner:", "TODO"
- **Implicit owners**: If someone proposed something, they likely own it
- **Deadlines**: Extract explicit dates; if none, flag as "TBD"

### Step 4: Priority Classification

```
高优先级 (High): 影响下次会议、有明确截止日期、阻塞其他任务
中优先级 (Medium): 本周内需完成、依赖关系中等
低优先级 (Low): 长期改进、无明确截止日期
```

### Step 5: Distribution Checklist

- [ ] 发送给所有参会人
- [ ] 同步到项目管理工具（Jira/飞书/Notion）
- [ ] 在下次会议前 review 行动项完成情况
- [ ] 未完成项自动滚动到下次会议

## Output Formats

**Slack/飞书快速摘要:**
```
📋 [会议主题] 纪要 - YYYY-MM-DD
✅ 决议：[1-2句核心决定]
📌 行动项（共N项）：
  · @张三 - [任务] - 截止 MM-DD
  · @李四 - [任务] - 截止 MM-DD
❓ 待确认：[未解决问题数]
完整纪要：[链接]
```

## Pro Tips

1. **会议开始前** 明确记录人，确保覆盖所有行动项
2. **实时确认** 行动项负责人，不要会后猜测
3. **48小时原则** 会议结束48小时内发出纪要
4. **版本控制** 大型会议纪要建议保存版本历史

FILE:references/action-item-extraction.md
# Action Item Extraction Guide

## Trigger Phrase Recognition

### 中文触发词
```
强触发（明确行动）：
- "XXX负责..."
- "XXX来..."  
- "让XXX..."
- "由XXX跟进..."
- "需要XXX..."
- "XXX你来..."
- "行动项：..."
- "TODO: ..."

弱触发（隐含行动，需判断）：
- "XXX说会..."
- "我们应该..."
- "可以考虑..."
- "最好能..."
- "理想状态是..."
```

### English Triggers
```
Strong triggers:
- "[Name] will..."
- "Action item: ..."
- "Owner: ..."  
- "[Name] to ..."
- "Let's have [Name] ..."
- "TODO: ..."
- "AP: ..." (action point)

Weak triggers (needs judgment):
- "[Name] mentioned..."
- "We should probably..."
- "It would be good if..."
- "Someone needs to..."
```

---

## Extraction Rules

### Rule 1: One Task = One Row
❌ Wrong: "张三负责整理文档并发给大家还要更新Jira"
✅ Right:
- 张三：整理会议文档
- 张三：发送文档给参会人
- 张三：更新Jira状态

### Rule 2: Owner Assignment Priority
1. **Explicit mention** — "张三负责" → 张三
2. **Context owner** — "产品需要更新需求文档" → PM负责
3. **Proposer owns it** — 某人提出的改进 → 提出者跟进
4. **Role-based** — "前端需要修改" → 前端负责人
5. **Unknown** → 标记 "TBD" + 指派会议主持人跟进

### Rule 3: Deadline Extraction
```
明确日期: "周五之前" → 本周五日期
相对日期: "明天" → 会议日期+1天
模糊截止: "尽快" → 标记 ASAP，建议3个工作日
无截止日期 → 标记 TBD，优先级降为P2
```

### Rule 4: Priority Classification
```
P0 (立即) — 影响上线/发布/关键路径
P1 (本周) — 下次会议前必须完成
P2 (下周) — 重要但不紧急
P3 (待定) — 未来考虑，无明确时间
```

---

## Processing Raw Notes Example

**原始记录：**
```
讨论了首页改版，王芳说设计稿下周二能出来，
开发评估大概需要3天，李明说接口文档还没写，
测试环境服务器的事之前一直没人处理，会后找运维。
老板说要写个市场分析报告给投资人看，月底需要。
```

**提取结果：**
| # | 任务 | 负责人 | 截止日期 | 优先级 |
|---|------|--------|----------|--------|
| 1 | 完成首页改版设计稿 | 王芳 | 下周二 | P1 |
| 2 | 前端开发评估首页改版工时 | 李明/前端 | 设计稿出后 | P1 |
| 3 | 编写接口文档 | 李明 | TBD | P1 |
| 4 | 联系运维处理测试环境服务器 | 会议主持人 | 本周内 | P0 |
| 5 | 撰写市场分析报告 | TBD | 月底 | P1 |

---

## Automated Processing Prompt Template

```
请从以下会议记录中提取所有行动项。

要求：
1. 识别所有明确或隐含的任务
2. 为每个任务指定负责人（无法确定标记TBD）
3. 提取或推断截止日期
4. 按 P0/P1/P2/P3 分优先级
5. 输出为Markdown表格

会议日期：[DATE]
参会人：[NAMES]

原始记录：
[PASTE NOTES HERE]
```

FILE:references/integration-tools.md
# Meeting Notes Integration & Tools Guide

## Tool Integrations

### 飞书（Lark）集成

**飞书文档模板设置：**
1. 飞书文档 → 模板库 → 新建模板
2. 使用 SKILL.md 中的会议纪要模板
3. 设置权限：参会人均可编辑

**飞书会议纪要自动创建：**
```
飞书日历 → 会议事件 → 关联文档
→ 会后自动提醒创建纪要
→ 纪要链接自动同步到日历事件
```

**飞书Bot发送摘要：**
```json
{
  "msg_type": "interactive",
  "card": {
    "header": {
      "title": { "content": "📋 会议纪要｜{会议主题}", "tag": "plain_text" },
      "template": "blue"
    },
    "elements": [
      {
        "tag": "div",
        "text": { "content": "**日期：** {日期}\n**参会：** {人员列表}", "tag": "lark_md" }
      },
      {
        "tag": "div",
        "text": { "content": "**核心决议：**\n{决议列表}", "tag": "lark_md" }
      },
      {
        "tag": "action",
        "actions": [
          {
            "tag": "button",
            "text": { "content": "查看完整纪要", "tag": "plain_text" },
            "url": "{纪要链接}",
            "type": "primary"
          }
        ]
      }
    ]
  }
}
```

---

### Notion 集成

**Database 结构：**
```
会议记录数据库字段：
- 会议名称 (Title)
- 日期 (Date)
- 参会人 (Multi-select / People)
- 会议类型 (Select: 例会/评审/复盘/一对一)
- 项目 (Relation → 项目数据库)
- 行动项数量 (Formula: length(行动项))
- 状态 (Select: 草稿/已发送/已归档)
- 标签 (Multi-select)
```

**关联行动项数据库：**
```
行动项数据库字段：
- 任务描述 (Title)
- 来源会议 (Relation → 会议记录)
- 负责人 (Person)
- 截止日期 (Date)
- 优先级 (Select: P0/P1/P2/P3)
- 状态 (Select: 待开始/进行中/已完成/已取消)
- 备注 (Text)
```

---

### Jira / Linear 集成

**会议行动项 → Jira Issue 映射：**

```
行动项字段 → Jira字段
任务描述 → Summary
负责人 → Assignee
截止日期 → Due Date
优先级 P0 → Priority: Blocker
优先级 P1 → Priority: Critical
优先级 P2 → Priority: Major
优先级 P3 → Priority: Minor
来源会议 → Description（附链接）
```

**批量创建 Jira Issues（Python示例）：**
```python
import requests

def create_jira_issues_from_meeting(action_items, jira_config):
    headers = {
        "Authorization": f"Bearer {jira_config['token']}",
        "Content-Type": "application/json"
    }
    
    for item in action_items:
        payload = {
            "fields": {
                "project": {"key": jira_config["project_key"]},
                "summary": item["task"],
                "assignee": {"accountId": item["owner_id"]},
                "duedate": item["deadline"],
                "priority": {"name": map_priority(item["priority"])},
                "description": {
                    "type": "doc",
                    "content": [{
                        "type": "paragraph",
                        "content": [{"type": "text", "text": f"来自会议：{item['meeting_link']}"}]
                    }]
                }
            }
        }
        
        response = requests.post(
            f"{jira_config['base_url']}/rest/api/3/issue",
            json=payload,
            headers=headers
        )
        print(f"Created: {response.json().get('key')} - {item['task']}")
```

---

## AI-Assisted Meeting Notes Workflow

### Step-by-Step with AI

```
1. 录音/转录 → Otter.ai / 飞书妙记 / Zoom AI Summary

2. 粘贴转录文本，使用此 Prompt：
   "请将以下会议转录整理为结构化纪要，
    包含：核心决议3-5条、行动项表格（含负责人/截止/优先级）、
    待确认问题列表。语言：中文。"

3. 检查并补充遗漏项

4. 发送给参会人确认（24小时内）

5. 将行动项同步到项目管理工具
```

---

## Meeting Notes Quality Checklist

发送前自查：
- [ ] 每个行动项都有明确负责人
- [ ] 每个行动项都有截止日期（或标注TBD+原因）
- [ ] 核心决议已用粗体/标注突出
- [ ] 参会人姓名无错别字
- [ ] 文档权限已设置（参会人可访问）
- [ ] 已在48小时内发送
- [ ] 下次会议时间已确认并发出邀请

FILE:references/templates-cn.md
# 会议纪要模板集合（中文）

## 模板1：日常项目例会

```markdown
# 项目例会纪要

**项目名称：** _______________
**会议时间：** YYYY年MM月DD日 HH:MM-HH:MM
**会议地点/方式：** □线下 □腾讯会议 □飞书 □钉钉
**参会人员：** 
**缺席人员：** 
**主持人：** 
**记录人：** 

---

### 上次行动项跟进

| 任务 | 负责人 | 原截止日期 | 状态 | 备注 |
|------|--------|------------|------|------|
| | | | □完成 □延期 □取消 | |

---

### 本次议题

**1. [议题1]**
- 讨论内容：
- 结论/决定：
- 遗留问题：

**2. [议题2]**
- 讨论内容：
- 结论/决定：
- 遗留问题：

---

### 行动项汇总

| 序号 | 任务描述 | 负责人 | 截止日期 | 优先级 |
|------|----------|--------|----------|--------|
| 1 | | | | P0/P1/P2 |
| 2 | | | | |

---

### 下次例会

**时间：** _______________
**预计议题：** _______________
```

---

## 模板2：需求评审会

```markdown
# 需求评审会纪要

**需求名称：** _______________
**产品负责人：** _______________
**评审日期：** _______________

### 需求概述
[1-2句话描述需求背景和目标]

### 评审意见汇总

| 模块 | 评审意见 | 提出人 | 处理方式 | 状态 |
|------|----------|--------|----------|------|
| | | | □接受 □拒绝 □待讨论 | |

### 技术风险点
1. [风险描述] — 影响程度：高/中/低 — 应对方案：
2.

### 评审结论
□ 通过，可进入开发
□ 有条件通过（需解决以下问题）：
□ 不通过，需重新评审

### 修改要求（如不通过）
1.
2.
```

---

## 模板3：复盘会议

```markdown
# 项目复盘会议纪要

**复盘项目/Sprint：** _______________
**时间范围：** _______________至_______________
**参会人：** _______________

---

### 数据回顾

| 指标 | 目标 | 实际 | 差异 |
|------|------|------|------|
| | | | |

---

### 做得好的地方（Keep）
1.
2.
3.

### 需要改进的地方（Improve）
1.
2.
3.

### 下次尝试的事（Try）
1.
2.

---

### 改进行动项

| 改进点 | 具体行动 | 负责人 | 下个周期验收标准 |
|--------|----------|--------|-----------------|
| | | | |
```

---

## 快捷标记符号

- ✅ 已完成 / 已确认
- 🔴 高优先级 / 阻塞问题
- 🟡 中优先级 / 待确认
- 🟢 低优先级 / 信息同步
- ❓ 待讨论 / 需澄清
- 📌 重要决定
- 📎 参考资料链接
- ⏰ 时间敏感

ClawHub Automation Project Management+2

H@clawhub-goldath-0656adbb74

Short Video Filming Preparation Checklist

Skill

Generates tailored pre-shoot checklists covering equipment, location, talent, wardrobe, and contingency plans for video shoot preparation.

# Short Video Filming Preparation Checklist

A comprehensive pre-shoot checklist covering equipment, location, talent, wardrobe, props, permissions, and contingency planning.

## Target Users

- Content creators
- Video production teams
- Solo shooters
- Agency producers

## When to Use

- Preparing for any video shoot day
- Avoiding forgotten equipment or props
- Managing multi-location shoots
- Onboarding new production team members

## Core Workflow

1. Pre-shoot planning
2. Equipment checklist
3. Location checklist
4. Talent & wardrobe checklist
5. Shot-day run sheet template
6. Contingency planning

## Inputs

- Shoot type
- Location details
- Equipment inventory
- Talent details
- Expected duration

## Expected Outputs

- Customized pre-shoot checklist
- Equipment packing list
- Location scout notes template
- Contingency plan template

## Example Prompts

- "Create a filming day checklist for a solo creator shooting a cooking video at home."
- "Build a pre-shoot checklist for an outdoor brand video with two locations and one talent."
- "What's in a complete equipment packing list for a travel vlog shoot?"

## Trigger Keywords

filming checklist, shoot prep, video preparation, shoot day, equipment checklist, pre-shoot

## Safety & Limitations

Checklists are organizational aids. Does not guarantee shoot success or cover all possible contingencies. Location safety, permits, and insurance are the user's responsibility.

---

*Generated for project short-video-skills-2026-04-27*

FILE:skill.json
{
  "slug": "sv-filming-checklist",
  "name": "Short Video Filming Preparation Checklist",
  "description": "A comprehensive pre-shoot checklist covering equipment, location, talent, wardrobe, props, permissions, and contingency planning.",
  "type": "descriptive",
  "requires_api": false,
  "readiness": "stable",
  "tags": [
    "video",
    "checklist",
    "preparation",
    "filming",
    "production",
    "descriptive"
  ],
  "trigger_keywords": [
    "filming checklist",
    "shoot prep",
    "video preparation",
    "shoot day",
    "equipment checklist",
    "pre-shoot"
  ],
  "max_files": 4,
  "language": "en",
  "safety": "document-only informational guidance"
}

FILE:README.md
# Short Video Filming Preparation Checklist

A comprehensive pre-shoot checklist covering equipment, location, talent, wardrobe, props, permissions, and contingency planning.

## Target Users

- Content creators
- Video production teams
- Solo shooters
- Agency producers

## When to Use

- Preparing for any video shoot day
- Avoiding forgotten equipment or props
- Managing multi-location shoots
- Onboarding new production team members

## Trigger Keywords

filming checklist, shoot prep, video preparation, shoot day, equipment checklist, pre-shoot

## Full Documentation

See [SKILL.md](./SKILL.md) for complete workflow, inputs, outputs, and examples.

---

*Generated for project short-video-skills-2026-04-27*

FILE:ACCEPTANCE.md
# Acceptance Checklist — Short Video Filming Preparation Checklist

## Criteria

- [x] Document-only: no handler.py, scripts, APIs, or executable code
- [x] No network calls or credential handling
- [x] English-first documentation
- [x] File count ≤ 10 (target: exactly 4)
- [x] Includes safety disclaimer
- [x] skill.json is valid with `requires_api: false`
- [x] No drift from design-spec.md

## Files in This Skill

1. `SKILL.md` — Full workflow, inputs, outputs, examples, safety
2. `README.md` — Quick-start reference
3. `skill.json` — Machine-readable metadata
4. `ACCEPTANCE.md` — This checklist

## Verification Commands

```bash
# Count files in this directory
find /Users/jianghaidong/.openclaw/skills/sv-filming-checklist -type f | wc -l
# Expected: 4

# Verify skill.json
cat /Users/jianghaidong/.openclaw/skills/sv-filming-checklist/skill.json | grep requires_api
# Expected: "requires_api": false

# Verify no code files
find /Users/jianghaidong/.openclaw/skills/sv-filming-checklist -name "*.py" -o -name "*.sh" | wc -l
# Expected: 0
```

---

*Generated for project short-video-skills-2026-04-27*

ClawHub Automation Documentation+2

H@clawhub-harrylabsj-35a31b2850

Short Video Lighting Setup Guide

Skill

Provides tailored lighting setup plans and tips for short video shooting using natural or artificial light across all budget levels.

# Short Video Lighting Setup Guide

Provides lighting setup plans — natural and artificial — for short video shooting scenarios from zero-budget to professional.

## Target Users

- Content creators
- Solo shooters
- Home studio operators
- Beginner videographers

## When to Use

- Setting up a home video studio
- Solving common lighting problems
- Planning lighting for different content types
- Working with limited or no equipment

## Core Workflow

1. Lighting scenario assessment
2. Three-point lighting adaptation for short video
3. Natural light optimization
4. Budget-tier lighting setups (ring light, softbox, practical lamps, DIY)
5. Content-type-specific lighting
6. Common lighting mistakes and fixes

## Inputs

- Shooting environment description
- Equipment inventory
- Content type
- Desired mood/look
- Budget level

## Expected Outputs

- Lighting setup plan with diagram description
- Equipment recommendations by tier
- Natural-light schedule
- Troubleshooting checklist

## Example Prompts

- "I shoot talking-head videos in my bedroom with one window — help me set up lighting."
- "Design a lighting plan for a product showcase video shot on a desk — budget under 200 RMB."
- "What's the best lighting approach for outdoor short videos on an overcast day?"

## Trigger Keywords

video lighting, lighting setup, ring light, three-point lighting, natural light video, filming lighting

## Safety & Limitations

Lighting guidance is educational. Does not control lighting equipment. Users should follow electrical safety rules. Heat from continuous lights should be managed carefully.

---

*Generated for project short-video-skills-2026-04-27*

FILE:skill.json
{
  "slug": "sv-lighting-setup",
  "name": "Short Video Lighting Setup Guide",
  "description": "Provides lighting setup plans — natural and artificial — for short video shooting scenarios from zero-budget to professional.",
  "type": "descriptive",
  "requires_api": false,
  "readiness": "stable",
  "tags": [
    "video",
    "lighting",
    "setup",
    "filming",
    "production",
    "descriptive"
  ],
  "trigger_keywords": [
    "video lighting",
    "lighting setup",
    "ring light",
    "three-point lighting",
    "natural light video",
    "filming lighting"
  ],
  "max_files": 4,
  "language": "en",
  "safety": "document-only informational guidance"
}

FILE:README.md
# Short Video Lighting Setup Guide

Provides lighting setup plans — natural and artificial — for short video shooting scenarios from zero-budget to professional.

## Target Users

- Content creators
- Solo shooters
- Home studio operators
- Beginner videographers

## When to Use

- Setting up a home video studio
- Solving common lighting problems
- Planning lighting for different content types
- Working with limited or no equipment

## Trigger Keywords

video lighting, lighting setup, ring light, three-point lighting, natural light video, filming lighting

## Full Documentation

See [SKILL.md](./SKILL.md) for complete workflow, inputs, outputs, and examples.

---

*Generated for project short-video-skills-2026-04-27*

FILE:ACCEPTANCE.md
# Acceptance Checklist — Short Video Lighting Setup Guide

## Criteria

- [x] Document-only: no handler.py, scripts, APIs, or executable code
- [x] No network calls or credential handling
- [x] English-first documentation
- [x] File count ≤ 10 (target: exactly 4)
- [x] Includes safety disclaimer
- [x] skill.json is valid with `requires_api: false`
- [x] No drift from design-spec.md

## Files in This Skill

1. `SKILL.md` — Full workflow, inputs, outputs, examples, safety
2. `README.md` — Quick-start reference
3. `skill.json` — Machine-readable metadata
4. `ACCEPTANCE.md` — This checklist

## Verification Commands

```bash
# Count files in this directory
find /Users/jianghaidong/.openclaw/skills/sv-lighting-setup -type f | wc -l
# Expected: 4

# Verify skill.json
cat /Users/jianghaidong/.openclaw/skills/sv-lighting-setup/skill.json | grep requires_api
# Expected: "requires_api": false

# Verify no code files
find /Users/jianghaidong/.openclaw/skills/sv-lighting-setup -name "*.py" -o -name "*.sh" | wc -l
# Expected: 0
```

---

*Generated for project short-video-skills-2026-04-27*

ClawHub Product Automation+2

H@clawhub-harrylabsj-35a31b2850

Short Video Shot Composition Guide

Skill

Provides tailored shot composition advice for vertical short videos, covering framing, angles, depth, camera movement, and smartphone setup tips.

# Short Video Shot Composition Guide

Teaches and applies shot composition principles — framing, angles, depth, and movement — specifically optimized for vertical short video formats.

## Target Users

- Beginner to intermediate videographers
- Content creators
- Smartphone shooters
- Solo creators

## When to Use

- Planning camera setups for a shoot
- Improving visual quality of existing content
- Learning composition fundamentals for vertical video
- Preparing multi-camera or multi-angle shoots

## Core Workflow

1. Aspect ratio & safe zone awareness (9:16, 1:1, 16:9)
2. Composition rule selection (rule of thirds, center framing, headroom, leading lines, symmetry, negative space)
3. Shot size & angle guide
4. Depth and layering (foreground, midground, background)
5. Camera movement dos and don'ts
6. Smartphone-specific tips

## Inputs

- Shooting environment description
- Available equipment
- Content type
- Desired visual style

## Expected Outputs

- Per-shot composition recommendations
- Framing diagrams (described textually)
- Equipment setup notes
- Common mistake avoidance checklist

## Example Prompts

- "I shoot cooking videos with my phone in a small kitchen — how should I compose my shots?"
- "Guide me through shot composition for a talking-head educational video in vertical format."
- "What composition rules should I follow for a fashion lookbook short video?"

## Trigger Keywords

shot composition, video framing, camera angles, vertical video, filming guide, composition rules

## Safety & Limitations

Composition guidance is educational. Does not control or operate camera equipment. Users should follow safety precautions when setting up equipment.

---

*Generated for project short-video-skills-2026-04-27*

FILE:skill.json
{
  "slug": "sv-shot-composition",
  "name": "Short Video Shot Composition Guide",
  "description": "Teaches and applies shot composition principles — framing, angles, depth, and movement — specifically optimized for vertical short video formats.",
  "type": "descriptive",
  "requires_api": false,
  "readiness": "stable",
  "tags": [
    "video",
    "composition",
    "framing",
    "camera",
    "shooting",
    "descriptive"
  ],
  "trigger_keywords": [
    "shot composition",
    "video framing",
    "camera angles",
    "vertical video",
    "filming guide",
    "composition rules"
  ],
  "max_files": 4,
  "language": "en",
  "safety": "document-only informational guidance"
}

FILE:README.md
# Short Video Shot Composition Guide

Teaches and applies shot composition principles — framing, angles, depth, and movement — specifically optimized for vertical short video formats.

## Target Users

- Beginner to intermediate videographers
- Content creators
- Smartphone shooters
- Solo creators

## When to Use

- Planning camera setups for a shoot
- Improving visual quality of existing content
- Learning composition fundamentals for vertical video
- Preparing multi-camera or multi-angle shoots

## Trigger Keywords

shot composition, video framing, camera angles, vertical video, filming guide, composition rules

## Full Documentation

See [SKILL.md](./SKILL.md) for complete workflow, inputs, outputs, and examples.

---

*Generated for project short-video-skills-2026-04-27*

FILE:ACCEPTANCE.md
# Acceptance Checklist — Short Video Shot Composition Guide

## Criteria

- [x] Document-only: no handler.py, scripts, APIs, or executable code
- [x] No network calls or credential handling
- [x] English-first documentation
- [x] File count ≤ 10 (target: exactly 4)
- [x] Includes safety disclaimer
- [x] skill.json is valid with `requires_api: false`
- [x] No drift from design-spec.md

## Files in This Skill

1. `SKILL.md` — Full workflow, inputs, outputs, examples, safety
2. `README.md` — Quick-start reference
3. `skill.json` — Machine-readable metadata
4. `ACCEPTANCE.md` — This checklist

## Verification Commands

```bash
# Count files in this directory
find /Users/jianghaidong/.openclaw/skills/sv-shot-composition -type f | wc -l
# Expected: 4

# Verify skill.json
cat /Users/jianghaidong/.openclaw/skills/sv-shot-composition/skill.json | grep requires_api
# Expected: "requires_api": false

# Verify no code files
find /Users/jianghaidong/.openclaw/skills/sv-shot-composition -name "*.py" -o -name "*.sh" | wc -l
# Expected: 0
```

---

*Generated for project short-video-skills-2026-04-27*

ClawHub Design Automation+2

H@clawhub-harrylabsj-35a31b2850

Short Video Content Calendar Planner

Skill

Plans and structures short video posting schedules, themes, and production timelines for creators and marketing teams across platforms.

# Short Video Content Calendar Planner

Helps creators plan and structure posting schedules, content themes, and production timelines for short video series.

## Target Users

- Content creators
- Social media managers
- Marketing teams
- Multi-platform publishers

## When to Use

- Planning a monthly/weekly content pipeline
- Aligning content with seasonal events or product launches
- Balancing content mix across formats

## Core Workflow

1. Time horizon & cadence definition
2. Content pillar / theme mapping
3. Production timeline back-planning
4. Platform-specific posting time optimization
5. Content mix balance check

## Inputs

- Publishing goals
- Content pillars
- Available production days
- Key dates/events
- Platform preferences

## Expected Outputs

- Content calendar template
- Weekly/monthly posting grid
- Production milestone schedule
- Content mix ratio recommendations

## Example Prompts

- "Help me plan a 30-day content calendar for a tech review channel posting daily on Douyin."
- "Build a weekly content mix for a fitness brand covering tutorial, motivation, and product content."
- "Align my content calendar with upcoming e-commerce shopping festivals in Q2."

## Trigger Keywords

content calendar, posting schedule, video planning, content timeline, content mix, video cadence

## Safety & Limitations

Scheduling recommendations are guidelines, not guarantees of optimal performance. Platform algorithms change; users should validate timing with their own analytics.

---

*Generated for project short-video-skills-2026-04-27*

FILE:skill.json
{
  "slug": "sv-content-calendar",
  "name": "Short Video Content Calendar Planner",
  "description": "Helps creators plan and structure posting schedules, content themes, and production timelines for short video series.",
  "type": "descriptive",
  "requires_api": false,
  "readiness": "stable",
  "tags": [
    "video",
    "planning",
    "calendar",
    "scheduling",
    "strategy",
    "descriptive"
  ],
  "trigger_keywords": [
    "content calendar",
    "posting schedule",
    "video planning",
    "content timeline",
    "content mix",
    "video cadence"
  ],
  "max_files": 4,
  "language": "en",
  "safety": "document-only informational guidance"
}

FILE:README.md
# Short Video Content Calendar Planner

Helps creators plan and structure posting schedules, content themes, and production timelines for short video series.

## Target Users

- Content creators
- Social media managers
- Marketing teams
- Multi-platform publishers

## When to Use

- Planning a monthly/weekly content pipeline
- Aligning content with seasonal events or product launches
- Balancing content mix across formats

## Trigger Keywords

content calendar, posting schedule, video planning, content timeline, content mix, video cadence

## Full Documentation

See [SKILL.md](./SKILL.md) for complete workflow, inputs, outputs, and examples.

---

*Generated for project short-video-skills-2026-04-27*

FILE:ACCEPTANCE.md
# Acceptance Checklist — Short Video Content Calendar Planner

## Criteria

- [x] Document-only: no handler.py, scripts, APIs, or executable code
- [x] No network calls or credential handling
- [x] English-first documentation
- [x] File count ≤ 10 (target: exactly 4)
- [x] Includes safety disclaimer
- [x] skill.json is valid with `requires_api: false`
- [x] No drift from design-spec.md

## Files in This Skill

1. `SKILL.md` — Full workflow, inputs, outputs, examples, safety
2. `README.md` — Quick-start reference
3. `skill.json` — Machine-readable metadata
4. `ACCEPTANCE.md` — This checklist

## Verification Commands

```bash
# Count files in this directory
find /Users/jianghaidong/.openclaw/skills/sv-content-calendar -type f | wc -l
# Expected: 4

# Verify skill.json
cat /Users/jianghaidong/.openclaw/skills/sv-content-calendar/skill.json | grep requires_api
# Expected: "requires_api": false

# Verify no code files
find /Users/jianghaidong/.openclaw/skills/sv-content-calendar -name "*.py" -o -name "*.sh" | wc -l
# Expected: 0
```

---

*Generated for project short-video-skills-2026-04-27*

ClawHub Marketing Documentation+2

H@clawhub-harrylabsj-35a31b2850

Legal Law Firm Ops Dashboard

Skill

Provides structured dashboards and checklists for law firm matter status, workload, deadlines, billing hygiene, client communication, and risk monitoring.

---
slug: legal-law-firm-ops-dashboard
version: "1.0.0"
type: descriptive
language: en
---

# Legal Law Firm Ops Dashboard

## Overview

Designs descriptive dashboards for law firm matter status, workload, deadlines, billing hygiene, client communication, and risk flags. This is a descriptive OpenClaw skill for legal-industry workflow support. It provides structured frameworks, checklists, templates, and issue-spotting prompts. It does not execute code, call external APIs, access legal databases, retrieve court records, automate filings, or perform legal services.

## When to Use

- Improving matter visibility
- Creating weekly practice reports
- Standardizing operational review meetings

## Target Users

- Law firm managers
- Practice group leaders
- Legal operations professionals
- Managing partners

## Inputs to Collect

- Matter or project context, including jurisdiction if known
- Relevant facts, documents, parties, dates, and constraints
- Desired output format, audience, and level of detail
- Known deadlines, risk concerns, or review priorities

## Core Modules

1. **Matter status fields** — provides structured prompts, checklists, and review fields for this area.
2. **Workload and deadline indicators** — provides structured prompts, checklists, and review fields for this area.
3. **Billing and WIP hygiene prompts** — provides structured prompts, checklists, and review fields for this area.
4. **Client communication cadence tracker** — provides structured prompts, checklists, and review fields for this area.
5. **Risk escalation dashboard** — provides structured prompts, checklists, and review fields for this area.

## Workflow

1. Confirm the user's legal workflow goal and the relevant practice context.
2. Ask for missing facts, documents, dates, parties, jurisdiction, and audience where needed.
3. Apply the modules below as a structured thinking framework.
4. Produce checklists, templates, matrices, memos, or planning aids tailored to the user's context.
5. Flag uncertainty, verification needs, deadlines, ethics concerns, confidentiality issues, and attorney-review points.

## Expected Outputs

- Dashboard field list
- Weekly report template
- Risk flag definitions
- Meeting agenda

## Example Prompts

- "Design a weekly litigation practice dashboard."
- "Create a law firm matter status dashboard template."

## Safety and Legal Limitations

- This skill provides informational workflow support only and is not legal advice.
- It does not create an attorney-client relationship and does not replace review by a qualified attorney.
- Laws, court rules, deadlines, ethics duties, privilege, confidentiality, and professional responsibility rules vary by jurisdiction and matter.
- Users must verify all legal authorities, filing requirements, deadlines, facts, citations, and strategic decisions with qualified counsel.
- The skill must not be used to fabricate evidence, coach false testimony, evade regulation, access data unlawfully, or bypass confidentiality obligations.
- Specific limitation for this skill: Operational guidance only; does not access billing systems or client data automatically.

## Acceptance Criteria

- Package is descriptive only: no handler.py, scripts, external APIs, network calls, or command execution.
- SKILL.md and README.md are English-first and include an explicit legal-information disclaimer.
- Outputs are frameworks, checklists, templates, or planning aids rather than legal conclusions.
- Includes target users, when-to-use guidance, inputs, workflow, outputs, examples, and safety limitations.
- skill.json contains unique slug, tags, trigger keywords, requires_api=false, and readiness=stable.

FILE:ACCEPTANCE.md
# Acceptance Criteria

1. Package is descriptive only: no handler.py, scripts, external APIs, network calls, or command execution.
2. SKILL.md and README.md are English-first and include an explicit legal-information disclaimer.
3. Outputs are frameworks, checklists, templates, or planning aids rather than legal conclusions.
4. Includes target users, when-to-use guidance, inputs, workflow, outputs, examples, and safety limitations.
5. skill.json contains unique slug, tags, trigger keywords, requires_api=false, and readiness=stable.

## Package Rules

- Allowed files: SKILL.md, README.md, skill.json, ACCEPTANCE.md.
- Forbidden files: handler.py, scripts, tests, binaries, credentials, generated caches, or workspace artifacts.
- The package must remain descriptive-only and English-first.

FILE:README.md
# Legal Law Firm Ops Dashboard

Designs descriptive dashboards for law firm matter status, workload, deadlines, billing hygiene, client communication, and risk flags.

## What This Skill Does

This document-only legal workflow skill helps users structure their thinking and deliverables using checklists, templates, matrices, and planning prompts. It is designed for lawyers, legal operations teams, paralegals, and adjacent professionals who need repeatable workflows without code execution.

## Core Modules

- Matter status fields
- Workload and deadline indicators
- Billing and WIP hygiene prompts
- Client communication cadence tracker
- Risk escalation dashboard

## Trigger Keywords

law firm dashboard, matter status report, legal operations, billing hygiene, legal-law-firm-ops-dashboard, legal law firm ops dashboard

## Example Prompts

- "Design a weekly litigation practice dashboard."
- "Create a law firm matter status dashboard template."

## Outputs

- Dashboard field list
- Weekly report template
- Risk flag definitions
- Meeting agenda

## Safety

Informational support only. Not legal advice. Does not replace qualified attorney review, jurisdiction-specific research, ethics analysis, or professional judgment.

FILE:skill.json
{
"name": "Legal Law Firm Ops Dashboard",
"slug": "legal-law-firm-ops-dashboard",
"version": "1.0.0",
"description": "Designs descriptive dashboards for law firm matter status, workload, deadlines, billing hygiene, client communication, and risk flags.",
"author": "Pearl Team (OpenClaw)",
"tags": [
"legal",
"law-firm",
"legal-ops",
"dashboard",
"descriptive"
],
"trigger_keywords": [
"law firm dashboard",
"matter status report",
"legal operations",
"billing hygiene",
"legal-law-firm-ops-dashboard",
"legal law firm ops dashboard"
],
"language": "en",
"outputs": "markdown",
"requires_api": false,
"readiness": "stable",
"type": "descriptive",
"legal_disclaimer": "Informational workflow support only; not legal advice."
}

ClawHub Data Analysis Research+2

H@clawhub-harrylabsj-35a31b2850

Legal Settlement Evaluation Framework

Skill

Provides structured checklists and templates to evaluate legal settlement options considering exposure, evidence, costs, timing, and non-monetary terms.

---
slug: legal-settlement-evaluation-framework
version: "1.0.0"
type: descriptive
language: en
---

# Legal Settlement Evaluation Framework

## Overview

Helps evaluate settlement options using exposure, evidence strength, litigation cost, non-monetary terms, timing, and uncertainty. This is a descriptive OpenClaw skill for legal-industry workflow support. It provides structured frameworks, checklists, templates, and issue-spotting prompts. It does not execute code, call external APIs, access legal databases, retrieve court records, automate filings, or perform legal services.

## When to Use

- Assessing settlement offers
- Preparing client recommendation memos
- Comparing litigation versus resolution options

## Target Users

- Litigators
- In-house counsel
- Claims teams
- Business stakeholders

## Inputs to Collect

## Core Modules

1. **Exposure and damages range table** — provides structured prompts, checklists, and review fields for this area.
2. **Evidence strength factors** — provides structured prompts, checklists, and review fields for this area.
3. **Cost/time/risk comparison** — provides structured prompts, checklists, and review fields for this area.
4. **Non-monetary term checklist** — provides structured prompts, checklists, and review fields for this area.
5. **Decision memo template** — provides structured prompts, checklists, and review fields for this area.

## Workflow

## Expected Outputs

- Settlement evaluation matrix
- Risk-adjusted comparison
- Client recommendation outline
- Open issues list

## Example Prompts

- "Build a settlement evaluation matrix for a contract dispute."
- "Help compare accepting an offer versus continuing litigation."

## Safety and Legal Limitations

- This skill provides informational workflow support only and is not legal advice.
- It does not create an attorney-client relationship and does not replace review by a qualified attorney.
- Laws, court rules, deadlines, ethics duties, privilege, confidentiality, and professional responsibility rules vary by jurisdiction and matter.
- Users must verify all legal authorities, filing requirements, deadlines, facts, citations, and strategic decisions with qualified counsel.
- The skill must not be used to fabricate evidence, coach false testimony, evade regulation, access data unlawfully, or bypass confidentiality obligations.
- Specific limitation for this skill: Does not predict court outcomes or advise acceptance; final settlement decisions require attorney-client analysis.

## Acceptance Criteria

FILE:ACCEPTANCE.md
# Acceptance Criteria

## Package Rules

FILE:README.md
# Legal Settlement Evaluation Framework

Helps evaluate settlement options using exposure, evidence strength, litigation cost, non-monetary terms, timing, and uncertainty.

## What This Skill Does

## Core Modules

- Exposure and damages range table
- Evidence strength factors
- Cost/time/risk comparison
- Non-monetary term checklist
- Decision memo template

## Trigger Keywords

settlement evaluation, litigation exposure, settlement matrix, case risk, legal-settlement-evaluation-framework, legal settlement evaluation framework

## Example Prompts

- "Build a settlement evaluation matrix for a contract dispute."
- "Help compare accepting an offer versus continuing litigation."

## Outputs

- Settlement evaluation matrix
- Risk-adjusted comparison
- Client recommendation outline
- Open issues list

## Safety

Informational support only. Not legal advice. Does not replace qualified attorney review, jurisdiction-specific research, ethics analysis, or professional judgment.

FILE:skill.json
{
"name": "Legal Settlement Evaluation Framework",
"slug": "legal-settlement-evaluation-framework",
"version": "1.0.0",
"description": "Helps evaluate settlement options using exposure, evidence strength, litigation cost, non-monetary terms, timing, and uncertainty.",
"author": "Pearl Team (OpenClaw)",
"tags": [
"legal",
"settlement",
"litigation",
"risk",
"descriptive"
],
"trigger_keywords": [
"settlement evaluation",
"litigation exposure",
"settlement matrix",
"case risk",
"legal-settlement-evaluation-framework",
"legal settlement evaluation framework"
],
"language": "en",
"outputs": "markdown",
"requires_api": false,
"readiness": "stable",
"type": "descriptive",
"legal_disclaimer": "Informational workflow support only; not legal advice."
}

ClawHub Data Analysis Research+2

H@clawhub-harrylabsj-35a31b2850

Legal Employment Policy Reviewer

Skill

Provides structured checklists and templates to support legal review of employee handbooks, HR policies, and employment risk areas by qualified professionals.

---
slug: legal-employment-policy-reviewer
version: "1.0.0"
type: descriptive
language: en
---

# Legal Employment Policy Reviewer

## Overview

Provides a structured framework for reviewing employee handbooks, workplace policies, HR procedures, and employment risk areas. This is a descriptive OpenClaw skill for legal-industry workflow support. It provides structured frameworks, checklists, templates, and issue-spotting prompts. It does not execute code, call external APIs, access legal databases, retrieve court records, automate filings, or perform legal services.

## When to Use

- Reviewing employee handbook updates
- Preparing HR policy audits
- Spotting employment-law risk areas

## Target Users

- Employment lawyers
- HR legal teams
- People operations leaders
- Compliance teams

## Inputs to Collect

## Core Modules

1. **Policy inventory checklist** — provides structured prompts, checklists, and review fields for this area.
2. **Jurisdiction and workforce scope notes** — provides structured prompts, checklists, and review fields for this area.
3. **Required vs optional policy map** — provides structured prompts, checklists, and review fields for this area.
4. **Risk and consistency review** — provides structured prompts, checklists, and review fields for this area.
5. **Employee communication checklist** — provides structured prompts, checklists, and review fields for this area.

## Workflow

## Expected Outputs

- Policy review checklist
- Risk issue log
- Update priority matrix
- Communication plan outline

## Example Prompts

- "Create an employment policy review checklist for a remote workforce."
- "Help audit handbook sections for legal risk areas."

## Safety and Legal Limitations

- This skill provides informational workflow support only and is not legal advice.
- It does not create an attorney-client relationship and does not replace review by a qualified attorney.
- Laws, court rules, deadlines, ethics duties, privilege, confidentiality, and professional responsibility rules vary by jurisdiction and matter.
- Users must verify all legal authorities, filing requirements, deadlines, facts, citations, and strategic decisions with qualified counsel.
- The skill must not be used to fabricate evidence, coach false testimony, evade regulation, access data unlawfully, or bypass confidentiality obligations.
- Specific limitation for this skill: Employment law is jurisdiction-specific; final policies require qualified local counsel review.

## Acceptance Criteria

FILE:ACCEPTANCE.md
# Acceptance Criteria

## Package Rules

FILE:README.md
# Legal Employment Policy Reviewer

Provides a structured framework for reviewing employee handbooks, workplace policies, HR procedures, and employment risk areas.

## What This Skill Does

## Core Modules

- Policy inventory checklist
- Jurisdiction and workforce scope notes
- Required vs optional policy map
- Risk and consistency review
- Employee communication checklist

## Trigger Keywords

employment policy review, employee handbook, HR legal checklist, workplace policy, legal-employment-policy-reviewer, legal employment policy reviewer

## Example Prompts

- "Create an employment policy review checklist for a remote workforce."
- "Help audit handbook sections for legal risk areas."

## Outputs

- Policy review checklist
- Risk issue log
- Update priority matrix
- Communication plan outline

## Safety

Informational support only. Not legal advice. Does not replace qualified attorney review, jurisdiction-specific research, ethics analysis, or professional judgment.

FILE:skill.json
{
"name": "Legal Employment Policy Reviewer",
"slug": "legal-employment-policy-reviewer",
"version": "1.0.0",
"description": "Provides a structured framework for reviewing employee handbooks, workplace policies, HR procedures, and employment risk areas.",
"author": "Pearl Team (OpenClaw)",
"tags": [
"legal",
"employment",
"hr-policy",
"compliance",
"descriptive"
],
"trigger_keywords": [
"employment policy review",
"employee handbook",
"HR legal checklist",
"workplace policy",
"legal-employment-policy-reviewer",
"legal employment policy reviewer"
],
"language": "en",
"outputs": "markdown",
"requires_api": false,
"readiness": "stable",
"type": "descriptive",
"legal_disclaimer": "Informational workflow support only; not legal advice."
}

ClawHub Data Analysis Research+2

H@clawhub-harrylabsj-35a31b2850

Think Block Leakage

Skill

Internal reasoning from <think> blocks leaks into the final user-facing reply instead of being stripped.

---
name: think-block-leakage
description: Internal reasoning from <think> blocks leaks into the final user-facing reply instead of being stripped.
emoji: 🧠
metadata:
  clawdis:
    os: [macos, linux, windows]
---

# think-block-leakage

The model's internal reasoning escapes into the reply the user sees. This usually means an unclosed `<think>` / `<thinking>` tag, or a reply that begins with planning prose instead of the answer itself.

## Symptoms

- Reply contains literal `<think>`, `<thinking>`, or similar reasoning tags.
- Reply opens with "Let me think...", "Okay, the user wants...", "First I'll need to...", or other planning preamble.
- Reply is cut off mid-sentence and an opening reasoning tag has no matching close.
- A `</think>` appears with only a few dozen characters of content after it.

## What to do

- Inspect the raw LLM output for unmatched reasoning tags before returning it. Strip or redact any content inside reasoning tags.
- If the provider supports a separate reasoning channel, emit reasoning there and keep it out of the reply body entirely.
- If leakage is detected, regenerate the reply. Do not ship reasoning-as-answer.
- If the reply starts with planning language, trim the preamble. The user should see the answer first.
- For persistent leakage, tighten the system prompt to forbid meta-commentary in the reply body.

ClawHub AI Agents Content Creation+1

M@clawhub-mvogt99-7d48143016

Legal Due Diligence Checklist

Skill

Generates tailored legal due diligence checklists and templates to support transaction review and risk assessment for corporate and investment professionals.

---
slug: legal-due-diligence-checklist
version: "1.0.0"
type: descriptive
language: en
---

# Legal Due Diligence Checklist

## Overview

Creates legal due diligence checklists for transactions, investments, acquisitions, vendor onboarding, and corporate housekeeping. This is a descriptive OpenClaw skill for legal-industry workflow support. It provides structured frameworks, checklists, templates, and issue-spotting prompts. It does not execute code, call external APIs, access legal databases, retrieve court records, automate filings, or perform legal services.

## When to Use

- Preparing diligence requests
- Reviewing target company documents
- Organizing transaction risk findings

## Target Users

- Corporate attorneys
- M&A teams
- Startup counsel
- Investment teams

## Inputs to Collect

## Core Modules

1. **Corporate records checklist** — provides structured prompts, checklists, and review fields for this area.
2. **Contracts and obligations review** — provides structured prompts, checklists, and review fields for this area.
3. **Employment/IP/compliance review** — provides structured prompts, checklists, and review fields for this area.
4. **Litigation and regulatory search plan** — provides structured prompts, checklists, and review fields for this area.
5. **Red-flag summary template** — provides structured prompts, checklists, and review fields for this area.

## Workflow

## Expected Outputs

- Diligence request list
- Issue tracker
- Red-flag summary
- Document index

## Example Prompts

- "Create a legal due diligence checklist for a small acquisition."
- "Help organize diligence requests for a startup investment."

## Safety and Legal Limitations

- This skill provides informational workflow support only and is not legal advice.
- It does not create an attorney-client relationship and does not replace review by a qualified attorney.
- Laws, court rules, deadlines, ethics duties, privilege, confidentiality, and professional responsibility rules vary by jurisdiction and matter.
- Users must verify all legal authorities, filing requirements, deadlines, facts, citations, and strategic decisions with qualified counsel.
- The skill must not be used to fabricate evidence, coach false testimony, evade regulation, access data unlawfully, or bypass confidentiality obligations.
- Specific limitation for this skill: Framework only; diligence scope must be tailored by transaction counsel and local law experts.

## Acceptance Criteria

FILE:ACCEPTANCE.md
# Acceptance Criteria

## Package Rules

FILE:README.md
# Legal Due Diligence Checklist

Creates legal due diligence checklists for transactions, investments, acquisitions, vendor onboarding, and corporate housekeeping.

## What This Skill Does

## Core Modules

- Corporate records checklist
- Contracts and obligations review
- Employment/IP/compliance review
- Litigation and regulatory search plan
- Red-flag summary template

## Trigger Keywords

legal due diligence, M&A checklist, investment diligence, corporate records, legal-due-diligence-checklist, legal due diligence checklist

## Example Prompts

- "Create a legal due diligence checklist for a small acquisition."
- "Help organize diligence requests for a startup investment."

## Outputs

- Diligence request list
- Issue tracker
- Red-flag summary
- Document index

## Safety

Informational support only. Not legal advice. Does not replace qualified attorney review, jurisdiction-specific research, ethics analysis, or professional judgment.

FILE:skill.json
{
"name": "Legal Due Diligence Checklist",
"slug": "legal-due-diligence-checklist",
"version": "1.0.0",
"description": "Creates legal due diligence checklists for transactions, investments, acquisitions, vendor onboarding, and corporate housekeeping.",
"author": "Pearl Team (OpenClaw)",
"tags": [
"legal",
"due-diligence",
"transactions",
"corporate",
"descriptive"
],
"trigger_keywords": [
"legal due diligence",
"M&A checklist",
"investment diligence",
"corporate records",
"legal-due-diligence-checklist",
"legal due diligence checklist"
],
"language": "en",
"outputs": "markdown",
"requires_api": false,
"readiness": "stable",
"type": "descriptive",
"legal_disclaimer": "Informational workflow support only; not legal advice."
}

ClawHub Data Analysis Research+2

H@clawhub-harrylabsj-35a31b2850

Legal Case Strategy Memo Builder

Skill

Provides structured frameworks and templates to build legal case strategy memos focusing on facts, issues, claims, defenses, risks, and next steps.

---
slug: legal-case-strategy-memo-builder
version: "1.0.0"
type: descriptive
language: en
---

# Legal Case Strategy Memo Builder

## Overview

Structures case strategy memos around facts, issues, claims, defenses, strengths, weaknesses, risks, and next actions. This is a descriptive OpenClaw skill for legal-industry workflow support. It provides structured frameworks, checklists, templates, and issue-spotting prompts. It does not execute code, call external APIs, access legal databases, retrieve court records, automate filings, or perform legal services.

## When to Use

- Preparing internal case assessments
- Updating clients or supervisors
- Deciding litigation strategy

## Target Users

- Attorneys
- Legal teams
- Law firm partners
- In-house litigation managers

## Inputs to Collect

## Core Modules

1. **Fact and issue summary** — provides structured prompts, checklists, and review fields for this area.
2. **Claims/defenses map** — provides structured prompts, checklists, and review fields for this area.
3. **Strengths and weaknesses analysis** — provides structured prompts, checklists, and review fields for this area.
4. **Risk and cost considerations** — provides structured prompts, checklists, and review fields for this area.
5. **Recommended next actions** — provides structured prompts, checklists, and review fields for this area.

## Workflow

## Expected Outputs

- Strategy memo outline
- Risk matrix
- Action plan
- Client update skeleton

## Example Prompts

- "Build a case strategy memo template for a commercial dispute."
- "Help structure a litigation risk assessment for management."

## Safety and Legal Limitations

- This skill provides informational workflow support only and is not legal advice.
- It does not create an attorney-client relationship and does not replace review by a qualified attorney.
- Laws, court rules, deadlines, ethics duties, privilege, confidentiality, and professional responsibility rules vary by jurisdiction and matter.
- Users must verify all legal authorities, filing requirements, deadlines, facts, citations, and strategic decisions with qualified counsel.
- The skill must not be used to fabricate evidence, coach false testimony, evade regulation, access data unlawfully, or bypass confidentiality obligations.
- Specific limitation for this skill: Does not predict outcomes with certainty; strategic decisions require attorney judgment and current law review.

## Acceptance Criteria

FILE:ACCEPTANCE.md
# Acceptance Criteria

## Package Rules

FILE:README.md
# Legal Case Strategy Memo Builder

Structures case strategy memos around facts, issues, claims, defenses, strengths, weaknesses, risks, and next actions.

## What This Skill Does

## Core Modules

- Fact and issue summary
- Claims/defenses map
- Strengths and weaknesses analysis
- Risk and cost considerations
- Recommended next actions

## Trigger Keywords

case strategy memo, litigation risk assessment, claims defenses, legal memo, legal-case-strategy-memo-builder, legal case strategy memo builder

## Example Prompts

- "Build a case strategy memo template for a commercial dispute."
- "Help structure a litigation risk assessment for management."

## Outputs

- Strategy memo outline
- Risk matrix
- Action plan
- Client update skeleton

## Safety

Informational support only. Not legal advice. Does not replace qualified attorney review, jurisdiction-specific research, ethics analysis, or professional judgment.

FILE:skill.json
{
"name": "Legal Case Strategy Memo Builder",
"slug": "legal-case-strategy-memo-builder",
"version": "1.0.0",
"description": "Structures case strategy memos around facts, issues, claims, defenses, strengths, weaknesses, risks, and next actions.",
"author": "Pearl Team (OpenClaw)",
"tags": [
"legal",
"case-strategy",
"litigation",
"memo",
"descriptive"
],
"trigger_keywords": [
"case strategy memo",
"litigation risk assessment",
"claims defenses",
"legal memo",
"legal-case-strategy-memo-builder",
"legal case strategy memo builder"
],
"language": "en",
"outputs": "markdown",
"requires_api": false,
"readiness": "stable",
"type": "descriptive",
"legal_disclaimer": "Informational workflow support only; not legal advice."
}

ClawHub Data Analysis Research+2

H@clawhub-harrylabsj-35a31b2850

Legal Trial Preparation Checklist

Skill

Provides structured checklists and planning aids to support trial readiness for exhibits, witnesses, motions, logistics, and daily courtroom workflow managem...

---
slug: legal-trial-preparation-checklist
version: "1.0.0"
type: descriptive
language: en
---

# Legal Trial Preparation Checklist

## Overview

Provides trial readiness checklists for exhibits, witnesses, motions, openings, closings, logistics, and daily courtroom workflow. This is a descriptive OpenClaw skill for legal-industry workflow support. It provides structured frameworks, checklists, templates, and issue-spotting prompts. It does not execute code, call external APIs, access legal databases, retrieve court records, automate filings, or perform legal services.

## When to Use

- Preparing for trial
- Running pretrial readiness checks
- Coordinating courtroom logistics

## Target Users

- Trial lawyers
- Paralegals
- Litigation support teams

## Inputs to Collect

## Core Modules

1. **Trial calendar and milestone checklist** — provides structured prompts, checklists, and review fields for this area.
2. **Exhibit and witness readiness** — provides structured prompts, checklists, and review fields for this area.
3. **Motions and orders tracker** — provides structured prompts, checklists, and review fields for this area.
4. **Courtroom logistics list** — provides structured prompts, checklists, and review fields for this area.
5. **Daily trial notebook structure** — provides structured prompts, checklists, and review fields for this area.

## Workflow

## Expected Outputs

- Trial readiness checklist
- Trial notebook outline
- Logistics tracker
- Witness/exhibit status table

## Example Prompts

- "Create a 30-day trial preparation checklist."
- "Help me organize a trial notebook for a commercial dispute."

## Safety and Legal Limitations

- This skill provides informational workflow support only and is not legal advice.
- It does not create an attorney-client relationship and does not replace review by a qualified attorney.
- Laws, court rules, deadlines, ethics duties, privilege, confidentiality, and professional responsibility rules vary by jurisdiction and matter.
- Users must verify all legal authorities, filing requirements, deadlines, facts, citations, and strategic decisions with qualified counsel.
- The skill must not be used to fabricate evidence, coach false testimony, evade regulation, access data unlawfully, or bypass confidentiality obligations.
- Specific limitation for this skill: Court rules, judge-specific procedures, and evidentiary rulings must be verified by the legal team.

## Acceptance Criteria

FILE:ACCEPTANCE.md
# Acceptance Criteria

## Package Rules

FILE:README.md
# Legal Trial Preparation Checklist

Provides trial readiness checklists for exhibits, witnesses, motions, openings, closings, logistics, and daily courtroom workflow.

## What This Skill Does

## Core Modules

- Trial calendar and milestone checklist
- Exhibit and witness readiness
- Motions and orders tracker
- Courtroom logistics list
- Daily trial notebook structure

## Trigger Keywords

trial preparation, trial checklist, trial notebook, courtroom logistics, legal-trial-preparation-checklist, legal trial preparation checklist

## Example Prompts

- "Create a 30-day trial preparation checklist."
- "Help me organize a trial notebook for a commercial dispute."

## Outputs

- Trial readiness checklist
- Trial notebook outline
- Logistics tracker
- Witness/exhibit status table

## Safety

Informational support only. Not legal advice. Does not replace qualified attorney review, jurisdiction-specific research, ethics analysis, or professional judgment.

FILE:skill.json
{
"name": "Legal Trial Preparation Checklist",
"slug": "legal-trial-preparation-checklist",
"version": "1.0.0",
"description": "Provides trial readiness checklists for exhibits, witnesses, motions, openings, closings, logistics, and daily courtroom workflow.",
"author": "Pearl Team (OpenClaw)",
"tags": [
"legal",
"trial",
"litigation",
"checklist",
"descriptive"
],
"trigger_keywords": [
"trial preparation",
"trial checklist",
"trial notebook",
"courtroom logistics",
"legal-trial-preparation-checklist",
"legal trial preparation checklist"
],
"language": "en",
"outputs": "markdown",
"requires_api": false,
"readiness": "stable",
"type": "descriptive",
"legal_disclaimer": "Informational workflow support only; not legal advice."
}

ClawHub Research Automation+2

H@clawhub-harrylabsj-35a31b2850

Memory Manager Pro (记忆索引管理)

Skill

Professional memory indexing and task management system for OpenClaw. Provides three-level indexing (core→project/type→detail), task tracking, keyword mappin...

---
name: memory-manager-pro
description: Professional memory indexing and task management system for OpenClaw. Provides three-level indexing (core→project/type→detail), task tracking, keyword mapping, and tag-based retrieval. Use when managing multiple projects, organizing tasks, creating memory structures, or optimizing information retrieval. Triggers on phrases like "管理记忆", "创建索引", "规划任务", "memory management", "task planning", "组织项目".
---

# Memory Manager Pro

专业记忆索引与任务管理系统 Skill for OpenClaw。提供三级索引架构、任务追踪、关键词映射、标签检索等功能，支持多项目管理。

## 核心功能

1. **三级索引架构** - 核心索引→项目/类型索引→详细内容
2. **任务管理系统** - 创建、执行、追问、归档完整流程
3. **关键词映射** - 快速定位文件路径
4. **标签系统** - 多维度组合检索
5. **规划预生成** - 自动创建下一步规划
6. **智能去重** - 标题、任务ID等自动去重检查

## 快速开始

### 创建新项目结构

```bash
# 1. 创建项目目录
mkdir -p projects/{project_name}/{subdirs}
mkdir -p memory/项目索引 memory/类型索引 memory/快速检索 memory/任务流/任务详情

# 2. 创建核心文件
touch memory/核心索引.md
touch memory/项目索引/{类型}_项目索引.md
touch memory/类型索引/{category}.md
touch memory/快速检索/关键词映射.md

# 3. 初始化任务追踪
touch memory/任务流/活跃任务.md
```

### 创建新任务

```bash
# 1. 生成任务ID
TASK_ID="TASK_{TYPE}_{YYYYMMDD}_{SEQ}"

# 2. 创建任务详情文件
touch memory/任务流/任务详情/TASK_ID.md

# 3. 添加到活跃任务索引
edit memory/任务流/活跃任务.md

# 4. 关联到项目索引
edit memory/项目索引/{项目}_项目索引.md
```

## 目录结构标准

```
workspace/
├── projects/                    # 项目目录（按项目类型分类）
│   ├── novel/                   # 小说项目
│   │   └── {project_name}/
│   ├── code/                    # 编码项目
│   │   └── {project_name}/
│   ├── design/                  # 设计项目
│   │   └── {project_name}/
│   └── research/                # 研究项目
│       └── {project_name}/
│
├── memory/                      # 记忆索引系统
│   ├── 核心索引.md              # ⭐ 顶层入口（<500字）
│   ├── 系统说明.md              # 系统架构文档
│   │
│   ├── 项目索引/                # 按项目分类（纵向）
│   │   ├── 小说项目索引.md
│   │   ├── 编码项目索引.md
│   │   ├── 设计项目索引.md
│   │   └── 研究项目索引.md
│   │
│   ├── 类型索引/                # 按任务类型分类（横向）
│   │   ├── 创作类.md
│   │   ├── 编码类.md
│   │   ├── 设计类.md
│   │   └── 研究类.md
│   │
│   ├── 快速检索/                # 快速定位系统
│   │   ├── 关键词映射.md        # 关键词→路径映射
│   │   └── 标签系统.md          # 多维度标签检索
│   │
│   └── 任务流/                  # 任务管理
│       ├── 活跃任务.md          # 进行中任务
│       ├── 已完成任务.md        # 历史归档
│       ├── 任务模板/            # 标准化模板
│       └── 任务详情/            # 详细记录（支持追问）
│
└── MEMORY.md                    # 系统入口（极简）
```

## 三级索引架构

### 一级索引（MEMORY.md）
- **作用**: 极简入口，快速跳转
- **内容量**: <500字
- **包含**: 快速开始链接、主要入口、当前状态

```markdown
# MEMORY.md - 系统入口

## 快速开始
| 我需要... | 点击这里 |
|-----------|----------|
| 继续任务X | [活跃任务](memory/任务流/活跃任务.md) |
| 查找项目Y | [核心索引](memory/核心索引.md) |

## 当前状态
| 项目 | 任务 | 状态 |
```

### 二级索引（核心索引.md）
- **作用**: 分类导航，按需下钻
- **内容量**: <1000字
- **包含**: 按项目、按类型、任务状态、快速检索

```markdown
# 核心索引

## 活跃上下文
| 项目 | 当前任务 | 状态 |

## 按项目索引
- [小说项目](项目索引/小说项目索引.md)
- [编码项目](项目索引/编码项目索引.md)

## 按类型索引
- [创作类](类型索引/创作类.md)
- [编码类](类型索引/编码类.md)

## 任务状态
- [活跃任务](任务流/活跃任务.md)
- [已完成任务](任务流/已完成任务.md)
```

### 三级索引（项目/类型索引）
- **作用**: 具体内容，详细记录
- **内容量**: <2000字
- **包含**: 项目详情、任务列表、规范标准、资源链接

## 任务管理系统

### 任务ID格式
```
TASK_{TYPE}_{YYYYMMDD}_{SEQ}

TYPE:
- NOVEL: 小说创作
- CODE: 编码开发
- DESIGN: 设计任务
- RESEARCH: 研究分析
- SYSTEM: 系统优化

示例:
- TASK_NOVEL_20260426_001
- TASK_CODE_20260426_003
```

### 任务状态流转
```
待开始 → 进行中 → 待追问 → 已完成
            ↓
          已暂停
```

### 任务文件模板

**活跃任务索引.md**:
```markdown
# 活跃任务

## 按项目分组
| 任务ID | 内容 | 状态 | 优先级 | 详情 |

## 快速操作
- [任务详情](任务详情/TASK_XXX.md)
```

**任务详情/TASK_XXX.md**:
```markdown
# TASK_XXX

## 基本信息
- 标题：
- 类型：
- 状态：
- 优先级：

## 任务内容
...

## 执行记录
### 阶段1
- 时间：
- 操作：
- 结果：

## 追问记录
- 追问1：

## 下一步建议
...
```

## 关键词映射系统

### 映射表格式
```markdown
# 关键词映射表

## 项目关键词
| 关键词 | 映射路径 | 说明 |
|--------|----------|------|
| 天道养殖场 | projects/novel/天道养殖场/ | 小说项目 |

## 任务关键词
| 关键词 | 映射路径 | 说明 |
|--------|----------|------|
| 活跃任务 | memory/任务流/活跃任务.md | 当前任务 |
| 任务091 | memory/任务流/任务详情/TASK_XXX.md | 具体任务 |

## 索引关键词
| 关键词 | 映射路径 | 说明 |
|--------|----------|------|
| 核心索引 | memory/核心索引.md | 顶层导航 |
```

### 使用场景

**场景1**: 用户说"继续创作天道养殖场"
```
1. 检索关键词"天道养殖场" → 定位项目目录
2. 检查活跃任务 → 获取当前任务ID
3. 读取任务详情 → 获取规划文件路径
4. 传递必要文件，执行任务
```

## 标签系统

### 标签分类

**项目标签**:
- `#天道养殖场` - 具体项目
- `#小说` - 项目类型

**类型标签**:
- `#创作` - 任务类型
- `#编码` - 任务类型
- `#设计` - 任务类型
- `#研究` - 任务类型

**状态标签**:
- `#活跃` - 进行中
- `#待开始` - 未开始
- `#已完成` - 已归档
- `#待追问` - 需追问

**优先级标签**:
- `#高优先级`
- `#中优先级`
- `#低优先级`

### 组合检索

**检索"活跃的小说创作任务"**:
- 标签: `#创作` + `#活跃` + `#小说`
- 结果: 过滤后的任务列表

## 索引更新服务（外部 Skill 调用接口）

Memory Manager Pro 提供标准化的索引更新服务，可被其他 Skill（如 Web Novel Creator）调用。

所有路径通过**语义推导自动生成**，无需调用方指定。

### 接口定义

**请求参数格式**：

```
Memory Manager Pro 索引更新请求
{
  "操作": "完成创作并更新索引",      // 必填
  "任务ID": "TASK_NOVEL_YYYYMMDD_XXX",  // 必填
  "章节": "第XXX章《标题名》",         // 可选
  "字数": "XXXX字",                   // 可选
  "项目": "天道养殖场",                // 必填，用于语义推导
  "创建下一章任务": true/false,         // 可选
  "下一章章节名": "第XXX+1章《标题》"  // 可选
}
```

**最简调用示例**（Web Novel Creator 创作完一章后）：
```
{
  "操作": "完成创作并更新索引",
  "任务ID": "TASK_NOVEL_20260426_004",
  "章节": "第094章《城中暗影》",
  "字数": "~2600字",
  "项目": "天道养殖场",
  "创建下一章任务": true,
  "下一章章节名": "第095章《残魂低语》"
}
```

---

### 语义推导引擎

Memory Manager Pro 从 `任务ID` 和 `项目` 参数中自动推导所有路径，无需硬编码：

#### 路径推导规则

```
任务ID → 自动提取任务类型
  TASK_NOVEL_xxx → 类型 = 创作类，项目类型 = 小说
  TASK_CODE_xxx  → 类型 = 编码类，项目类型 = 编码
  TASK_DESIGN_xxx → 类型 = 设计类，项目类型 = 设计
  TASK_RESEARCH_xxx → 类型 = 研究类，项目类型 = 研究
  TASK_SYSTEM_xxx → 类型 = 系统类，项目类型 = 系统

项目名 → 自动定位项目目录（通过关键词映射）
  1. 查 memory/快速检索/关键词映射.md 中的「项目关键词」表
  2. 若存在：直接使用映射路径
  3. 若不存在：按默认路径规则生成
    novel/项目名/ → 小说项目
    code/项目名/  → 编码项目
    design/项目名/ → 设计项目
    research/项目名/ → 研究项目

推导出的文件路径：
  项目索引:   memory/项目索引/{项目类型}项目索引.md
  类型索引:   memory/类型索引/{任务类型}.md
  任务详情:   memory/任务流/任务详情/{任务ID}.md
  正文目录:   {项目目录}正文/
  规划目录:   {项目目录}规划/
  标题库:     {项目目录}规划/已用标题库.md
```

#### 推导示例

| 任务ID | 项目 | 推导出的项目索引 | 推导出的类型索引 | 推导出的项目目录 |
|--------|------|-----------------|-----------------|-----------------|
| TASK_NOVEL_... | 天道养殖场 | `小说项目索引.md` | `创作类.md` | `novel/天道养殖场：从盘古开天杀穿/` |
| TASK_CODE_... | 博客系统 | `编码项目索引.md` | `编码类.md` | `code/博客系统/` |
| TASK_DESIGN_... | UI重设计 | `设计项目索引.md` | `设计类.md` | `design/UI重设计/` |
| TASK_RESEARCH_... | AI调研 | `研究项目索引.md` | `研究类.md` | `research/AI调研/` |

---

### 执行步骤

收到请求后，Memory Manager Pro 按以下流程执行：

```
第一步：解析参数
  ├── 从任务ID提取类型前缀（NOVEL/CODE/DESIGN/RESEARCH/SYSTEM）
  ├── 从类型前缀推导项目索引文件路径
  ├── 从类型前缀推导类型索引文件路径
  ├── 从项目名称查关键词映射 → 项目目录
  └── 若关键词映射不存在，按规则生成默认路径

第二步：更新任务详情
  ├── 构造路径: memory/任务流/任务详情/{任务ID}.md
  ├── 检查文件是否存在
  ├── 存在 → 标记已完成，追加执行记录
  └── 不存在 → 创建新文件（含基本信息、执行记录）

第三步：更新已完成任务索引
  ├── edit memory/任务流/已完成任务.md
  ├── 追加当日的任务记录
  └── 更新统计信息

第四步：更新活跃任务索引
  ├── edit memory/任务流/活跃任务.md
  ├── 从活跃列表移除已完成的
  └── 如请求创建下一章任务，追加新任务到活跃列表

第五步：更新项目索引（路径由类型前缀自动推导）
  ├── 类型前缀 NOVEL
  │   └── edit memory/项目索引/小说项目索引.md
  ├── 类型前缀 CODE
  │   └── edit memory/项目索引/编码项目索引.md
  ├── 类型前缀 DESIGN
  │   └── edit memory/项目索引/设计项目索引.md
  ├── 类型前缀 RESEARCH
  │   └── edit memory/项目索引/研究项目索引.md
  └── (如文件不存在，自动创建)

第六步：更新类型索引（路径由任务类型名称自动推导）
  ├── 类型 = 创作类 → edit memory/类型索引/创作类.md
  ├── 类型 = 编码类 → edit memory/类型索引/编码类.md
  ├── 类型 = 设计类 → edit memory/类型索引/设计类.md
  ├── 类型 = 研究类 → edit memory/类型索引/研究类.md
  └── 类型 = 系统类 → edit memory/类型索引/系统类.md（如不存在自动创建）

第七步：更新核心索引
  └── edit memory/核心索引.md

第八步：更新MEMORY.md
  └── edit MEMORY.md
```

### 类型前缀 → 索引文件映射表（完整参考）

| 任务ID前缀 | 类型名称 | 项目索引 | 类型索引 | 默认项目目录 |
|-----------|----------|----------|----------|-------------|
| NOVEL | 创作类 | `小说项目索引.md` | `创作类.md` | `novel/` |
| CODE | 编码类 | `编码项目索引.md` | `编码类.md` | `code/` |
| DESIGN | 设计类 | `设计项目索引.md` | `设计类.md` | `design/` |
| RESEARCH | 研究类 | `研究项目索引.md` | `研究类.md` | `research/` |
| SYSTEM | 系统类 | （无项目索引） | `系统类.md` | （无项目目录） |

### 调用注意事项

1. **调用方只需要传递 4 个必填参数**（操作、任务ID、项目、章节），其余可省略
2. **所有路径由系统自动推导**，不依赖调用方传入任何路径
3. **支持批量操作**：传递多个任务ID可一次性批量更新
4. **调用方仍需自己更新**小说专属内容文件（正文、规划、标题库）
5. **关键词映射优先**：项目目录优先查关键词映射表，不存在才用默认规则
6. **处理完后**返回确认信息给调用方

## Token 优化策略

### 按需加载原则

| 场景 | 传递内容 | 避免传递 |
|------|----------|----------|
| 执行任务 | 规划文件+必要上下文 | 历史完整记录 |
| 任务追问 | 任务详情文件 | 其他任务记录 |
| 项目概览 | 项目索引文件 | 详细内容文件 |
| 全局导航 | 核心索引文件 | 所有详细内容 |

### 文件大小控制

- MEMORY.md: <500字
- 核心索引.md: <1000字
- 项目/类型索引: <2000字
- 任务详情: 按需，完整记录

## 使用流程

### 创建新项目

```bash
# 1. 创建目录结构
mkdir -p projects/{类型}/{项目名}/{子目录}

# 2. 创建项目索引
edit memory/项目索引/{类型}_项目索引.md

# 3. 更新核心索引
edit memory/核心索引.md

# 4. 创建初始任务
# 生成任务ID
# 创建任务详情文件
# 添加到活跃任务索引
```

### 执行日常任务

```bash
# 1. 检查活跃任务
read memory/任务流/活跃任务.md

# 2. 读取任务详情
read memory/任务流/任务详情/TASK_XXX.md

# 3. 根据任务类型读取规划
read {项目路径}/规划/第XXX章规划.md

# 4. 执行任务
# ...

# 5. 更新任务状态
edit memory/任务流/任务详情/TASK_XXX.md
edit memory/任务流/活跃任务.md

# 6. 生成下一步规划（可选）
write {项目路径}/规划/第XXX+1章规划.md
```

### 追问历史任务

```bash
# 1. 关键词检索
# "第091章" → TASK_NOVEL_20260426_001

# 2. 读取任务详情
read memory/任务流/任务详情/TASK_NOVEL_20260426_001.md

# 3. 展示结果
```

## 参考文件

- `references/目录结构标准.md` - 完整目录规范
- `references/任务模板.md` - 任务文件模板
- `references/索引模板.md` - 索引文件模板
- `references/关键词映射示例.md` - 映射表示例
- `references/标签系统指南.md` - 标签使用指南

## 使用示例

### 示例1: 创建小说创作任务
```
用户: "创建天道养殖场第092章创作任务"

系统:
1. 生成任务ID: TASK_NOVEL_20260426_002
2. 创建任务详情文件
3. 读取第092章规划文件
4. 添加到活跃任务索引
5. 更新项目索引
6. 返回: 任务已创建，等待执行
```

### 示例2: 查看当前活跃任务
```
用户: "查看当前有什么任务"

系统:
1. 读取 memory/任务流/活跃任务.md
2. 按项目/类型/优先级分组展示
3. 提供快速操作链接
```

### 示例3: 追问历史任务
```
用户: "第091章创作得怎么样"

系统:
1. 关键词检索 "第091章" → TASK_NOVEL_20260426_001
2. 读取任务详情
3. 展示: 字数、时间、成果、关键节点
```

## 扩展方式

### 添加新项目类型
1. 创建 `memory/项目索引/新类型_项目索引.md`
2. 创建 `projects/新类型/` 目录
3. 更新 `memory/核心索引.md`
4. 更新关键词映射

### 添加新任务类型
1. 创建 `memory/类型索引/新类型.md`
2. 创建任务模板（可选）
3. 更新标签系统
4. 更新关键词映射

## 设计原则

1. **按需加载** - 只传递当前任务必需的上下文
2. **快速定位** - 通过索引3秒内找到目标文件
3. **最小上下文** - MEMORY.md < 500字，逐级下钻
4. **双向索引** - 纵向（项目）+ 横向（类型）交叉
5. **完整追溯** - 任务详情完整记录，支持追问

FILE:README.md
# Memory Manager Pro

专业记忆索引与任务管理系统 Skill for OpenClaw

## 简介

Memory Manager Pro 是一个通用的记忆索引与任务管理 Skill，适用于所有类型的项目管理。提供三级索引架构、任务追踪、关键词映射、标签检索等功能。

## 功能特性

- ✅ **三级索引架构** - 核心索引→项目/类型索引→详细内容
- ✅ **任务管理系统** - 创建、执行、追问、归档完整流程
- ✅ **关键词映射** - 快速定位文件路径
- ✅ **标签系统** - 多维度组合检索
- ✅ **规划预生成** - 自动创建下一步规划
- ✅ **智能去重** - 标题、任务ID等自动去重检查
- ✅ **多项目支持** - 同时管理多个项目
- ✅ **Token优化** - 按需加载，最小上下文
- ✅ **语义推导归档** - 通过任务ID前缀自动推导索引路径，无需硬编码
- ✅ **外部 Skill 调用接口** - 接受 Web Novel Creator 等外部 Skill 的索引更新请求

## 安装

### 本地安装
```bash
# 将 skill 复制到 workspace skills 目录
cp -r memory-manager-pro ~/.openclaw/workspace/skills/

# 验证安装
openclaw skills info memory-manager-pro
```

## 使用方法

### 触发方式

Skill 会自动识别以下关键词触发：
- "管理记忆"
- "创建索引"
- "规划任务"
- "memory management"
- "task planning"
- "组织项目"

### 快速开始

#### 1. 创建新项目结构
```
用户: "为我的小说项目创建记忆管理系统"

系统:
1. 创建目录结构
   - projects/novel/{项目名}/
   - memory/项目索引/
   - memory/类型索引/
   - memory/快速检索/
   - memory/任务流/

2. 创建核心文件
   - memory/核心索引.md
   - memory/项目索引/小说项目索引.md
   - memory/类型索引/创作类.md
   - memory/快速检索/关键词映射.md

3. 初始化任务追踪
   - memory/任务流/活跃任务.md
   - memory/任务流/已完成任务.md
```

#### 2. 创建新任务
```
用户: "创建第092章创作任务"

系统:
1. 生成任务ID: TASK_NOVEL_20260426_002
2. 创建任务详情文件
3. 添加到活跃任务索引
4. 关联到项目索引
5. 更新关键词映射
```

#### 3. 执行任务
```
用户: "执行第092章创作任务"

系统:
1. 读取活跃任务索引
2. 读取任务详情
3. 读取规划文件
4. 执行任务
5. 更新任务状态
6. 生成下一步规划
```

## 目录结构

```
workspace/
├── projects/                    # 项目存储
│   ├── novel/
│   ├── code/
│   ├── design/
│   └── research/
│
├── memory/                      # 记忆索引系统
│   ├── 核心索引.md              # 顶层入口
│   ├── 系统说明.md              # 系统架构
│   ├── 项目索引/                # 纵向索引
│   ├── 类型索引/                # 横向索引
│   ├── 快速检索/                # 快速定位
│   └── 任务流/                  # 任务管理
│
└── MEMORY.md                    # 系统入口
```

## 核心概念

### 三级索引架构

| 级别 | 文件 | 大小 | 作用 |
|------|------|------|------|
| 一级 | MEMORY.md | <500字 | 极简入口 |
| 二级 | 核心索引.md | <1000字 | 分类导航 |
| 三级 | 项目/类型索引 | <2000字 | 详细内容 |

### 任务ID格式
```
TASK_{TYPE}_{YYYYMMDD}_{SEQ}

示例：
- TASK_NOVEL_20260426_001
- TASK_CODE_20260426_003
- TASK_DESIGN_20260426_005
```

### 标签系统

**项目标签**: `#天道养殖场` `#项目A`
**类型标签**: `#创作` `#编码` `#设计` `#研究`
**状态标签**: `#活跃` `#待开始` `#已完成` `#待追问`
**优先级标签**: `#高优先级` `#中优先级` `#低优先级`

## 文件说明

- `SKILL.md` - Skill 主文件
- `references/目录结构标准.md` - 完整目录规范
- `references/任务模板.md` - 任务文件模板
- `references/索引模板.md` - 索引文件模板
- `references/关键词映射示例.md` - 映射表示例
- `references/标签系统指南.md` - 标签使用指南

## 使用示例

### 示例1：初始化新项目
```
用户: "为天道养殖场创建记忆管理系统"

系统执行：
1. mkdir -p projects/novel/天道养殖场/{正文,规划}
2. mkdir -p memory/{项目索引,类型索引,快速检索,任务流/任务详情}
3. 创建核心索引.md
4. 创建小说项目索引.md
5. 创建关键词映射.md
6. 初始化任务流

结果：记忆管理系统创建完成
```

### 示例2：创建并执行任务
```
用户: "创建并执行第092章创作任务"

系统执行：
1. 生成任务ID: TASK_NOVEL_20260426_002
2. 创建任务详情文件
3. 添加到活跃任务索引
4. 读取第092章规划
5. 检查标题库
6. 创作章节
7. 更新任务状态为已完成
8. 生成第093章规划
9. 更新所有索引
```

### 示例3：追问历史任务
```
用户: "查看第091章任务详情"

系统执行：
1. 关键词检索 "第091章" → TASK_NOVEL_20260426_001
2. 读取任务详情文件
3. 展示: 基本信息、执行记录、成果统计
```

## Token 优化

### 按需加载
| 场景 | 传递内容 |
|------|----------|
| 执行任务 | 规划文件+必要上下文 |
| 任务追问 | 任务详情文件 |
| 项目概览 | 项目索引文件 |
| 全局导航 | 核心索引文件 |

### 文件大小控制
- MEMORY.md: <500字
- 核心索引.md: <1000字
- 项目/类型索引: <2000字

## 扩展方式

### 添加新项目类型
1. 创建 `memory/项目索引/新类型_项目索引.md`
2. 创建 `projects/新类型/` 目录
3. 更新 `memory/核心索引.md`
4. 更新关键词映射

### 添加新任务类型
1. 创建 `memory/类型索引/新类型.md`
2. 创建任务模板
3. 更新标签系统
4. 更新关键词映射

## 贡献

欢迎提交 Issue 和 PR！

## 许可证

MIT License

## 作者

OpenClaw User

## 更新日志

### v1.1.0 (2026-04-26)
- 新增「索引更新服务」接口，接受外部 Skill 调用
- 语义推导引擎：通过任务ID类型前缀自动推导项目索引/类型索引路径
- 关键词映射优先：项目目录优先查关键词映射，不存在才用默认规则
- WEB Novel Creator 创作完成后委托 Memory Manager Pro 完成全量索引更新

### v1.0.0 (2026-04-26)
- 初始版本发布
- 三级索引架构
- 任务管理系统
- 关键词映射
- 标签检索系统
- 多项目支持

FILE:references/任务模板.md
# 任务文件模板

## 活跃任务索引模板

```markdown
# 活跃任务

> 当前进行中的任务列表

## 按项目分组

### {项目名称}
| 任务ID | 内容 | 状态 | 优先级 | 详情 |
|--------|------|------|--------|------|
| TASK_XXX | {任务简述} | {状态} | {优先级} | [详情](任务详情/TASK_XXX.md) |

## 按类型分组

### {类型}
- TASK_XXX: {任务简述}

## 按优先级分组

### 高优先级
- TASK_XXX: {任务简述}

### 中优先级
- 暂无

### 低优先级
- 暂无

## 快速操作

- [任务详情](任务详情/TASK_XXX.md)

---
*标签: #活跃 #项目名 #类型 #优先级*
```

## 任务详情模板

```markdown
# {任务ID}

## 基本信息
- **任务标题**: 
- **任务类型**: NOVEL/CODE/DESIGN/RESEARCH/SYSTEM
- **关联项目**: 
- **创建时间**: YYYY-MM-DD HH:MM
- **状态**: 待开始/进行中/待追问/已完成/已暂停
- **优先级**: 高/中/低

## 任务内容
{详细描述任务目标和要求}

## 输入资源
- {资源1}: {路径}
- {资源2}: {路径}

## 输出交付
- {交付物1}: {路径}
- {交付物2}: {路径}

## 执行记录

### 阶段1: {阶段名称}
- **时间**: YYYY-MM-DD HH:MM
- **操作**: {具体操作}
- **结果**: {执行结果}
- **问题**: {遇到的问题}

### 阶段2: {阶段名称}
- **时间**: 
- **操作**: 
- **结果**: 

## 追问记录

### 追问1: {追问主题}
- **时间**: 
- **问题**: 
- **回答**: 
- **链接**: [追问文件](追问记录/{任务ID}_追问1.md)

## 下一步建议
1. {建议1}
2. {建议2}

## 关联任务
- **前置任务**: TASK_XXX
- **后续任务**: TASK_XXX
- **相关任务**: TASK_XXX

## 统计信息
- **预估工时**: X小时
- **实际工时**: X小时
- **完成度**: X%

---
*最后更新: YYYY-MM-DD HH:MM*
*标签: #项目名 #类型 #状态 #优先级*
```

## 已完成任务索引模板

```markdown
# 已完成任务

> 已归档的历史任务

## {年月}

| 任务ID | 类型 | 内容 | 项目 | 完成时间 | 成果 | 详情 |
|--------|------|------|------|----------|------|------|
| TASK_XXX | {类型} | {内容} | {项目} | YYYY-MM-DD | {成果} | [详情](任务详情/TASK_XXX.md) |

## 统计

### 本月统计
- {类型}: X个
- 总计: X个

### 累计成果
- {成果类型}: X

---
*标签: #已完成 #历史归档*
```

## 使用说明

1. 创建新任务时，复制对应模板
2. 填充基本信息和任务内容
3. 执行过程中逐步完善执行记录
4. 完成后移动到已完成任务索引
5. 保留任务详情文件用于追问

FILE:references/关键词映射示例.md
# 关键词映射示例

## 项目关键词

| 关键词 | 映射路径 | 说明 | 标签 |
|--------|----------|------|------|
| 天道养殖场 | `projects/novel/天道养殖场/` | 小说项目 | #天道养殖场 #小说 |
| 项目A | `projects/code/项目A/` | 编码项目 | #项目A #编码 |
| 设计B | `projects/design/设计B/` | 设计项目 | #设计B #设计 |
| 研究C | `projects/research/研究C/` | 研究项目 | #研究C #研究 |

## 章节/阶段关键词

| 关键词 | 映射路径 | 说明 | 标签 |
|--------|----------|------|------|
| 第091章 | `projects/novel/天道养殖场/规划/第091章规划.md` | 章节规划 | #天道养殖场 #第091章 |
| 第092章 | `projects/novel/天道养殖场/规划/第092章规划.md` | 章节规划 | #天道养殖场 #第092章 |
| 阶段1 | `memory/任务流/任务详情/TASK_XXX.md#阶段1` | 任务阶段 | #TASK_XXX |

## 任务关键词

| 关键词 | 映射路径 | 说明 | 标签 |
|--------|----------|------|------|
| 活跃任务 | `memory/任务流/活跃任务.md` | 当前任务列表 | #活跃 #任务 |
| 已完成任务 | `memory/任务流/已完成任务.md` | 历史任务列表 | #已完成 #任务 |
| 任务091 | `memory/任务流/任务详情/TASK_NOVEL_20260426_001.md` | 具体任务 | #天道养殖场 #创作 |
| 任务092 | `memory/任务流/任务详情/TASK_NOVEL_20260426_002.md` | 具体任务 | #天道养殖场 #创作 |

## 索引关键词

| 关键词 | 映射路径 | 说明 | 标签 |
|--------|----------|------|------|
| 核心索引 | `memory/核心索引.md` | 顶层导航 | #索引 #核心 |
| 项目索引 | `memory/项目索引/` | 按项目分类 | #索引 #项目 |
| 类型索引 | `memory/类型索引/` | 按类型分类 | #索引 #类型 |
| 小说项目 | `memory/项目索引/小说项目索引.md` | 小说项目列表 | #索引 #小说 |
| 编码项目 | `memory/项目索引/编码项目索引.md` | 编码项目列表 | #索引 #编码 |
| 创作类 | `memory/类型索引/创作类.md` | 创作任务索引 | #索引 #创作 |
| 编码类 | `memory/类型索引/编码类.md` | 编码任务索引 | #索引 #编码 |

## 资源关键词

| 关键词 | 映射路径 | 说明 | 标签 |
|--------|----------|------|------|
| 标题库 | `projects/novel/天道养殖场/规划/已用标题库.md` | 已用标题列表 | #天道养殖场 #标题库 |
| 规划模板 | `memory/任务流/任务模板/小说创作.md` | 任务模板 | #模板 #创作 |
| 番茄规范 | `references/番茄小说规范.md` | 平台规范 | #规范 #番茄小说 |

## 检索示例

### 示例1：继续创作天道养殖场
```
输入: "继续创作天道养殖场"
关键词: "天道养殖场"
映射: projects/novel/天道养殖场/
操作:
1. 读取项目索引获取当前任务
2. 读取下一章规划文件
3. 读取标题库检查去重
4. 执行创作任务
```

### 示例2：查看当前任务
```
输入: "查看当前任务"
关键词: "活跃任务"
映射: memory/任务流/活跃任务.md
操作:
1. 读取活跃任务索引
2. 按项目/类型/优先级分组展示
3. 提供快速操作链接
```

### 示例3：追问历史任务
```
输入: "第091章创作得怎么样"
关键词: "第091章"
映射: memory/任务流/任务详情/TASK_NOVEL_20260426_001.md
操作:
1. 关键词检索定位任务详情文件
2. 读取任务执行记录和成果
3. 展示统计数据和关键节点
```

### 示例4：查找项目
```
输入: "查看小说项目"
关键词: "小说项目"
映射: memory/项目索引/小说项目索引.md
操作:
1. 读取小说项目索引
2. 展示所有活跃和已完成的小说项目
3. 提供项目入口链接
```

## 维护说明

1. **添加新项目**：在对应类别下添加关键词条目
2. **添加新任务**：创建任务时同步更新映射表
3. **定期清理**：移除不再使用的关键词
4. **标签同步**：确保关键词和标签一致

FILE:references/标签系统指南.md
# 标签系统指南

## 标签分类体系

### 1. 项目标签
用于标识所属项目

| 标签 | 说明 | 示例 |
|------|------|------|
| `#天道养殖场` | 具体项目名称 | 小说项目 |
| `#项目A` | 具体项目名称 | 编码项目 |
| `#设计B` | 具体项目名称 | 设计项目 |
| `#研究C` | 具体项目名称 | 研究项目 |

### 2. 类型标签
用于标识任务类型

| 标签 | 说明 | 适用场景 |
|------|------|----------|
| `#创作` | 创作类任务 | 小说、文案、策划 |
| `#编码` | 编码类任务 | 开发、调试、部署 |
| `#设计` | 设计类任务 | 视觉、交互、原型 |
| `#研究` | 研究类任务 | 调研、分析、总结 |
| `#系统` | 系统类任务 | 优化、配置、维护 |

### 3. 状态标签
用于标识任务状态

| 标签 | 说明 | 流转规则 |
|------|------|----------|
| `#活跃` | 进行中 | 待开始→进行中 |
| `#待开始` | 未开始 | 新建任务 |
| `#待追问` | 需追问 | 进行中→待追问 |
| `#已完成` | 已归档 | 进行中→已完成 |
| `#已暂停` | 暂停中 | 进行中→已暂停 |

### 4. 优先级标签
用于标识任务优先级

| 标签 | 说明 | 处理顺序 |
|------|------|----------|
| `#高优先级` | 紧急重要 | 优先处理 |
| `#中优先级` | 重要不紧急 | 其次处理 |
| `#低优先级` | 不紧急 | 延后处理 |

### 5. 索引标签
用于标识索引类型

| 标签 | 说明 | 使用场景 |
|------|------|----------|
| `#索引` | 索引文件 | 所有索引文件 |
| `#核心` | 核心索引 | MEMORY.md、核心索引.md |
| `#项目` | 项目索引 | 项目索引目录下 |
| `#类型` | 类型索引 | 类型索引目录下 |

## 组合检索

### 基础组合

**项目+类型**
```
#天道养殖场 + #创作
→ 天道养殖场项目的所有创作任务
```

**类型+状态**
```
#创作 + #活跃
→ 所有活跃的创作任务
```

**项目+状态**
```
#天道养殖场 + #活跃
→ 天道养殖场项目的活跃任务
```

### 复杂组合

**项目+类型+状态**
```
#天道养殖场 + #创作 + #活跃
→ 天道养殖场项目中活跃的创作任务
```

**类型+状态+优先级**
```
#创作 + #活跃 + #高优先级
→ 活跃的、高优先级的创作任务
```

**项目+类型+状态+优先级**
```
#天道养殖场 + #创作 + #活跃 + #高优先级
→ 天道养殖场项目中活跃的、高优先级的创作任务
```

## 使用场景

### 场景1：查看小说创作任务
```
检索: #创作 + #小说
结果: 
- TASK_NOVEL_20260426_001: 第091章创作
- TASK_NOVEL_20260426_002: 第092章创作
```

### 场景2：查看高优先级任务
```
检索: #活跃 + #高优先级
结果:
- TASK_NOVEL_20260426_001: 第091章创作（高）
- TASK_CODE_20260426_003: 紧急修复（高）
```

### 场景3：查看天道养殖场所有任务
```
检索: #天道养殖场
结果:
- 活跃: TASK_NOVEL_20260426_001
- 活跃: TASK_NOVEL_20260426_002
- 已完成: TASK_NOVEL_20260425_003
```

### 场景4：查看待追问任务
```
检索: #待追问
结果:
- TASK_XXX: 等待用户确认
```

## 标签使用规范

### 文件头部标签注释

```markdown
<!--
标签: #天道养殖场 #创作 #活跃 #高优先级
创建: 2026-04-26 00:00
更新: 2026-04-26 00:00
-->

# 文件内容...
```

### 索引文件标签

**活跃任务.md**
```markdown
---
*标签: #活跃 #任务 #索引*
```

**项目索引.md**
```markdown
---
*标签: #项目 #索引 #{项目名}*
```

**任务详情.md**
```markdown
---
*标签: #{项目名} #类型 #状态 #优先级*
```

## 标签管理

### 添加新标签

1. 确定标签分类（项目/类型/状态/优先级/索引）
2. 确保标签名称简洁明了
3. 在标签系统指南中登记
4. 更新相关文件的标签注释

### 标签命名规范

- 使用英文或中文
- 简洁明了，不超过10个字符
- 避免空格，使用连字符或驼峰
- 统一大小写（建议使用小写）

### 标签示例

```
✓ #天道养殖场
✓ #创作
✓ #活跃
✓ #高优先级
✓ #小说-创作

✗ #天道养殖场第91章（太长）
✗ #创 作（有空格）
✗ #ACTIVE（大小写不一致）
```

## 标签检索实现

### 方式1：全文搜索
```bash
# 搜索包含特定标签的文件
grep -r "#天道养殖场" memory/ --include="*.md"
```

### 方式2：索引文件
维护标签→文件列表的映射表

```markdown
# 标签索引

## #天道养殖场
- memory/任务流/任务详情/TASK_NOVEL_20260426_001.md
- memory/项目索引/小说项目索引.md

## #创作
- memory/类型索引/创作类.md
- memory/任务流/任务详情/TASK_NOVEL_20260426_001.md
```

### 方式3：动态检索
根据标签组合实时筛选

```
输入: #天道养殖场 + #活跃
步骤:
1. 找到所有含#天道养殖场的文件
2. 找到所有含#活跃的文件
3. 取交集
4. 返回结果列表
```

FILE:references/目录结构标准.md
# 目录结构标准

## 完整目录树

```
workspace/
├── projects/                    # 项目存储（按类型分类）
│   ├── novel/                   # 小说项目
│   │   └── {project_name}/
│   │       ├── 正文/
│   │       └── 规划/
│   ├── code/                    # 编码项目
│   │   └── {project_name}/
│   ├── design/                  # 设计项目
│   │   └── {project_name}/
│   └── research/                # 研究项目
│       └── {project_name}/
│
├── memory/                      # 记忆索引系统
│   ├── 核心索引.md              # ⭐ 顶层入口
│   ├── 系统说明.md              # 系统架构文档
│   │
│   ├── 项目索引/                # 纵向索引（按项目）
│   │   ├── 小说项目索引.md
│   │   ├── 编码项目索引.md
│   │   ├── 设计项目索引.md
│   │   └── 研究项目索引.md
│   │
│   ├── 类型索引/                # 横向索引（按类型）
│   │   ├── 创作类.md
│   │   ├── 编码类.md
│   │   ├── 设计类.md
│   │   └── 研究类.md
│   │
│   ├── 快速检索/                # 快速定位
│   │   ├── 关键词映射.md
│   │   └── 标签系统.md
│   │
│   └── 任务流/                  # 任务管理
│       ├── 活跃任务.md
│       ├── 已完成任务.md
│       ├── 任务模板/
│       │   ├── 小说创作.md
│       │   ├── 编码开发.md
│       │   ├── 设计任务.md
│       │   └── 研究分析.md
│       └── 任务详情/
│           └── TASK_XXX.md
│
└── MEMORY.md                    # 系统入口（极简）
```

## 文件大小标准

| 文件 | 建议大小 | 说明 |
|------|----------|------|
| MEMORY.md | < 500字 | 极简入口 |
| 核心索引.md | < 1000字 | 分类导航 |
| 项目/类型索引 | < 2000字 | 详细内容 |
| 任务详情 | 按需 | 完整记录 |
| 规划文件 | < 1500字 | 章节规划 |

## 命名规范

### 任务ID
```
TASK_{TYPE}_{YYYYMMDD}_{SEQ}

示例：
- TASK_NOVEL_20260426_001
- TASK_CODE_20260426_003
- TASK_DESIGN_20260426_005
```

### 章节标题
```
第XXX章《标题名》

示例：
- 第091章《第七层觉醒》
- 第092章《本源具现》
```

### 索引文件名
```
{分类}_索引.md
{分类}_项目索引.md
{分类}.md

示例：
- 核心索引.md
- 小说项目索引.md
- 创作类.md
```

## 创建新项目流程

```bash
# 1. 创建项目目录
mkdir -p projects/{类型}/{项目名}/{子目录}

# 2. 创建索引文件
touch memory/项目索引/{类型}_项目索引.md

# 3. 更新核心索引
edit memory/核心索引.md

# 4. 创建初始规划（可选）
touch projects/{类型}/{项目名}/规划/初始规划.md

# 5. 更新关键词映射
edit memory/快速检索/关键词映射.md
```

## 文件模板位置

- `references/索引模板.md` - 索引文件模板
- `references/任务模板.md` - 任务文件模板
- `references/规划模板.md` - 规划文件模板

FILE:references/索引模板.md
# 索引文件模板

## 核心索引模板

```markdown
# 核心索引

> 顶层快速入口，按需向下导航

## 活跃上下文

| 项目 | 当前任务 | 最后更新 | 快速入口 |
|------|----------|----------|----------|
| {项目名} | {当前任务} | YYYY-MM-DD | [规划]({规划路径}) |

## 按项目索引

- [{类型1}项目](项目索引/{类型1}_项目索引.md)
- [{类型2}项目](项目索引/{类型2}_项目索引.md)

## 按类型索引

- [{类型1}类](类型索引/{类型1}.md)
- [{类型2}类](类型索引/{类型2}.md)

## 任务状态

- [活跃任务](任务流/活跃任务.md)
- [已完成任务](任务流/已完成任务.md)

## 快速检索

- [关键词映射](快速检索/关键词映射.md)
- [标签系统](快速检索/标签系统.md)

---
*设计原则：本文件保持极简，所有详情通过链接按需加载*
```

## 项目索引模板

```markdown
# {类型}项目索引

## 活跃项目

### {项目名称}
| 属性 | 值 |
|------|-----|
| 项目ID | {ID} |
| 状态 | {状态} |
| 目录 | `projects/{类型}/{项目名}/` |
| 当前任务 | TASK_XXX |

**快速链接**
- [项目目录]({项目路径})
- [当前规划]({规划路径})
- [任务详情](../任务流/任务详情/TASK_XXX.md)

**关键信息**
- 

**规范标准**
- 

---

## 项目模板

```markdown
### {项目名称}
| 属性 | 值 |
|------|-----|
| 项目ID | {ID} |
| 状态 | {状态} |
| 目录 | `projects/{类型}/{项目名}/` |
| 当前任务 | TASK_XXX |

**快速链接**
- [目录]()
- [规划]()
- [任务]()

**关键信息**
- 

**规范标准**
- 
```

## 类型索引模板

```markdown
# {类型}类任务索引

## 活跃任务

| 任务ID | 项目 | 内容 | 状态 | 规划文件 |
|--------|------|------|------|----------|
| TASK_XXX | {项目} | {内容} | {状态} | [规划]({规划路径}) |

## 规范库

### {子类型}规范
- 

## 资源

### {资源类型}
- 

## 历史任务

| 任务ID | 项目 | 内容 | 完成时间 | 成果 |
|--------|------|------|----------|------|
| TASK_XXX | {项目} | {内容} | YYYY-MM-DD | {成果} |

## 技巧库

- 

---
*标签: #{类型} #活跃 #历史归档*
```

## MEMORY.md 模板

```markdown
# MEMORY.md - 系统入口

> 极简入口，快速导航到详细内容

## 快速开始

| 我需要... | 点击这里 |
|-----------|----------|
| 继续{任务} | [{任务}]({任务路径}) |
| 查看当前任务 | [活跃任务](memory/任务流/活跃任务.md) |
| 查找项目 | [核心索引](memory/核心索引.md) |

## 主要入口

- **[核心索引](memory/核心索引.md)** - 系统主入口
- **[活跃任务](memory/任务流/活跃任务.md)** - 当前任务
- **[关键词检索](memory/快速检索/关键词映射.md)** - 快速定位

## 当前状态

| 项目 | 任务 | 状态 |
|------|------|------|
| {项目} | {任务} | {状态} |

## 任务索引系统

| 索引文件 | 路径 |
|----------|------|
| 活跃任务 | `memory/任务流/活跃任务.md` |
| 已完成任务 | `memory/任务流/已完成任务.md` |
| 任务详情 | `memory/任务流/任务详情/` |

---
*本文件保持极简，详细内容通过链接按需加载*
*最后更新: YYYY-MM-DD HH:MM*
```

ClawHub Coding Research+2

C@clawhub-guojiuben-817f19c816

Legal Clause Risk Spotter

Skill

Guides legal professionals in identifying risk patterns in key contract clauses with checklists, issue prompts, and escalation criteria for review support.

---
slug: legal-clause-risk-spotter
version: "1.0.0"
type: descriptive
language: en
---

# Legal Clause Risk Spotter

## Overview

Guides reviewers through identifying common risk patterns in clauses such as indemnity, liability, termination, IP, confidentiality, and governing law. This is a descriptive OpenClaw skill for legal-industry workflow support. It provides structured frameworks, checklists, templates, and issue-spotting prompts. It does not execute code, call external APIs, access legal databases, retrieve court records, automate filings, or perform legal services.

## When to Use

- Screening a draft agreement for risk
- Training junior reviewers
- Preparing a clause issue list

## Target Users

- Lawyers
- Contract managers
- Legal operations professionals

## Inputs to Collect

## Core Modules

1. **High-risk clause taxonomy** — provides structured prompts, checklists, and review fields for this area.
2. **Clause-by-clause issue prompts** — provides structured prompts, checklists, and review fields for this area.
3. **Business impact notes** — provides structured prompts, checklists, and review fields for this area.
4. **Fallback language considerations** — provides structured prompts, checklists, and review fields for this area.
5. **Escalation criteria** — provides structured prompts, checklists, and review fields for this area.

## Workflow

## Expected Outputs

- Clause risk checklist
- Issue spotting matrix
- Escalation notes

## Example Prompts

- "Spot risks I should check in an indemnity clause."
- "Create a clause risk checklist for a master services agreement."

## Safety and Legal Limitations

- This skill provides informational workflow support only and is not legal advice.
- It does not create an attorney-client relationship and does not replace review by a qualified attorney.
- Laws, court rules, deadlines, ethics duties, privilege, confidentiality, and professional responsibility rules vary by jurisdiction and matter.
- Users must verify all legal authorities, filing requirements, deadlines, facts, citations, and strategic decisions with qualified counsel.
- The skill must not be used to fabricate evidence, coach false testimony, evade regulation, access data unlawfully, or bypass confidentiality obligations.
- Specific limitation for this skill: Does not rewrite binding legal terms automatically; suggested considerations require attorney review.

## Acceptance Criteria

FILE:ACCEPTANCE.md
# Acceptance Criteria

## Package Rules

FILE:README.md
# Legal Clause Risk Spotter

Guides reviewers through identifying common risk patterns in clauses such as indemnity, liability, termination, IP, confidentiality, and governing law.

## What This Skill Does

## Core Modules

- High-risk clause taxonomy
- Clause-by-clause issue prompts
- Business impact notes
- Fallback language considerations
- Escalation criteria

## Trigger Keywords

clause risk, indemnity checklist, liability cap, contract clauses, legal-clause-risk-spotter, legal clause risk spotter

## Example Prompts

- "Spot risks I should check in an indemnity clause."
- "Create a clause risk checklist for a master services agreement."

## Outputs

- Clause risk checklist
- Issue spotting matrix
- Escalation notes

## Safety

Informational support only. Not legal advice. Does not replace qualified attorney review, jurisdiction-specific research, ethics analysis, or professional judgment.

FILE:skill.json
{
"name": "Legal Clause Risk Spotter",
"slug": "legal-clause-risk-spotter",
"version": "1.0.0",
"description": "Guides reviewers through identifying common risk patterns in clauses such as indemnity, liability, termination, IP, confidentiality, and governing law.",
"author": "Pearl Team (OpenClaw)",
"tags": [
"legal",
"contracts",
"clause-analysis",
"risk",
"descriptive"
],
"trigger_keywords": [
"clause risk",
"indemnity checklist",
"liability cap",
"contract clauses",
"legal-clause-risk-spotter",
"legal clause risk spotter"
],
"language": "en",
"outputs": "markdown",
"requires_api": false,
"readiness": "stable",
"type": "descriptive",
"legal_disclaimer": "Informational workflow support only; not legal advice."
}

ClawHub Data Analysis Research+2

H@clawhub-harrylabsj-35a31b2850

Legal Contract Review Playbook

Skill

Provides structured frameworks, checklists, and templates to support legal contract review, risk identification, and stakeholder summaries without offering l...

---
slug: legal-contract-review-playbook
version: "1.0.0"
type: descriptive
language: en
---

# Legal Contract Review Playbook

## Overview

Provides a structured contract review workflow covering parties, obligations, risk allocation, remedies, and negotiation notes. This is a descriptive OpenClaw skill for legal-industry workflow support. It provides structured frameworks, checklists, templates, and issue-spotting prompts. It does not execute code, call external APIs, access legal databases, retrieve court records, automate filings, or perform legal services.

## When to Use

- Reviewing commercial contracts
- Preparing markup notes
- Summarizing contractual risks for stakeholders

## Target Users

- Contract attorneys
- In-house counsel
- Procurement legal teams
- Business reviewers

## Inputs to Collect

## Core Modules

1. **Contract metadata capture** — provides structured prompts, checklists, and review fields for this area.
2. **Key obligation map** — provides structured prompts, checklists, and review fields for this area.
3. **Risk clause checklist** — provides structured prompts, checklists, and review fields for this area.
4. **Fallback position notes** — provides structured prompts, checklists, and review fields for this area.
5. **Executive summary template** — provides structured prompts, checklists, and review fields for this area.

## Workflow

## Expected Outputs

- Contract review checklist
- Issue list
- Negotiation note template
- Stakeholder summary

## Example Prompts

- "Give me a contract review checklist for a SaaS agreement."
- "Help structure a risk summary for this vendor contract."

## Safety and Legal Limitations

- This skill provides informational workflow support only and is not legal advice.
- It does not create an attorney-client relationship and does not replace review by a qualified attorney.
- Laws, court rules, deadlines, ethics duties, privilege, confidentiality, and professional responsibility rules vary by jurisdiction and matter.
- Users must verify all legal authorities, filing requirements, deadlines, facts, citations, and strategic decisions with qualified counsel.
- The skill must not be used to fabricate evidence, coach false testimony, evade regulation, access data unlawfully, or bypass confidentiality obligations.
- Specific limitation for this skill: Framework only; not a substitute for jurisdiction-specific legal review or attorney judgment.

## Acceptance Criteria

FILE:ACCEPTANCE.md
# Acceptance Criteria

## Package Rules

FILE:README.md
# Legal Contract Review Playbook

Provides a structured contract review workflow covering parties, obligations, risk allocation, remedies, and negotiation notes.

## What This Skill Does

## Core Modules

- Contract metadata capture
- Key obligation map
- Risk clause checklist
- Fallback position notes
- Executive summary template

## Trigger Keywords

contract review, agreement checklist, vendor contract, SaaS agreement, legal-contract-review-playbook, legal contract review playbook

## Example Prompts

- "Give me a contract review checklist for a SaaS agreement."
- "Help structure a risk summary for this vendor contract."

## Outputs

- Contract review checklist
- Issue list
- Negotiation note template
- Stakeholder summary

## Safety

Informational support only. Not legal advice. Does not replace qualified attorney review, jurisdiction-specific research, ethics analysis, or professional judgment.

FILE:skill.json
{
"name": "Legal Contract Review Playbook",
"slug": "legal-contract-review-playbook",
"version": "1.0.0",
"description": "Provides a structured contract review workflow covering parties, obligations, risk allocation, remedies, and negotiation notes.",
"author": "Pearl Team (OpenClaw)",
"tags": [
"legal",
"contracts",
"review",
"commercial",
"descriptive"
],
"trigger_keywords": [
"contract review",
"agreement checklist",
"vendor contract",
"SaaS agreement",
"legal-contract-review-playbook",
"legal contract review playbook"
],
"language": "en",
"outputs": "markdown",
"requires_api": false,
"readiness": "stable",
"type": "descriptive",
"legal_disclaimer": "Informational workflow support only; not legal advice."
}

ClawHub Data Analysis Research+2

H@clawhub-harrylabsj-35a31b2850

Legal Matter Triage Framework

Skill

Provides structured frameworks and checklists to help legal teams triage matters by urgency, risk, deadlines, forum, and expertise without providing legal ad...

---
slug: legal-matter-triage-framework
version: "1.0.0"
type: descriptive
language: en
---

# Legal Matter Triage Framework

## Overview

Helps legal teams triage incoming matters by urgency, risk, deadlines, forum, and required expertise. This is a descriptive OpenClaw skill for legal-industry workflow support. It provides structured frameworks, checklists, templates, and issue-spotting prompts. It does not execute code, call external APIs, access legal databases, retrieve court records, automate filings, or perform legal services.

## When to Use

- Sorting a queue of new requests
- Prioritizing legal work
- Escalating high-risk matters

## Target Users

- In-house counsel
- Law firm associates
- Legal operations teams

## Inputs to Collect

## Core Modules

1. **Urgency/risk scoring** — provides structured prompts, checklists, and review fields for this area.
2. **Deadline and statute capture** — provides structured prompts, checklists, and review fields for this area.
3. **Practice-area routing** — provides structured prompts, checklists, and review fields for this area.
4. **Privilege/confidentiality caution points** — provides structured prompts, checklists, and review fields for this area.
5. **Next-action plan** — provides structured prompts, checklists, and review fields for this area.

## Workflow

## Expected Outputs

- Matter priority matrix
- Escalation recommendations
- Initial next-step checklist

## Example Prompts

- "Triage these five incoming legal requests by urgency and risk."
- "Create a triage rubric for an in-house legal helpdesk."

## Safety and Legal Limitations

- This skill provides informational workflow support only and is not legal advice.
- It does not create an attorney-client relationship and does not replace review by a qualified attorney.
- Laws, court rules, deadlines, ethics duties, privilege, confidentiality, and professional responsibility rules vary by jurisdiction and matter.
- Users must verify all legal authorities, filing requirements, deadlines, facts, citations, and strategic decisions with qualified counsel.
- The skill must not be used to fabricate evidence, coach false testimony, evade regulation, access data unlawfully, or bypass confidentiality obligations.
- Specific limitation for this skill: Does not decide legal rights or deadlines; users must verify all dates and legal requirements with qualified counsel.

## Acceptance Criteria

FILE:ACCEPTANCE.md
# Acceptance Criteria

## Package Rules

FILE:README.md
# Legal Matter Triage Framework

Helps legal teams triage incoming matters by urgency, risk, deadlines, forum, and required expertise.

## What This Skill Does

## Core Modules

- Urgency/risk scoring
- Deadline and statute capture
- Practice-area routing
- Privilege/confidentiality caution points
- Next-action plan

## Trigger Keywords

matter triage, legal request prioritization, legal helpdesk, risk scoring, legal-matter-triage-framework, legal matter triage framework

## Example Prompts

- "Triage these five incoming legal requests by urgency and risk."
- "Create a triage rubric for an in-house legal helpdesk."

## Outputs

- Matter priority matrix
- Escalation recommendations
- Initial next-step checklist

## Safety

Informational support only. Not legal advice. Does not replace qualified attorney review, jurisdiction-specific research, ethics analysis, or professional judgment.

FILE:skill.json
{
"name": "Legal Matter Triage Framework",
"slug": "legal-matter-triage-framework",
"version": "1.0.0",
"description": "Helps legal teams triage incoming matters by urgency, risk, deadlines, forum, and required expertise.",
"author": "Pearl Team (OpenClaw)",
"tags": [
"legal",
"triage",
"legal-ops",
"risk",
"descriptive"
],
"trigger_keywords": [
"matter triage",
"legal request prioritization",
"legal helpdesk",
"risk scoring",
"legal-matter-triage-framework",
"legal matter triage framework"
],
"language": "en",
"outputs": "markdown",
"requires_api": false,
"readiness": "stable",
"type": "descriptive",
"legal_disclaimer": "Informational workflow support only; not legal advice."
}

ClawHub Data Analysis Research+2

H@clawhub-harrylabsj-35a31b2850

Discord Task Tracker

Skill

Track tasks in Discord using natural language. Add, list, complete, and delete tasks via chat commands. Triggers: add task, track task, todo, my tasks, task...

---
name: discord-task-tracker
description: "Track tasks in Discord using natural language. Add, list, complete, and delete tasks via chat commands. Triggers: add task, track task, todo, my tasks, task list, complete task, delete task, task done"
---

# Discord Task Tracker

Track your tasks directly from Discord with natural language commands.

## Commands

| Command | Description |
|---------|-------------|
| `add task <description>` | Add a new task |
| `list tasks` / `my tasks` / `task list` | Show all tasks |
| `complete task <task number>` | Mark a task as done |
| `delete task <task number>` | Remove a task |

## Examples

```
add task Finish the Discord bot integration
list tasks
complete task 1
delete task 2
```

## How It Works

- Tasks are stored in `tasks.json` in the skill directory
- Task numbers are assigned sequentially; use `list tasks` to see current numbers
- Completed tasks are removed from the list
- All task operations reply directly in the Discord channel

FILE:references/commands.md
# Command Reference — Discord Task Tracker

## Syntax

All commands are natural language phrases. Run via:

```
uv run python scripts/task_manager.py "<command>"
```

## Commands

### Add a task
```
add task <description>
track task <description>
todo <description>
```
**Example:** `add task Finish the Discord integration`

### List all tasks
```
list tasks
my tasks
task list
```
Shows numbered task list with status indicators:
- ⬜ = pending
- ✅ = completed (auto-removed after completion)

### Complete a task
```
complete task <number>
task done <number>
done <number>
```
**Example:** `complete task 1`

### Delete a task
```
delete task <number>
```
**Example:** `delete task 2`

## Task Storage

- File: `tasks.json` in the skill directory
- Format: JSON array of `{"id": N, "text": "...", "done": bool}` objects
- Task IDs are sequential and may shift after deletions/completions

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error (task not found, unknown command) |

FILE:scripts/task_manager.py
#!/usr/bin/env python3
"""
Discord Task Tracker - Manage tasks via Discord chat commands.
Reads command from stdin/args, manages tasks in tasks.json, outputs response.
"""

import sys
import json
import os
from pathlib import Path

# Ensure UTF-8 output on Windows
if sys.platform == "win32":
    import io
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")

SKILL_DIR = Path(__file__).parent.parent
TASKS_FILE = SKILL_DIR / "tasks.json"


def load_tasks():
    if TASKS_FILE.exists():
        with open(TASKS_FILE, "r", encoding="utf-8") as f:
            return json.load(f)
    return []


def save_tasks(tasks):
    with open(TASKS_FILE, "w", encoding="utf-8") as f:
        json.dump(tasks, f, indent=2)


def cmd_add(text):
    tasks = load_tasks()
    task_id = len(tasks) + 1
    tasks.append({"id": task_id, "text": text.strip(), "done": False})
    save_tasks(tasks)
    print(f"✅ Task added (#{task_id}): {text.strip()}")


def cmd_list():
    tasks = load_tasks()
    if not tasks:
        print("📋 No tasks yet. Say 'add task <description>' to create one.")
        return
    lines = ["**📋 Your Tasks:**"]
    for t in tasks:
        status = "✅" if t["done"] else "⬜"
        lines.append(f"  {status} `[{t['id']}]` {t['text']}")
    print("\n".join(lines))


def cmd_complete(task_id):
    tasks = load_tasks()
    task = next((t for t in tasks if t["id"] == int(task_id)), None)
    if not task:
        print(f"❌ Task #{task_id} not found.")
        return
    task["done"] = True
    save_tasks(tasks)
    # Remove completed task
    tasks = [t for t in tasks if not (t["id"] == int(task_id))]
    save_tasks(tasks)
    print(f"✅ Task #{task_id} completed and removed: {task['text']}")


def cmd_delete(task_id):
    tasks = load_tasks()
    task = next((t for t in tasks if t["id"] == int(task_id)), None)
    if not task:
        print(f"❌ Task #{task_id} not found.")
        return
    tasks = [t for t in tasks if t["id"] != int(task_id)]
    save_tasks(tasks)
    print(f"🗑️ Task #{task_id} deleted: {task['text']}")


def main():
    # Read full input (can be passed via stdin or args)
    raw = ""
    if len(sys.argv) > 1:
        raw = " ".join(sys.argv[1:])
    else:
        raw = sys.stdin.read().strip()

    raw = raw.strip()
    if not raw:
        print("Usage: task_manager.py <command>")
        sys.exit(1)

    lower = raw.lower()

    # add task <text>
    if lower.startswith("add task ") or lower.startswith("track task ") or lower.startswith("todo "):
        text = raw.split(" ", 2)[-1]
        cmd_add(text)
    # list tasks / my tasks / task list
    elif lower in ("list tasks", "my tasks", "task list", "list", "tasks"):
        cmd_list()
    # complete task <id>
    elif lower.startswith("complete task ") or lower.startswith("task done ") or lower.startswith("done "):
        parts = raw.split()
        if len(parts) >= 2:
            cmd_complete(parts[-1])
        else:
            print("❌ Usage: complete task <task number>")
    # delete task <id>
    elif lower.startswith("delete task "):
        parts = raw.split()
        if len(parts) >= 2:
            cmd_delete(parts[-1])
        else:
            print("❌ Usage: delete task <task number>")
    else:
        print("Unknown command. Use: add task <text>, list tasks, complete task <#>, delete task <#>")


if __name__ == "__main__":
    main()

FILE:tasks.json
[
  {
    "id": 1,
    "text": "Test task from CLI",
    "done": false
  },
  {
    "id": 2,
    "text": "Test task from CLI",
    "done": false
  }
]

ClawHub Coding Testing+2

F@clawhub-fuzzyb33s-5ee8c7baf7

Game Dev Time Estimator

Skill

Help a beginner or early-stage game team estimate the likely development time for a game concept based on scope, target milestone, current team, skill covera...

---
name: game-dev-time-estimator
description: Help a beginner or early-stage game team estimate the likely development time for a game concept based on scope, target milestone, current team, skill coverage, work model, and production constraints. Use when someone asks how long a game might take, whether their current team can hit a target date, what timeline range they should expect for a prototype, vertical slice, release, or live F2P project, or how missing roles and part-time availability change development time. Ask for missing information when concept, team, scope, or staffing assumptions are unclear, then provide a rough timeline range, main schedule drivers, hidden time sinks, and ways to shorten the path.
---

# Game Dev Time Estimator

Estimate likely timeline ranges, not fake precision.

Use this skill when the user needs a practical schedule read on a game concept, milestone, or team setup. The goal is to help beginners understand which assumptions drive time, what the current team can realistically deliver, where hidden schedule drag comes from, and how scope choices affect duration.

Read `references/time-drivers.md` when you need a checklist of the main things that push timelines up or down.
Read `references/estimation-modes.md` when the user has not provided enough team detail or when you need to switch into scenario mode.

## Core behavior

- Keep the language simple and non-jargony.
- Ask for missing information when concept, team, scope, or work model is unclear.
- Give ranges, not fake precise delivery dates.
- Explain assumptions clearly.
- Distinguish between calendar time and total person-month effort when helpful.
- Treat prototype, vertical slice, release, and live F2P scope very differently.
- Ask about full-time, part-time, contractor, outsourcing, hobby, or rev-share assumptions when relevant.
- Ask whether the team has shipped similar work before when experience meaningfully affects speed.
- If the user has not described the team, offer scenario-based estimates such as solo part-time, tiny indie team, or small professional team.
- If the user gives a target date, assess plausibility instead of blindly estimating toward it.

## What to ask first

Prioritize these questions:
1. What is the game concept in plain language?
2. What is the target platform?
3. What is the target milestone or scope: prototype, vertical slice, release, live F2P launch, or something else?
4. Who is already on the team?
5. What can each person actually do well?
6. Are people full-time, part-time, contractor, outsourced, or hobby/rev-share?
7. Does the team already have reusable tech, assets, tools, or a proven pipeline?
8. Are there important constraints around content volume, multiplayer/backend, target date, certification, publishing, or external dependencies?

If key information is missing, ask 2 to 5 focused questions. If the user wants a fast estimate, state assumptions and continue.

## What to diagnose

Quickly identify:
- the main time drivers for this concept
- whether schedule risk comes mostly from implementation, content production, coordination, polish, or approvals
- what the current team can do in parallel versus what is bottlenecked through one person
- what missing disciplines will slow progress even if they do not add much direct budget
- whether the user is underestimating iteration, QA, UI, content integration, platform prep, or online/live-service time
- whether the milestone is realistic for the stated team and availability
- whether the user is confusing best-case build time with realistic calendar time

## Common time sinks to consider

Do not always list all of these. Only raise what matters.

- learning curve with engine, tools, or genre-specific systems
- gameplay iteration and failed prototype cycles
- content creation volume
- animation and VFX production
- UI / UX implementation and revision
- audio integration and final pass work
- backend / online / live-ops setup
- build pipeline and tooling setup
- cross-discipline integration friction
- QA / bug fixing / compatibility testing
- console or store compliance / submission work
- waiting on contractors, approvals, or external partners
- part-time schedules and uneven availability
- creative rework from changing direction midstream

## Response structure

Always organize the answer using this structure.

### Project Snapshot
- one short summary of the game and milestone
- one sentence on what kind of timeline shape this project usually has

### Assumptions
- scope assumptions
- team assumptions
- availability assumptions
- tooling / pipeline assumptions
- timeline constraints if relevant

### Main Schedule Drivers
- list the top factors driving time for this project
- explain why they matter here

### What the Current Team Can Parallelize
- explain what can move simultaneously
- identify bottlenecks or single-threaded work
- distinguish fully covered from partly covered

### Likely Hidden Time Sinks
- list schedule drag the project probably still faces
- explain which are must-plan-for versus optional risk buffers

### Rough Time Range
- low case
- expected case
- high case
- short explanation of what changes between them

### Ways to Shorten the Timeline
- scope cuts
- milestone reduction
- art/style simplification
- fewer platforms
- fewer online dependencies
- better reuse of tools, assets, middleware, or contractors where sensible
- more realistic sequencing and fewer parallel workstreams when coordination overhead is hurting

### Best Next Steps
- give 3 to 5 concrete actions
- at least one should be something the user can do today

## Estimation modes

### Team-known mode
Use when the user described the team.
- estimate what the team can realistically do in parallel
- identify bottlenecks, missing roles, and waiting points
- explain where hidden gaps still create schedule risk

### Team-unknown mode
Use when the user did not describe the team.
- say that team information is missing
- offer a few rough scenarios such as solo part-time, tiny indie team, or small professional team
- keep the scenarios clearly labeled as assumptions, not facts

### Target-date mode
Use when the user asks whether they can hit a deadline.
- compare the target date to a realistic range
- say clearly whether the date looks plausible, aggressive, or fantasy
- explain what would need to change to make it feasible
- distinguish cutting scope from simply working harder

### Milestone-specific mode
Adjust strongly by milestone:
- **Prototype**: low polish, placeholder-heavy, learning-focused, iteration-heavy
- **Vertical slice**: stronger presentation, UX, polish, and cross-discipline quality bar
- **Release**: much broader production, QA, content, business, and platform-readiness burden
- **Live F2P / online**: higher ongoing time needs for backend, analytics, economy tuning, content cadence, support, and operations

## Scope sensitivity

Call out these common schedule traps when relevant:
- assuming part-time work compresses calendar time more than it actually does
- assuming a vertical slice schedule scales linearly into full production
- ignoring iteration and rework time
- forgetting UI, audio, QA, and integration passes
- underestimating content production and polish time
- treating existing team members as if they cover roles they only partly cover
- assuming adding people always makes things faster even when onboarding and coordination slow things down
- forgetting submission, approvals, localization, or store-readiness work near the end

## Style guidance

- Be practical and transparent.
- Do not pretend the estimate is precise.
- Give directional confidence, not fake production certainty.
- If the project sounds under-timed, say so directly.
- If the timeline could become realistic through scope cuts, explain how.
- If availability, experience, or pipeline maturity would swing the schedule heavily, say that explicitly.

## Fast mode

Use this compressed flow when the user wants a quick answer:
- what are you making
- what milestone are you targeting
- who is on the team
- how available are they
- what is most likely to slow this down
- what timeline range is plausible
- how could the timeline be shortened

## Working principle

A useful early time estimate is not a fake launch date. It is a clear explanation of which assumptions are creating schedule risk, what the team can actually do in parallel, and where the biggest hidden delays are likely to appear.

FILE:references/estimation-modes.md
# Estimation Modes

Use this file when the user input is incomplete, when you need scenario framing, or when a deadline plausibility check is more useful than a generic estimate.

## 1. Team-known mode

Use when the user described the team with at least rough role and availability detail.

Focus on:
- what can happen in parallel
- which workstreams bottleneck through one person
- where missing coverage creates waiting time
- how experience level changes speed

Good output pattern:
- current team summary
- likely parallel work
- likely bottlenecks
- low / expected / high schedule range
- what would shorten the schedule

## 2. Team-unknown mode

Use when team information is missing.

Offer labeled scenarios such as:
- solo part-time beginner
- solo full-time experienced developer
- tiny indie team with mixed skills
- small professional team with solid coverage

Keep scenario names plain and clearly hypothetical.
Do not imply the user actually has that team.

## 3. Target-date mode

Use when the user asks something like:
- can we do this in 6 months?
- could this ship by next summer?
- is this realistic by Q4?

Approach:
1. estimate a realistic range first
2. compare the requested deadline against that range
3. label the deadline as plausible, aggressive, or unrealistic
4. explain what must change to make it plausible

Prefer language like:
- plausible if scope stays tight
- possible but aggressive
- unrealistic without major cuts
- fantasy unless the milestone is redefined

## 4. Milestone mode

Shift the estimate based on what the user is actually trying to reach.

### Prototype
- optimize for learning speed
- assume placeholder assets
- include iteration and failed experiments

### Vertical slice
- assume one polished representative slice
- raise the bar for UX, art consistency, and polish
- include more integration and presentation work

### Release
- include content breadth, QA, stability, business readiness, and endgame finishing work

### Live F2P / online
- include backend, telemetry, balancing cadence, support needs, and operational readiness

## 5. Confidence language

Use confidence language instead of pretending the estimate is exact.

Examples:
- high uncertainty because team details are missing
- moderate confidence if the team has shipped similar work
- low confidence because content scope is still undefined
- confidence would improve a lot after a prototype or feature list cut

FILE:references/time-drivers.md
# Time Drivers

Use this file when you need a quick checklist of what usually stretches or compresses game development timelines.

## Biggest timeline multipliers

### Scope shape
- Number of core systems
- Content volume
- Number of playable characters, levels, enemies, modes, or biomes
- Required polish level
- Number of target platforms
- Online or live-service requirements

### Team shape
- Solo versus duo versus small team
- Full-time versus part-time availability
- Seniority and prior shipped experience
- Whether key disciplines are missing
- How much work bottlenecks through one person
- Coordination overhead once multiple people depend on each other

### Production maturity
- Existing codebase or prototype reuse
- Existing art style, asset library, or outsourcing pipeline
- Familiarity with engine and tools
- Build pipeline and testing maturity
- Clarity of design versus likely rework rate

### Technical difficulty
- Multiplayer / netcode / backend
- Procedural systems or AI-heavy behavior
- Cross-platform optimization
- Save systems, economy, progression, analytics
- Platform-specific certification or compliance constraints

### Content burden
- High-volume authored content
- Animation workload
- Narrative and localization load
- UX flow complexity
- Audio implementation and iteration

## Fast heuristics

Use these as rough reasoning aids, not formulas.

- A prototype often spends more time on learning and iteration than on polish.
- A vertical slice often takes longer than beginners expect because presentation quality rises sharply.
- A release schedule usually grows non-linearly versus a prototype because content, QA, and stability work expand fast.
- Online and live F2P scope usually add both upfront setup time and recurring operational time.
- Part-time teams usually lose time not just from fewer hours but from context-switching and slower feedback loops.
- Adding people helps only when work can be split cleanly and the pipeline is already organized.

## Common hidden delays

Raise these when the user sounds overly optimistic.

- tool learning
- prototype restarts
- waiting on art, UI, or audio handoff
- bug fixing late in production
- integration passes between disciplines
- store submission prep
- performance optimization
- platform-specific fixes
- contractor lag or revision rounds
- changing direction after playtests

## Questions that improve the estimate

Ask only the ones that matter.

1. Is this a prototype, vertical slice, release, or live service launch?
2. How many people are actually working on it, and how available are they?
3. Which disciplines are truly covered in-house?
4. Is the game content-light or content-hungry?
5. Is there multiplayer, backend, or live operations?
6. Is there existing tech or a mature pipeline to reuse?
7. Is there a target date that is driving decisions?

ClawHub Testing Design+2

S@clawhub-stanestane-85fbf0a896

Jira Expert.Old

Skill

Atlassian Jira expert for creating and managing projects, planning, product discovery, JQL queries, workflows, custom fields, automation, reporting, and all...

---
name: "jira-expert"
description: Atlassian Jira expert for creating and managing projects, planning, product discovery, JQL queries, workflows, custom fields, automation, reporting, and all Jira features. Use for Jira project setup, configuration, advanced search, dashboard creation, workflow design, and technical Jira operations.
---

# Atlassian Jira Expert

Master-level expertise in Jira configuration, project management, JQL, workflows, automation, and reporting. Handles all technical and operational aspects of Jira.

## Quick Start — Most Common Operations

**Create a project**:
```
mcp jira create_project --name "My Project" --key "MYPROJ" --type scrum --lead "[email protected]"
```

**Run a JQL query**:
```
mcp jira search_issues --jql "project = MYPROJ AND status != Done AND dueDate < now()" --maxResults 50
```

For full command reference, see [Atlassian MCP Integration](#atlassian-mcp-integration). For JQL functions, see [JQL Functions Reference](#jql-functions-reference). For report templates, see [Reporting Templates](#reporting-templates).

---

## Workflows

### Project Creation
1. Determine project type (Scrum, Kanban, Bug Tracking, etc.)
2. Create project with appropriate template
3. Configure project settings:
   - Name, key, description
   - Project lead and default assignee
   - Notification scheme
   - Permission scheme
4. Set up issue types and workflows
5. Configure custom fields if needed
6. Create initial board/backlog view
7. **HANDOFF TO**: Scrum Master for team onboarding

### Workflow Design
1. Map out process states (To Do → In Progress → Done)
2. Define transitions and conditions
3. Add validators, post-functions, and conditions
4. Configure workflow scheme
5. **Validate**: Deploy to a test project first; verify all transitions, conditions, and post-functions behave as expected before associating with production projects
6. Associate workflow with project
7. Test workflow with sample issues

### JQL Query Building
**Basic Structure**: `field operator value`

**Common Operators**:
- `=, !=` : equals, not equals
- `~, !~` : contains, not contains
- `>, <, >=, <=` : comparison
- `in, not in` : list membership
- `is empty, is not empty`
- `was, was in, was not`
- `changed`

**Powerful JQL Examples**:

Find overdue issues:
```jql
dueDate < now() AND status != Done
```

Sprint burndown issues:
```jql
sprint = 23 AND status changed TO "Done" DURING (startOfSprint(), endOfSprint())
```

Find stale issues:
```jql
updated < -30d AND status != Done
```

Cross-project epic tracking:
```jql
"Epic Link" = PROJ-123 ORDER BY rank
```

Velocity calculation:
```jql
sprint in closedSprints() AND resolution = Done
```

Team capacity:
```jql
assignee in (user1, user2) AND sprint in openSprints()
```

### Dashboard Creation
1. Create new dashboard (personal or shared)
2. Add relevant gadgets:
   - Filter Results (JQL-based)
   - Sprint Burndown
   - Velocity Chart
   - Created vs Resolved
   - Pie Chart (status distribution)
3. Arrange layout for readability
4. Configure automatic refresh
5. Share with appropriate teams
6. **HANDOFF TO**: Senior PM or Scrum Master for use

### Automation Rules
1. Define trigger (issue created, field changed, scheduled)
2. Add conditions (if applicable)
3. Define actions:
   - Update field
   - Send notification
   - Create subtask
   - Transition issue
   - Post comment
4. Test automation with sample data
5. Enable and monitor

## Advanced Features

### Custom Fields
**When to Create**:
- Track data not in standard fields
- Capture process-specific information
- Enable advanced reporting

**Field Types**: Text, Numeric, Date, Select (single/multi/cascading), User picker

**Configuration**:
1. Create custom field
2. Configure field context (which projects/issue types)
3. Add to appropriate screens
4. Update search templates if needed

### Issue Linking
**Link Types**:
- Blocks / Is blocked by
- Relates to
- Duplicates / Is duplicated by
- Clones / Is cloned by
- Epic-Story relationship

**Best Practices**:
- Use Epic linking for feature grouping
- Use blocking links to show dependencies
- Document link reasons in comments

### Permissions & Security

**Permission Schemes**:
- Browse Projects
- Create/Edit/Delete Issues
- Administer Projects
- Manage Sprints

**Security Levels**:
- Define confidential issue visibility
- Control access to sensitive data
- Audit security changes

### Bulk Operations
**Bulk Change**:
1. Use JQL to find target issues
2. Select bulk change operation
3. Choose fields to update
4. **Validate**: Preview all changes before executing; confirm the JQL filter matches only intended issues — bulk edits are difficult to reverse
5. Execute and confirm
6. Monitor background task

**Bulk Transitions**:
- Move multiple issues through workflow
- Useful for sprint cleanup
- Requires appropriate permissions
- **Validate**: Run the JQL filter and review results in small batches before applying at scale

## JQL Functions Reference

> **Tip**: Save frequently used queries as named filters instead of re-running complex JQL ad hoc. See [Best Practices](#best-practices) for performance guidance.

**Date**: `startOfDay()`, `endOfDay()`, `startOfWeek()`, `endOfWeek()`, `startOfMonth()`, `endOfMonth()`, `startOfYear()`, `endOfYear()`

**Sprint**: `openSprints()`, `closedSprints()`, `futureSprints()`

**User**: `currentUser()`, `membersOf("group")`

**Advanced**: `issueHistory()`, `linkedIssues()`, `issuesWithFixVersions()`

## Reporting Templates

> **Tip**: These JQL snippets can be saved as shared filters or wired directly into Dashboard gadgets (see [Dashboard Creation](#dashboard-creation)).

| Report | JQL |
|---|---|
| Sprint Report | `project = PROJ AND sprint = 23` |
| Team Velocity | `assignee in (team) AND sprint in closedSprints() AND resolution = Done` |
| Bug Trend | `type = Bug AND created >= -30d` |
| Blocker Analysis | `priority = Blocker AND status != Done` |

## Decision Framework

**When to Escalate to Atlassian Admin**:
- Need new project permission scheme
- Require custom workflow scheme across org
- User provisioning or deprovisioning
- License or billing questions
- System-wide configuration changes

**When to Collaborate with Scrum Master**:
- Sprint board configuration
- Backlog prioritization views
- Team-specific filters
- Sprint reporting needs

**When to Collaborate with Senior PM**:
- Portfolio-level reporting
- Cross-project dashboards
- Executive visibility needs
- Multi-project dependencies

## Handoff Protocols

**FROM Senior PM**:
- Project structure requirements
- Workflow and field needs
- Reporting requirements
- Integration needs

**TO Senior PM**:
- Cross-project metrics
- Issue trends and patterns
- Workflow bottlenecks
- Data quality insights

**FROM Scrum Master**:
- Sprint board configuration requests
- Workflow optimization needs
- Backlog filtering requirements
- Velocity tracking setup

**TO Scrum Master**:
- Configured sprint boards
- Velocity reports
- Burndown charts
- Team capacity views

## Best Practices

**Data Quality**:
- Enforce required fields with field validation rules
- Use consistent issue key naming conventions per project type
- Schedule regular cleanup of stale/orphaned issues

**Performance**:
- Avoid leading wildcards in JQL (`~` on large text fields is expensive)
- Use saved filters instead of re-running complex JQL ad hoc
- Limit dashboard gadgets to reduce page load time
- Archive completed projects rather than deleting to preserve history

**Governance**:
- Document rationale for custom workflow states and transitions
- Version-control permission/workflow schemes before making changes
- Require change management review for org-wide scheme updates
- Run permission audits after user role changes

## Atlassian MCP Integration

**Primary Tool**: Jira MCP Server

**Key Operations with Example Commands**:

Create a project:
```
mcp jira create_project --name "My Project" --key "MYPROJ" --type scrum --lead "[email protected]"
```

Execute a JQL query:
```
mcp jira search_issues --jql "project = MYPROJ AND status != Done AND dueDate < now()" --maxResults 50
```

Update an issue field:
```
mcp jira update_issue --issue "MYPROJ-42" --field "status" --value "In Progress"
```

Create a sprint:
```
mcp jira create_sprint --board 10 --name "Sprint 5" --startDate "2024-06-01" --endDate "2024-06-14"
```

Create a board filter:
```
mcp jira create_filter --name "Open Blockers" --jql "priority = Blocker AND status != Done" --shareWith "project-team"
```

**Integration Points**:
- Pull metrics for Senior PM reporting
- Configure sprint boards for Scrum Master
- Create documentation pages for Confluence Expert
- Support template creation for Template Creator

## Related Skills

- **Confluence Expert** (`project-management/confluence-expert/`) — Documentation complements Jira workflows
- **Atlassian Admin** (`project-management/atlassian-admin/`) — Permission and user management for Jira projects

FILE:references/automation-examples.md
# Jira Automation Examples

## Auto-Assignment Rules

### Auto-assign by component
**Trigger:** Issue created
**Conditions:**
- Component is not EMPTY
**Actions:**
- Assign issue to component lead

### Auto-assign to reporter for feedback
**Trigger:** Issue transitioned to "Waiting for Feedback"
**Actions:**
- Assign issue to reporter
- Add comment: "Please provide additional information"

### Round-robin assignment
**Trigger:** Issue created
**Conditions:**
- Project = ABC
- Assignee is EMPTY
**Actions:**
- Assign to next team member in rotation (use smart value)

---

## Status Sync Rules

### Sync subtask status to parent
**Trigger:** Issue transitioned
**Conditions:**
- Issue type = Sub-task
- Transition is to "Done"
- Parent issue exists
- All subtasks are Done
**Actions:**
- Transition parent issue to "Done"

### Sync parent to subtasks
**Trigger:** Issue transitioned
**Conditions:**
- Issue type has subtasks
- Transition is to "Cancelled"
**Actions:**
- For each: Sub-tasks
  - Transition issue to "Cancelled"

### Epic progress tracking
**Trigger:** Issue transitioned
**Conditions:**
- Epic link is not EMPTY
- Transition is to "Done"
**Actions:**
- Add comment to epic: "{{issue.key}} completed"
- Update epic custom field "Progress"

---

## Notification Rules

### Slack notification for high-priority bugs
**Trigger:** Issue created
**Conditions:**
- Issue type = Bug
- Priority IN (Highest, High)
**Actions:**
- Send Slack message to #engineering:
  ```
  🚨 High Priority Bug Created
  {{issue.key}}: {{issue.summary}}
  Reporter: {{issue.reporter.displayName}}
  Priority: {{issue.priority.name}}
  {{issue.url}}
  ```

### Email assignee when mentioned
**Trigger:** Issue commented
**Conditions:**
- Comment contains @mention of assignee
**Actions:**
- Send email to {{issue.assignee.emailAddress}}:
  ```
  Subject: You were mentioned in {{issue.key}}
  Body: {{comment.author.displayName}} mentioned you:
  {{comment.body}}
  ```

### SLA breach warning
**Trigger:** Scheduled - Every hour
**Conditions:**
- Status != Done
- SLA time remaining < 2 hours
**Actions:**
- Send email to {{issue.assignee}}
- Add comment: "⚠️ SLA expires in <2 hours"
- Set priority to Highest

---

## Field Automation Rules

### Auto-set due date
**Trigger:** Issue created
**Conditions:**
- Issue type = Bug
- Priority = Highest
**Actions:**
- Set due date to {{now.plusDays(1)}}

### Clear assignee when in backlog
**Trigger:** Issue transitioned
**Conditions:**
- Transition is to "Backlog"
- Assignee is not EMPTY
**Actions:**
- Assign issue to Unassigned
- Add comment: "Returned to backlog, assignee cleared"

### Auto-populate sprint field
**Trigger:** Issue transitioned
**Conditions:**
- Transition is to "In Progress"
- Sprint is EMPTY
**Actions:**
- Add issue to current sprint

### Set fix version based on component
**Trigger:** Issue created
**Conditions:**
- Component = "Mobile App"
**Actions:**
- Set fix version to "Mobile v2.0"

---

## Escalation Rules

### Auto-escalate stale issues
**Trigger:** Scheduled - Daily at 9:00 AM
**Conditions:**
- Status = "Waiting for Response"
- Updated < -7 days
**Actions:**
- Add comment: "@{{issue.reporter}} This issue needs attention"
- Send email to project lead
- Add label: "needs-attention"

### Escalate overdue critical issues
**Trigger:** Scheduled - Every hour
**Conditions:**
- Priority IN (Highest, High)
- Due date < now()
- Status != Done
**Actions:**
- Transition to "Escalated"
- Assign to project manager
- Send Slack notification

### Auto-close inactive issues
**Trigger:** Scheduled - Daily at 10:00 AM
**Conditions:**
- Status = "Waiting for Customer"
- Updated < -30 days
**Actions:**
- Transition to "Closed"
- Add comment: "Auto-closed due to inactivity"
- Send email to reporter

---

## Sprint Automation Rules

### Move incomplete work to next sprint
**Trigger:** Sprint closed
**Conditions:**
- Issue status != Done
**Actions:**
- Add issue to next sprint
- Add comment: "Moved from {{sprint.name}}"

### Auto-remove completed items from active sprint
**Trigger:** Issue transitioned
**Conditions:**
- Transition is to "Done"
- Sprint IN openSprints()
**Actions:**
- Remove issue from sprint
- Add comment: "Removed from active sprint (completed)"

### Sprint start notification
**Trigger:** Sprint started
**Actions:**
- Send Slack message to #team:
  ```
  🚀 Sprint {{sprint.name}} Started!
  Goal: {{sprint.goal}}
  Committed: {{sprint.issuesCount}} issues
  ```

---

## Approval Workflow Rules

### Request approval for large stories
**Trigger:** Issue created
**Conditions:**
- Issue type = Story
- Story points >= 13
**Actions:**
- Transition to "Pending Approval"
- Assign to product owner
- Send email notification

### Auto-approve small bugs
**Trigger:** Issue created
**Conditions:**
- Issue type = Bug
- Priority IN (Low, Lowest)
**Actions:**
- Transition to "Approved"
- Add comment: "Auto-approved (low-priority bug)"

### Require security review
**Trigger:** Issue transitioned
**Conditions:**
- Transition is to "Ready for Release"
- Labels contains "security"
**Actions:**
- Transition to "Security Review"
- Assign to security-team
- Send email to [email protected]

---

## Integration Rules

### Create GitHub issue
**Trigger:** Issue transitioned
**Conditions:**
- Transition is to "In Progress"
- Labels contains "needs-tracking"
**Actions:**
- Send webhook to GitHub API:
  ```json
  {
    "title": "{{issue.key}}: {{issue.summary}}",
    "body": "{{issue.description}}",
    "assignee": "{{issue.assignee.name}}"
  }
  ```

### Update Confluence page
**Trigger:** Issue transitioned
**Conditions:**
- Issue type = Epic
- Transition is to "Done"
**Actions:**
- Send webhook to Confluence:
  - Update epic status page
  - Add completion date

---

## Quality & Testing Rules

### Require test cases for features
**Trigger:** Issue transitioned
**Conditions:**
- Issue type = Story
- Transition is to "Ready for QA"
- Custom field "Test Cases" is EMPTY
**Actions:**
- Transition back to "In Progress"
- Add comment: "❌ Test cases required before QA"

### Auto-create test issue
**Trigger:** Issue transitioned
**Conditions:**
- Issue type = Story
- Transition is to "Ready for QA"
**Actions:**
- Create linked issue:
  - Type: Test
  - Summary: "Test: {{issue.summary}}"
  - Link type: "tested by"
  - Assignee: QA team

### Flag regression bugs
**Trigger:** Issue created
**Conditions:**
- Issue type = Bug
- Affects version is in released versions
**Actions:**
- Add label: "regression"
- Set priority to High
- Add comment: "🚨 Regression in released version"

---

## Documentation Rules

### Require documentation for features
**Trigger:** Issue transitioned
**Conditions:**
- Issue type = Story
- Labels contains "customer-facing"
- Transition is to "Done"
- Custom field "Documentation Link" is EMPTY
**Actions:**
- Reopen issue
- Add comment: "📝 Documentation required for customer-facing feature"

### Auto-create doc task
**Trigger:** Issue transitioned
**Conditions:**
- Issue type = Epic
- Transition is to "In Progress"
**Actions:**
- Create subtask:
  - Type: Task
  - Summary: "Documentation for {{issue.summary}}"
  - Assignee: {{issue.assignee}}

---

## Time Tracking Rules

### Log work reminder
**Trigger:** Issue transitioned
**Conditions:**
- Transition is to "Done"
- Time spent is EMPTY
**Actions:**
- Add comment: "⏱️ Reminder: Please log your time"

### Warn on high time spent
**Trigger:** Work logged
**Conditions:**
- Time spent > original estimate * 1.5
**Actions:**
- Add comment: "⚠️ Time spent exceeds estimate by 50%"
- Send notification to assignee and project manager

---

## Advanced Conditional Rules

### Conditional assignee based on priority
**Trigger:** Issue created
**Conditions:**
- Issue type = Bug
**Actions:**
- If: Priority = Highest
  - Assign to on-call engineer
- Else if: Priority = High
  - Assign to team lead
- Else:
  - Assign to next available team member

### Multi-step approval flow
**Trigger:** Issue transitioned
**Conditions:**
- Transition is to "Request Approval"
- Budget estimate > $10,000
**Actions:**
- If: Budget > $50,000
  - Assign to CFO
  - Send email to executive team
- Else if: Budget > $10,000
  - Assign to Director
  - Add comment: "Director approval required"
- Add label: "pending-approval"

---

## Smart Value Examples

### Dynamic assignee based on component
```
{{issue.components.first.lead.accountId}}
```

### Days since created
```
{{issue.created.diff(now).days}}
```

### Conditional message
```
{{#if(issue.priority.name == "Highest")}}
  🚨 CRITICAL
{{else}}
  ℹ️ Normal priority
{{/}}
```

### List all subtasks
```
{{#issue.subtasks}}
  - {{key}}: {{summary}} ({{status.name}})
{{/}}
```

### Calculate completion percentage
```
{{issue.subtasks.filter(item => item.status.statusCategory.key == "done").size.divide(issue.subtasks.size).multiply(100).round()}}%
```

---

## Best Practices

1. **Test in sandbox** - Always test rules on test project first
2. **Start simple** - Begin with basic rules, add complexity incrementally
3. **Use conditions wisely** - Narrow scope to reduce unintended triggers
4. **Monitor audit log** - Check automation execution history regularly
5. **Limit actions** - Keep rules focused, don't chain too many actions
6. **Name clearly** - Use descriptive names: "Auto-assign bugs to component lead"
7. **Document rules** - Add description explaining purpose and owner
8. **Review regularly** - Audit rules quarterly, disable unused ones
9. **Handle errors** - Add error handling for webhooks and integrations
10. **Performance** - Avoid scheduled rules that query large datasets hourly

FILE:references/AUTOMATION.md
# Jira Automation Reference

Comprehensive guide to Jira automation rules: triggers, conditions, actions, smart values, and production-ready recipes.

## Rule Structure

Every automation rule follows this pattern:
```
TRIGGER → [CONDITION(s)] → ACTION(s)
```

- **Trigger**: The event that starts the rule (required, exactly one)
- **Condition**: Filters to narrow when the rule fires (optional, multiple allowed)
- **Action**: What the rule does (required, one or more)

## Triggers

### Issue Triggers

| Trigger | Fires When | Use For |
|---------|------------|---------|
| **Issue created** | New issue is created | Auto-assignment, notifications, SLA start |
| **Issue transitioned** | Status changes | Workflow automation, notifications |
| **Issue updated** | Any field changes | Field sync, cascading updates |
| **Issue commented** | Comment is added | Auto-responses, SLA tracking |
| **Issue assigned** | Assignee changes | Workload notifications |
| **Issue linked** | Link is added/removed | Dependency tracking |
| **Issue deleted** | Issue is deleted | Cleanup, audit logging |

### Sprint & Board Triggers

| Trigger | Fires When |
|---------|------------|
| **Sprint started** | Sprint is activated |
| **Sprint completed** | Sprint is closed |
| **Issue moved between sprints** | Issue is moved |
| **Backlog item moved to sprint** | Item is pulled into sprint |

### Scheduled Triggers

| Trigger | Fires When |
|---------|------------|
| **Scheduled** | Cron-based (daily, weekly, custom) |
| **Issue stale** | No updates for X days |

### Version Triggers

| Trigger | Fires When |
|---------|------------|
| **Version created** | New version added |
| **Version released** | Version is released |

## Conditions

### Issue Conditions

| Condition | Matches When |
|-----------|-------------|
| **Issue fields condition** | Field matches value (e.g., priority = High) |
| **JQL condition** | Issue matches JQL query |
| **Related issues condition** | Linked/sub-task issues match criteria |
| **User condition** | Actor matches (reporter, assignee, group) |
| **Advanced compare** | Complex field comparisons |

### Condition Operators

```
Field = value           # Exact match
Field != value          # Not equal
Field > value           # Greater than (numeric/date)
Field is empty          # Field has no value
Field is not empty      # Field has a value
Field changed           # Field was modified in this event
Field changed to        # Field changed to specific value
Field changed from      # Field changed from specific value
```

## Actions

### Issue Actions

| Action | Does |
|--------|------|
| **Edit issue** | Update any field on the current issue |
| **Transition issue** | Move to a new status |
| **Assign issue** | Change assignee |
| **Comment on issue** | Add a comment |
| **Create issue** | Create a new linked issue |
| **Create sub-tasks** | Create child issues |
| **Clone issue** | Duplicate the issue |
| **Delete issue** | Remove the issue |
| **Link issues** | Add issue links |
| **Log work** | Add time tracking entry |

### Notification Actions

| Action | Does |
|--------|------|
| **Send email** | Send custom email to users/groups |
| **Send Slack message** | Post to Slack channel (requires integration) |
| **Send Microsoft Teams message** | Post to Teams (requires integration) |
| **Send web request** | HTTP call to external service |

### Lookup & Branch Actions

| Action | Does |
|--------|------|
| **Lookup issues (JQL)** | Find issues matching JQL, iterate over them |
| **Create branch** | Branch logic (if/then/else) |
| **For each** | Loop over found issues |

## Smart Values

Smart values are dynamic placeholders that resolve at runtime.

### Issue Smart Values

```
{{issue.key}}                    # PROJ-123
{{issue.summary}}                # Issue title
{{issue.description}}            # Full description
{{issue.status.name}}            # Current status
{{issue.priority.name}}          # Priority level
{{issue.assignee.displayName}}   # Assignee name
{{issue.reporter.displayName}}   # Reporter name
{{issue.issuetype.name}}         # Issue type
{{issue.project.key}}            # Project key
{{issue.created}}                # Creation date
{{issue.updated}}                # Last update date
{{issue.fixVersions}}            # Fix versions
{{issue.labels}}                 # Labels array
{{issue.components}}             # Components array
```

### Transition Smart Values

```
{{transition.from_status}}       # Previous status
{{transition.to_status}}         # New status
{{transition.transitionName}}    # Transition name
```

### User Smart Values

```
{{initiator.displayName}}        # Who triggered the rule
{{initiator.emailAddress}}       # Their email
{{initiator.accountId}}          # Their account ID
```

### Date Smart Values

```
{{now}}                          # Current timestamp
{{now.plusDays(7)}}              # 7 days from now
{{now.minusHours(24)}}          # 24 hours ago
{{issue.created.plusBusinessDays(3)}}  # 3 business days after creation
```

### Conditional Smart Values

```
{{#if issue.priority.name == "High"}}
  This is high priority
{{/if}}

{{#if issue.assignee}}
  Assigned to {{issue.assignee.displayName}}
{{else}}
  Unassigned
{{/if}}
```

## Production-Ready Recipes

### 1. Auto-Assign by Component

```yaml
Trigger: Issue created
Condition: Issue has component
Action: Edit issue
  - Assignee = Component lead

Rule Logic:
  IF component = "Backend" → assign to @backend-lead
  IF component = "Frontend" → assign to @frontend-lead
  IF component = "DevOps" → assign to @devops-lead
```

### 2. SLA Warning — Stale Issues

```yaml
Trigger: Scheduled (daily at 9am)
Condition: JQL = "status != Done AND updated <= -5d AND priority in (High, Highest)"
Action: 
  - Add comment: "⚠️ This {{issue.priority.name}} issue hasn't been updated in 5+ days."
  - Send Slack: "#engineering-alerts: {{issue.key}} is stale ({{issue.assignee.displayName}})"
```

### 3. Auto-Close Resolved Issues After 7 Days

```yaml
Trigger: Scheduled (daily)
Condition: JQL = "status = Resolved AND updated <= -7d"
Action:
  - Transition: Resolved → Closed
  - Comment: "Auto-closed after 7 days in Resolved status."
```

### 4. Sprint Spillover Notification

```yaml
Trigger: Sprint completed
Condition: Issue status != Done
Action:
  - Comment: "Spilled over from Sprint {{sprint.name}}. Reason needs review."
  - Add label: "spillover"
  - Send email to: {{issue.assignee.emailAddress}}
```

### 5. Sub-Task Completion → Parent Transition

```yaml
Trigger: Issue transitioned (to Done)
Condition: Issue is sub-task AND all sibling sub-tasks are Done
Action (on parent):
  - Transition: In Progress → In Review
  - Comment: "All sub-tasks completed. Ready for review."
```

### 6. Bug Priority Escalation

```yaml
Trigger: Scheduled (every 4 hours)
Condition: JQL = "type = Bug AND priority = High AND status = Open AND created <= -24h"
Action:
  - Edit: priority = Highest
  - Comment: "⚡ Auto-escalated: High-priority bug open for 24+ hours."
  - Send email to: project lead
```

### 7. Auto-Link Duplicate Detection

```yaml
Trigger: Issue created
Condition: JQL finds issues with similar summary (fuzzy)
Action:
  - Comment: "Possible duplicate of {{lookupIssues.first.key}}: {{lookupIssues.first.summary}}"
  - Add label: "possible-duplicate"
```

### 8. Release Notes Generator

```yaml
Trigger: Version released
Condition: None
Action:
  - Lookup: JQL = "fixVersion = {{version.name}} AND status = Done"
  - Create Confluence page:
    Title: "Release Notes — {{version.name}}"
    Content: List of resolved issues with types and summaries
```

### 9. Workload Balancer — Round-Robin Assignment

```yaml
Trigger: Issue created
Condition: Issue type = Story AND assignee is empty
Action:
  - Lookup: JQL = "assignee in (dev1, dev2, dev3) AND sprint in openSprints() AND status != Done"
  - Assign to team member with fewest open issues
```

### 10. Blocker Notification Chain

```yaml
Trigger: Issue updated (priority changed to Blocker)
Action:
  - Send email to: project lead, scrum master
  - Send Slack: "#blockers: 🚨 {{issue.key}} marked as Blocker by {{initiator.displayName}}"
  - Comment: "Blocker escalated. Notified: PM + SM."
  - Edit: Add label "blocker-active"
```

## Best Practices

1. **Name rules descriptively** — "Auto-assign Backend bugs to @dev-lead" not "Rule 1"
2. **Add conditions before actions** — prevent unintended execution
3. **Use JQL conditions** for precision — field conditions can miss edge cases
4. **Test in a sandbox project first** — automation mistakes can be destructive
5. **Set rate limits** — avoid infinite loops (Rule A triggers Rule B triggers Rule A)
6. **Monitor rule execution** — check Automation audit log weekly
7. **Document business rules** — explain WHY the rule exists, not just WHAT it does
8. **Use branches (if/else)** over separate rules — reduces rule count, easier to maintain
9. **Disable before deleting** — observe for a week to ensure no side effects
10. **Version your automation** — export rules as JSON backup before major changes

FILE:references/jql-examples.md
# JQL Query Examples

## Sprint Queries

**Current sprint issues:**
```jql
sprint IN openSprints() ORDER BY rank
```

**Issues in specific sprint:**
```jql
sprint = "Sprint 23" ORDER BY priority DESC
```

**All sprint work (current and backlog):**
```jql
project = ABC AND issuetype IN (Story, Bug, Task) 
ORDER BY sprint DESC, rank
```

**Unscheduled stories:**
```jql
project = ABC AND issuetype = Story AND sprint IS EMPTY 
AND status != Done ORDER BY priority DESC
```

**Spillover from last sprint:**
```jql
sprint IN closedSprints() AND sprint NOT IN (latestReleasedVersion()) 
AND status != Done ORDER BY created DESC
```

**Sprint completion rate:**
```jql
sprint = "Sprint 23" AND status = Done
```

## User & Team Queries

**My open issues:**
```jql
assignee = currentUser() AND status != Done 
ORDER BY priority DESC, created ASC
```

**Unassigned in my project:**
```jql
project = ABC AND assignee IS EMPTY AND status != Done
ORDER BY priority DESC
```

**Issues I'm watching:**
```jql
watcher = currentUser() AND status != Done
```

**Team workload:**
```jql
assignee IN membersOf("engineering-team") AND status IN ("In Progress", "In Review")
ORDER BY assignee, priority DESC
```

**Issues I reported that are still open:**
```jql
reporter = currentUser() AND status != Done ORDER BY created DESC
```

**Issues commented on by me:**
```jql
comment ~ currentUser() AND status != Done
```

## Date Range Queries

**Created today:**
```jql
created >= startOfDay() ORDER BY created DESC
```

**Updated in last 7 days:**
```jql
updated >= -7d ORDER BY updated DESC
```

**Created this week:**
```jql
created >= startOfWeek() AND created <= endOfWeek()
```

**Created this month:**
```jql
created >= startOfMonth() AND created <= endOfMonth()
```

**Not updated in 30 days:**
```jql
status != Done AND updated <= -30d ORDER BY updated ASC
```

**Resolved yesterday:**
```jql
resolved >= startOfDay(-1d) AND resolved < startOfDay()
```

**Due this week:**
```jql
duedate >= startOfWeek() AND duedate <= endOfWeek() AND status != Done
```

**Overdue:**
```jql
duedate < now() AND status != Done ORDER BY duedate ASC
```

## Status & Workflow Queries

**In Progress issues:**
```jql
project = ABC AND status = "In Progress" ORDER BY assignee
```

**Blocked issues:**
```jql
project = ABC AND labels = blocked AND status != Done
```

**Issues in review:**
```jql
project = ABC AND status IN ("Code Review", "QA Review", "Pending Approval")
ORDER BY updated ASC
```

**Ready for development:**
```jql
project = ABC AND status = "Ready" AND sprint IS EMPTY
ORDER BY priority DESC
```

**Recently done:**
```jql
project = ABC AND status = Done AND resolved >= -7d
ORDER BY resolved DESC
```

**Status changed today:**
```jql
status CHANGED AFTER startOfDay() ORDER BY updated DESC
```

**Long-running in progress:**
```jql
status = "In Progress" AND status CHANGED BEFORE -14d
ORDER BY status CHANGED ASC
```

## Priority & Type Queries

**High priority bugs:**
```jql
issuetype = Bug AND priority IN (Highest, High) AND status != Done
ORDER BY priority DESC, created ASC
```

**Critical blockers:**
```jql
priority = Highest AND status != Done ORDER BY created ASC
```

**All epics:**
```jql
issuetype = Epic ORDER BY status, priority DESC
```

**Stories without acceptance criteria:**
```jql
issuetype = Story AND "Acceptance Criteria" IS EMPTY AND status = Backlog
```

**Technical debt:**
```jql
labels = tech-debt AND status != Done ORDER BY priority DESC
```

## Complex Multi-Condition Queries

**My team's sprint work:**
```jql
sprint IN openSprints() 
AND assignee IN membersOf("engineering-team") 
AND status != Done
ORDER BY assignee, priority DESC
```

**Bugs created this month, not in sprint:**
```jql
issuetype = Bug 
AND created >= startOfMonth() 
AND sprint IS EMPTY 
AND status != Done
ORDER BY priority DESC, created DESC
```

**High-priority work needing attention:**
```jql
project = ABC 
AND priority IN (Highest, High) 
AND status IN ("In Progress", "In Review") 
AND updated <= -3d
ORDER BY priority DESC, updated ASC
```

**Stale issues:**
```jql
project = ABC 
AND status NOT IN (Done, Cancelled) 
AND (assignee IS EMPTY OR updated <= -30d)
ORDER BY created ASC
```

**Epic progress:**
```jql
"Epic Link" = ABC-123 ORDER BY status, rank
```

## Component & Version Queries

**Issues in component:**
```jql
project = ABC AND component = "Frontend" AND status != Done
```

**Issues without component:**
```jql
project = ABC AND component IS EMPTY AND status != Done
```

**Target version:**
```jql
fixVersion = "v2.0" ORDER BY status, priority DESC
```

**Released versions:**
```jql
fixVersion IN releasedVersions() ORDER BY fixVersion DESC
```

## Label & Text Search Queries

**Issues with label:**
```jql
labels = urgent AND status != Done
```

**Multiple labels (AND):**
```jql
labels IN (frontend, bug) AND status != Done
```

**Search in summary:**
```jql
summary ~ "authentication" ORDER BY created DESC
```

**Search in summary and description:**
```jql
text ~ "API integration" ORDER BY created DESC
```

**Issues with empty description:**
```jql
description IS EMPTY AND issuetype = Story
```

## Performance-Optimized Queries

**Good - Specific project first:**
```jql
project = ABC AND status = "In Progress" AND assignee = currentUser()
```

**Bad - User filter first:**
```jql
assignee = currentUser() AND status = "In Progress" AND project = ABC
```

**Good - Use functions:**
```jql
sprint IN openSprints() AND status != Done
```

**Bad - Hardcoded sprint:**
```jql
sprint = "Sprint 23" AND status != Done
```

**Good - Specific date:**
```jql
created >= 2024-01-01 AND created <= 2024-01-31
```

**Bad - Relative with high cost:**
```jql
created >= -365d AND created <= -335d
```

## Reporting Queries

**Velocity calculation:**
```jql
sprint = "Sprint 23" AND status = Done
```
*Then sum story points*

**Bug rate:**
```jql
project = ABC AND issuetype = Bug AND created >= startOfMonth()
```

**Average cycle time:**
```jql
project = ABC AND resolved >= startOfMonth() 
AND resolved <= endOfMonth()
```
*Calculate time from In Progress to Done*

**Stories delivered this quarter:**
```jql
project = ABC AND issuetype = Story 
AND resolved >= startOfYear() AND resolved <= endOfQuarter()
```

**Team capacity:**
```jql
assignee IN membersOf("engineering-team") 
AND sprint IN openSprints()
```
*Sum original estimates*

## Notification & Watching Queries

**Issues I need to review:**
```jql
status = "Pending Review" AND assignee = currentUser()
```

**Issues assigned to me, high priority:**
```jql
assignee = currentUser() AND priority IN (Highest, High) 
AND status != Done
```

**Issues created by me, not resolved:**
```jql
reporter = currentUser() AND status != Done 
ORDER BY created DESC
```

## Advanced Functions

**Issues changed from status:**
```jql
status WAS "In Progress" AND status = "Done" 
AND status CHANGED AFTER startOfWeek()
```

**Assignee changed:**
```jql
assignee CHANGED BY currentUser() AFTER -7d
```

**Issues re-opened:**
```jql
status WAS Done AND status != Done ORDER BY updated DESC
```

**Linked issues:**
```jql
issue IN linkedIssues("ABC-123") ORDER BY issuetype
```

**Parent epic:**
```jql
parent = ABC-123 ORDER BY rank
```

## Saved Filter Examples

**Daily Standup Filter:**
```jql
assignee = currentUser() AND sprint IN openSprints() 
AND status != Done ORDER BY priority DESC
```

**Team Sprint Board Filter:**
```jql
project = ABC AND sprint IN openSprints() ORDER BY rank
```

**Bugs Dashboard Filter:**
```jql
project = ABC AND issuetype = Bug AND status != Done
ORDER BY priority DESC, created ASC
```

**Tech Debt Backlog:**
```jql
project = ABC AND labels = tech-debt AND status = Backlog
ORDER BY priority DESC
```

**Needs Triage:**
```jql
project = ABC AND status = "To Triage" 
AND created >= -7d ORDER BY created ASC
```

FILE:references/WORKFLOWS.md
# Jira Workflows Reference

Comprehensive guide to Jira workflow design, transitions, conditions, validators, and post-functions.

## Default Workflows

### Simplified Workflow
```
Open → In Progress → Done
```

### Software Development Workflow
```
Backlog → Selected for Development → In Progress → In Review → Done
         ↑___________________________|  (reopen)
```

### Bug Tracking Workflow
```
Open → In Progress → Fixed → Verified → Closed
  ↑                    |        |
  |____Reopened________|________|
```

## Custom Workflow Design

### Design Principles
1. **Mirror your actual process** — don't force teams into artificial states
2. **Minimize statuses** — each status must represent a distinct work state where the item waits for a different action
3. **Clear ownership** — every status should have an obvious responsible party
4. **Allow rework** — always provide paths back for rejected/reopened items
5. **Separate "waiting" from "working"** — distinguish "In Review" (waiting) from "Reviewing" (actively working)

### Status Categories
Jira maps every status to one of four categories that drive board columns and JQL:

| Category | Meaning | JQL | Examples |
|----------|---------|-----|----------|
| `To Do` | Not started | `statusCategory = "To Do"` | Backlog, Open, New |
| `In Progress` | Active work | `statusCategory = "In Progress"` | In Progress, In Review, Testing |
| `Done` | Completed | `statusCategory = Done` | Done, Closed, Released |
| `Undefined` | Legacy/unused | — | Avoid using |

### Recommended Statuses by Team Type

**Engineering Team:**
```
Backlog → Ready → In Progress → Code Review → QA → Done
```

**Support Team:**
```
New → Triaged → In Progress → Waiting on Customer → Resolved → Closed
```

**Design Team:**
```
Backlog → Research → Design → Review → Approved → Handoff
```

## Transitions

### Transition Properties

| Property | Description |
|----------|-------------|
| **Name** | Display name on the button (e.g., "Start Work") |
| **Screen** | Form shown during transition (optional) |
| **Conditions** | Who can trigger this transition |
| **Validators** | Rules that must pass before transition executes |
| **Post-functions** | Actions executed after transition completes |

### Common Transition Patterns

**Start Work:**
```
Trigger: "Start Work" button
Condition: Assignee only
Validator: Issue must have assignee
Post-function: Set "In Progress" resolution to None
```

**Submit for Review:**
```
Trigger: "Submit for Review" button
Condition: Assignee or project admin
Validator: All sub-tasks must be Done
Post-function: Add comment "Submitted for review by {user}"
```

**Approve:**
```
Trigger: "Approve" button
Condition: Must be in "Reviewers" group
Validator: Must add comment
Post-function: Set resolution to "Done", fire event
```

## Conditions

### Built-in Conditions

| Condition | Use When |
|-----------|----------|
| **Only Assignee** | Only assigned user can transition |
| **Only Reporter** | Only creator can transition |
| **Permission Condition** | User must have specific permission |
| **Group Condition** | User must be in specified group |
| **Sub-Task Blocking** | All sub-tasks must be resolved |
| **Previous Status** | Issue must have been in a specific status |
| **User Is In Role** | User must have project role (Developer, Admin) |

### Combining Conditions
- **AND logic**: Add multiple conditions to one transition — ALL must pass
- **OR logic**: Create parallel transitions with different conditions

## Validators

### Built-in Validators

| Validator | Checks |
|-----------|--------|
| **Required Field** | Specific field must be populated |
| **Field Has Been Modified** | Field must change during transition |
| **Regular Expression** | Field must match regex pattern |
| **Permission Validator** | User must have permission |
| **Previous Status Validator** | Issue was in a required status |

### Common Validator Patterns

```
# Require comment on rejection
Validator: Comment Required
When: Transition = "Reject"

# Require fix version before release
Validator: Required Field = "Fix Version/s"
When: Transition = "Release"

# Require time logged before closing
Validator: Field Required = "Time Spent" (must be > 0)
When: Transition = "Close"
```

## Post-Functions

### Built-in Post-Functions

| Post-Function | Action |
|---------------|--------|
| **Set Field Value** | Assign a value to any field |
| **Update Issue Field** | Change assignee, priority, etc. |
| **Create Comment** | Add automated comment |
| **Fire Event** | Trigger notification event |
| **Assign to Lead** | Assign to project lead |
| **Assign to Reporter** | Assign back to creator |
| **Clear Field** | Remove field value |
| **Copy Value** | Copy field from parent/linked issue |

### Post-Function Execution Order
Post-functions execute in defined order. Standard sequence:
1. Set issue status (automatic, always first)
2. Add comment (if configured)
3. Update fields
4. Generate change history (automatic, always last)
5. Fire event (triggers notifications)

**Important:** "Generate change history" and "Fire event" must always be last — reorder if you add custom post-functions.

## Workflow Schemes

### What They Do
- Map issue types to workflows within a project
- One workflow scheme per project
- Different issue types can use different workflows

### Configuration Pattern
```
Project: MYPROJ
Workflow Scheme: "Engineering Workflow Scheme"

  Bug         → Bug Tracking Workflow
  Story       → Development Workflow
  Task        → Simple Workflow
  Epic        → Epic Workflow
  Sub-task    → Sub-task Workflow (inherits parent transitions)
```

## Best Practices

1. **Start simple, add complexity only when needed** — a 5-status workflow beats a 15-status one
2. **Name transitions as actions** — "Start Work" not "In Progress" (the status is "In Progress", the action is "Start Work")
3. **Use screens sparingly** — only show a screen when you need data from the user during transition
4. **Test with real users** — workflows that look good on paper may confuse the team
5. **Document your workflow** — add descriptions to statuses and transitions
6. **Use global transitions carefully** — a "Cancel" transition from any status is convenient but can bypass important gates
7. **Audit quarterly** — remove statuses with <5% usage

FILE:scripts/jql_query_builder.py
#!/usr/bin/env python3
"""
JQL Query Builder

Pattern-matching JQL builder from natural language descriptions. Maps common
phrases to JQL operators and constructs valid queries with syntax validation.

Usage:
    python jql_query_builder.py "high priority bugs in PROJECT assigned to me"
    python jql_query_builder.py "overdue tasks in PROJ" --format json
    python jql_query_builder.py --patterns
"""

import argparse
import json
import re
import sys
from datetime import datetime
from typing import Any, Dict, List, Optional, Tuple


# ---------------------------------------------------------------------------
# Pattern Library
# ---------------------------------------------------------------------------

PATTERN_LIBRARY = {
    "my_open_bugs": {
        "phrases": ["my open bugs", "my bugs", "bugs assigned to me"],
        "jql": 'assignee = currentUser() AND type = Bug AND status != Done',
        "description": "All open bugs assigned to current user",
    },
    "high_priority_bugs": {
        "phrases": ["high priority bugs", "critical bugs", "urgent bugs", "p1 bugs"],
        "jql": 'type = Bug AND priority in (Highest, High) AND status != Done',
        "description": "High and highest priority open bugs",
    },
    "my_open_tasks": {
        "phrases": ["my open tasks", "my tasks", "tasks assigned to me", "my work"],
        "jql": 'assignee = currentUser() AND status != Done',
        "description": "All open issues assigned to current user",
    },
    "unassigned_issues": {
        "phrases": ["unassigned", "unassigned issues", "no assignee"],
        "jql": 'assignee is EMPTY AND status != Done',
        "description": "Issues with no assignee",
    },
    "recently_created": {
        "phrases": ["recently created", "new issues", "created this week", "recent"],
        "jql": 'created >= -7d ORDER BY created DESC',
        "description": "Issues created in the last 7 days",
    },
    "recently_updated": {
        "phrases": ["recently updated", "updated this week", "recent changes"],
        "jql": 'updated >= -7d ORDER BY updated DESC',
        "description": "Issues updated in the last 7 days",
    },
    "overdue": {
        "phrases": ["overdue", "past due", "missed deadline", "overdue tasks"],
        "jql": 'duedate < now() AND status != Done',
        "description": "Issues past their due date",
    },
    "due_this_week": {
        "phrases": ["due this week", "due soon", "upcoming deadlines"],
        "jql": 'duedate >= startOfWeek() AND duedate <= endOfWeek() AND status != Done',
        "description": "Issues due this week",
    },
    "blocked_issues": {
        "phrases": ["blocked", "blocked issues", "impediments"],
        "jql": 'status = Blocked OR status = Impediment',
        "description": "Issues in blocked or impediment status",
    },
    "in_progress": {
        "phrases": ["in progress", "being worked on", "active work"],
        "jql": 'status = "In Progress"',
        "description": "Issues currently in progress",
    },
    "sprint_issues": {
        "phrases": ["current sprint", "this sprint", "active sprint"],
        "jql": 'sprint in openSprints()',
        "description": "Issues in the current active sprint",
    },
    "backlog": {
        "phrases": ["backlog", "backlog items", "not started"],
        "jql": 'sprint is EMPTY AND status = "To Do" ORDER BY priority DESC',
        "description": "Issues in the backlog not assigned to a sprint",
    },
    "stories_without_estimates": {
        "phrases": ["no estimates", "unestimated", "missing estimates", "no story points"],
        "jql": 'type = Story AND (storyPoints is EMPTY OR storyPoints = 0) AND status != Done',
        "description": "Stories missing story point estimates",
    },
    "epics_in_progress": {
        "phrases": ["active epics", "epics in progress", "open epics"],
        "jql": 'type = Epic AND status != Done ORDER BY priority DESC',
        "description": "Epics that are not yet completed",
    },
    "done_this_week": {
        "phrases": ["done this week", "completed this week", "resolved this week"],
        "jql": 'status changed to Done DURING (startOfWeek(), now())',
        "description": "Issues completed during the current week",
    },
    "created_vs_resolved": {
        "phrases": ["created vs resolved", "issue flow", "throughput"],
        "jql": 'created >= -30d ORDER BY created DESC',
        "description": "Issues created in the last 30 days for flow analysis",
    },
    "my_reported_issues": {
        "phrases": ["my reported", "reported by me", "i created", "i reported"],
        "jql": 'reporter = currentUser() ORDER BY created DESC',
        "description": "Issues reported by current user",
    },
    "stale_issues": {
        "phrases": ["stale", "stale issues", "not updated", "abandoned"],
        "jql": 'updated <= -30d AND status != Done ORDER BY updated ASC',
        "description": "Issues not updated in 30+ days",
    },
    "subtasks_without_parent": {
        "phrases": ["orphan subtasks", "subtasks no parent", "loose subtasks"],
        "jql": 'type = Sub-task AND parent is EMPTY',
        "description": "Subtasks missing parent issues",
    },
    "high_priority_unassigned": {
        "phrases": ["high priority unassigned", "urgent unassigned", "critical no owner"],
        "jql": 'priority in (Highest, High) AND assignee is EMPTY AND status != Done',
        "description": "High priority issues with no assignee",
    },
    "bugs_by_component": {
        "phrases": ["bugs by component", "component bugs"],
        "jql": 'type = Bug AND status != Done ORDER BY component ASC',
        "description": "Open bugs organized by component",
    },
    "resolved_recently": {
        "phrases": ["resolved recently", "recently resolved", "fixed this month"],
        "jql": 'resolved >= -30d ORDER BY resolved DESC',
        "description": "Issues resolved in the last 30 days",
    },
}

# Keyword-to-JQL fragment mapping for dynamic query building
KEYWORD_FRAGMENTS = {
    # Issue types
    "bug": ("type", "= Bug"),
    "bugs": ("type", "= Bug"),
    "story": ("type", "= Story"),
    "stories": ("type", "= Story"),
    "task": ("type", "= Task"),
    "tasks": ("type", "= Task"),
    "epic": ("type", "= Epic"),
    "epics": ("type", "= Epic"),
    "subtask": ("type", "= Sub-task"),
    "sub-task": ("type", "= Sub-task"),
    # Statuses
    "open": ("status", "!= Done"),
    "closed": ("status", "= Done"),
    "done": ("status", "= Done"),
    "resolved": ("status", "= Done"),
    "todo": ("status", '= "To Do"'),
    # Priorities
    "critical": ("priority", "= Highest"),
    "highest": ("priority", "= Highest"),
    "high": ("priority", "in (Highest, High)"),
    "medium": ("priority", "= Medium"),
    "low": ("priority", "in (Low, Lowest)"),
    "lowest": ("priority", "= Lowest"),
    # Assignee
    "me": ("assignee", "= currentUser()"),
    "mine": ("assignee", "= currentUser()"),
    "unassigned": ("assignee", "is EMPTY"),
    # Time
    "overdue": ("duedate", "< now()"),
    "today": ("duedate", "= now()"),
}

PROJECT_PATTERN = re.compile(r'\b([A-Z]{2,10})\b')
ASSIGNEE_PATTERN = re.compile(r'assigned\s+to\s+(\w+)', re.IGNORECASE)
LABEL_PATTERN = re.compile(r'label[s]?\s*[=:]\s*["\']?(\w+)["\']?', re.IGNORECASE)
COMPONENT_PATTERN = re.compile(r'component[s]?\s*[=:]\s*["\']?(\w+)["\']?', re.IGNORECASE)
DATE_RANGE_PATTERN = re.compile(r'last\s+(\d+)\s+(day|week|month)s?', re.IGNORECASE)
SPRINT_NAME_PATTERN = re.compile(r'sprint\s+["\']?(\w[\w\s]*\w)["\']?', re.IGNORECASE)

# Words to exclude from project matching
EXCLUDED_WORDS = {
    "AND", "OR", "NOT", "IN", "IS", "TO", "BY", "ON", "DO", "BE",
    "THE", "ALL", "MY", "NO", "OF", "AT", "AS", "IF", "IT",
    "BUG", "BUGS", "TASK", "TASKS", "STORY", "EPIC", "DONE",
    "HIGH", "LOW", "MEDIUM", "JQL",
}


# ---------------------------------------------------------------------------
# Query Builder
# ---------------------------------------------------------------------------

def find_matching_pattern(description: str) -> Optional[Dict[str, Any]]:
    """Check if description matches a known pattern exactly."""
    desc_lower = description.lower().strip()
    for pattern_name, pattern_data in PATTERN_LIBRARY.items():
        for phrase in pattern_data["phrases"]:
            if phrase in desc_lower or desc_lower in phrase:
                return {
                    "pattern_name": pattern_name,
                    "jql": pattern_data["jql"],
                    "description": pattern_data["description"],
                    "match_type": "exact_pattern",
                }
    return None


def build_jql_from_description(description: str) -> Dict[str, Any]:
    """Build JQL query from natural language description."""
    # First try exact pattern match
    pattern_match = find_matching_pattern(description)
    if pattern_match:
        # Augment with project if mentioned
        project = _extract_project(description)
        if project:
            pattern_match["jql"] = f'project = {project} AND {pattern_match["jql"]}'
        return pattern_match

    # Dynamic query building
    clauses = []
    used_fields = set()
    desc_lower = description.lower()

    # Extract project
    project = _extract_project(description)
    if project:
        clauses.append(f"project = {project}")
        used_fields.add("project")

    # Extract keyword-based fragments
    for keyword, (field, fragment) in KEYWORD_FRAGMENTS.items():
        if keyword in desc_lower.split() and field not in used_fields:
            clauses.append(f"{field} {fragment}")
            used_fields.add(field)

    # Extract explicit assignee
    assignee_match = ASSIGNEE_PATTERN.search(description)
    if assignee_match and "assignee" not in used_fields:
        assignee = assignee_match.group(1)
        if assignee.lower() in ("me", "myself"):
            clauses.append("assignee = currentUser()")
        else:
            clauses.append(f'assignee = "{assignee}"')
        used_fields.add("assignee")

    # Extract labels
    label_match = LABEL_PATTERN.search(description)
    if label_match:
        clauses.append(f'labels = "{label_match.group(1)}"')

    # Extract component
    component_match = COMPONENT_PATTERN.search(description)
    if component_match:
        clauses.append(f'component = "{component_match.group(1)}"')

    # Extract date ranges
    date_match = DATE_RANGE_PATTERN.search(description)
    if date_match:
        amount = date_match.group(1)
        unit = date_match.group(2).lower()
        unit_char = {"day": "d", "week": "w", "month": "m"}.get(unit, "d")
        clauses.append(f"created >= -{amount}{unit_char}")

    # Extract sprint reference
    sprint_match = SPRINT_NAME_PATTERN.search(description)
    if sprint_match:
        sprint_name = sprint_match.group(1).strip()
        if sprint_name.lower() in ("current", "active", "open"):
            clauses.append("sprint in openSprints()")
        else:
            clauses.append(f'sprint = "{sprint_name}"')

    # Default: if no status clause and not looking for done items
    if "status" not in used_fields and "done" not in desc_lower and "closed" not in desc_lower:
        clauses.append("status != Done")

    if not clauses:
        return {
            "jql": "",
            "description": "Could not build query from description",
            "match_type": "no_match",
            "error": "No recognizable patterns found in description",
        }

    jql = " AND ".join(clauses)

    # Add ORDER BY for common scenarios
    if "recent" in desc_lower or "latest" in desc_lower:
        jql += " ORDER BY created DESC"
    elif "priority" in desc_lower or "urgent" in desc_lower:
        jql += " ORDER BY priority DESC"

    return {
        "jql": jql,
        "description": f"Dynamic query from: {description}",
        "match_type": "dynamic",
        "clauses_used": len(clauses),
    }


def _extract_project(description: str) -> Optional[str]:
    """Extract project key from description."""
    # Look for IN/in PROJECT pattern
    in_project = re.search(r'\bin\s+([A-Z]{2,10})\b', description)
    if in_project and in_project.group(1) not in EXCLUDED_WORDS:
        return in_project.group(1)

    # Look for standalone project keys
    for match in PROJECT_PATTERN.finditer(description):
        word = match.group(1)
        if word not in EXCLUDED_WORDS:
            return word

    return None


def validate_jql_syntax(jql: str) -> Dict[str, Any]:
    """Basic JQL syntax validation."""
    issues = []

    if not jql.strip():
        return {"valid": False, "issues": ["Empty query"]}

    # Check balanced quotes
    single_quotes = jql.count("'")
    double_quotes = jql.count('"')
    if single_quotes % 2 != 0:
        issues.append("Unbalanced single quotes")
    if double_quotes % 2 != 0:
        issues.append("Unbalanced double quotes")

    # Check balanced parentheses
    open_parens = jql.count("(")
    close_parens = jql.count(")")
    if open_parens != close_parens:
        issues.append(f"Unbalanced parentheses: {open_parens} open, {close_parens} close")

    # Check for known JQL operators
    valid_operators = {"=", "!=", ">", "<", ">=", "<=", "~", "!~", "in", "not in", "is", "is not", "was", "was not", "changed"}
    jql_upper = jql.upper()

    # Check AND/OR placement
    if jql_upper.strip().startswith("AND") or jql_upper.strip().startswith("OR"):
        issues.append("Query cannot start with AND/OR")
    if jql_upper.strip().endswith("AND") or jql_upper.strip().endswith("OR"):
        issues.append("Query cannot end with AND/OR")

    # Check ORDER BY syntax
    order_match = re.search(r'ORDER\s+BY\s+(\w+)(?:\s+(ASC|DESC))?', jql, re.IGNORECASE)
    if "ORDER" in jql_upper and not order_match:
        issues.append("Invalid ORDER BY syntax")

    return {
        "valid": len(issues) == 0,
        "issues": issues,
        "query_length": len(jql),
    }


# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------

def format_text_output(result: Dict[str, Any]) -> str:
    """Format results as readable text report."""
    lines = []
    lines.append("=" * 60)
    lines.append("JQL QUERY BUILDER RESULTS")
    lines.append("=" * 60)
    lines.append("")

    if "error" in result:
        lines.append(f"ERROR: {result['error']}")
        return "\n".join(lines)

    lines.append(f"Match Type: {result.get('match_type', 'unknown')}")
    lines.append(f"Description: {result.get('description', '')}")
    lines.append("")
    lines.append("GENERATED JQL")
    lines.append("-" * 30)
    lines.append(result.get("jql", ""))
    lines.append("")

    validation = result.get("validation", {})
    if validation:
        lines.append("VALIDATION")
        lines.append("-" * 30)
        lines.append(f"Valid: {'Yes' if validation.get('valid') else 'No'}")
        if validation.get("issues"):
            for issue in validation["issues"]:
                lines.append(f"  - {issue}")

    if result.get("pattern_name"):
        lines.append("")
        lines.append(f"Matched Pattern: {result['pattern_name']}")

    return "\n".join(lines)


def format_patterns_output(output_format: str) -> str:
    """Format available patterns list."""
    if output_format == "json":
        patterns = {}
        for name, data in PATTERN_LIBRARY.items():
            patterns[name] = {
                "description": data["description"],
                "phrases": data["phrases"],
                "jql": data["jql"],
            }
        return json.dumps(patterns, indent=2)

    lines = []
    lines.append("=" * 60)
    lines.append("AVAILABLE JQL PATTERNS")
    lines.append("=" * 60)
    lines.append("")

    for name, data in PATTERN_LIBRARY.items():
        lines.append(f"  {name}")
        lines.append(f"    Description: {data['description']}")
        lines.append(f"    Phrases: {', '.join(data['phrases'])}")
        lines.append(f"    JQL: {data['jql']}")
        lines.append("")

    lines.append(f"Total patterns: {len(PATTERN_LIBRARY)}")
    return "\n".join(lines)


def format_json_output(result: Dict[str, Any]) -> Dict[str, Any]:
    """Format results as JSON."""
    return result


# ---------------------------------------------------------------------------
# CLI Interface
# ---------------------------------------------------------------------------

def main() -> int:
    """Main CLI entry point."""
    parser = argparse.ArgumentParser(
        description="Build JQL queries from natural language descriptions"
    )
    parser.add_argument(
        "description",
        nargs="?",
        help="Natural language description of the query",
    )
    parser.add_argument(
        "--format",
        choices=["text", "json"],
        default="text",
        help="Output format (default: text)",
    )
    parser.add_argument(
        "--patterns",
        action="store_true",
        help="List all available query patterns",
    )

    args = parser.parse_args()

    try:
        if args.patterns:
            print(format_patterns_output(args.format))
            return 0

        if not args.description:
            parser.error("description is required unless --patterns is used")

        # Build query
        result = build_jql_from_description(args.description)

        # Validate
        if result.get("jql"):
            result["validation"] = validate_jql_syntax(result["jql"])

        # Output results
        if args.format == "json":
            output = format_json_output(result)
            print(json.dumps(output, indent=2))
        else:
            output = format_text_output(result)
            print(output)

        return 0

    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    sys.exit(main())

FILE:scripts/workflow_validator.py
#!/usr/bin/env python3
"""
Workflow Validator

Validates Jira workflow definitions (JSON input) for anti-patterns and common
issues. Checks for dead-end states, orphan states, missing transitions, circular
paths, and produces a health score with severity-rated findings.

Usage:
    python workflow_validator.py workflow.json
    python workflow_validator.py workflow.json --format json
"""

import argparse
import json
import sys
from typing import Any, Dict, List, Optional, Set, Tuple


# ---------------------------------------------------------------------------
# Validation Configuration
# ---------------------------------------------------------------------------

MAX_RECOMMENDED_STATES = 10
REQUIRED_TERMINAL_STATES = {"done", "closed", "resolved", "completed"}

SEVERITY_WEIGHTS = {
    "error": 20,
    "warning": 10,
    "info": 3,
}


# ---------------------------------------------------------------------------
# Validation Rules
# ---------------------------------------------------------------------------

def check_state_count(states: List[str]) -> List[Dict[str, str]]:
    """Check if the workflow has too many states."""
    findings = []
    count = len(states)

    if count > MAX_RECOMMENDED_STATES:
        findings.append({
            "rule": "state_count",
            "severity": "warning",
            "message": f"Workflow has {count} states (recommended max: {MAX_RECOMMENDED_STATES}). "
                       f"Complex workflows slow teams down and increase error rates.",
        })
    elif count < 2:
        findings.append({
            "rule": "state_count",
            "severity": "error",
            "message": f"Workflow has only {count} state(s). A minimum of 2 states is required.",
        })

    if count > 15:
        findings[-1]["severity"] = "error"

    return findings


def check_dead_end_states(
    states: List[str],
    transitions: List[Dict[str, str]],
    terminal_states: Set[str],
) -> List[Dict[str, str]]:
    """Find states with no outgoing transitions that are not terminal."""
    findings = []
    outgoing = set()
    for t in transitions:
        outgoing.add(t.get("from", "").lower())

    for state in states:
        state_lower = state.lower()
        if state_lower not in outgoing and state_lower not in terminal_states:
            findings.append({
                "rule": "dead_end_state",
                "severity": "error",
                "message": f"State '{state}' has no outgoing transitions and is not a terminal state. "
                           f"Issues will get stuck here.",
            })

    return findings


def check_orphan_states(
    states: List[str],
    transitions: List[Dict[str, str]],
    initial_state: Optional[str],
) -> List[Dict[str, str]]:
    """Find states with no incoming transitions (except the initial state)."""
    findings = []
    incoming = set()
    for t in transitions:
        incoming.add(t.get("to", "").lower())

    initial_lower = (initial_state or "").lower()

    for state in states:
        state_lower = state.lower()
        if state_lower not in incoming and state_lower != initial_lower:
            findings.append({
                "rule": "orphan_state",
                "severity": "warning",
                "message": f"State '{state}' has no incoming transitions and is not the initial state. "
                           f"This state may be unreachable.",
            })

    return findings


def check_missing_terminal_state(states: List[str]) -> List[Dict[str, str]]:
    """Check that at least one terminal/done state exists."""
    findings = []
    states_lower = {s.lower() for s in states}

    has_terminal = bool(states_lower & REQUIRED_TERMINAL_STATES)
    if not has_terminal:
        findings.append({
            "rule": "missing_terminal_state",
            "severity": "error",
            "message": f"No terminal state found. Expected one of: {', '.join(sorted(REQUIRED_TERMINAL_STATES))}. "
                       f"Issues cannot be marked as complete.",
        })

    return findings


def check_duplicate_transition_names(
    transitions: List[Dict[str, str]],
) -> List[Dict[str, str]]:
    """Check for duplicate transition names from the same state."""
    findings = []
    seen = {}

    for t in transitions:
        name = t.get("name", "").lower()
        from_state = t.get("from", "").lower()
        key = (from_state, name)

        if key in seen:
            findings.append({
                "rule": "duplicate_transition",
                "severity": "warning",
                "message": f"Duplicate transition name '{t.get('name', '')}' from state '{t.get('from', '')}'. "
                           f"This can confuse users selecting transitions.",
            })
        else:
            seen[key] = True

    return findings


def check_missing_transitions(
    states: List[str],
    transitions: List[Dict[str, str]],
) -> List[Dict[str, str]]:
    """Check for states referenced in transitions but not defined."""
    findings = []
    defined_states = {s.lower() for s in states}

    for t in transitions:
        from_state = t.get("from", "").lower()
        to_state = t.get("to", "").lower()

        if from_state and from_state not in defined_states:
            findings.append({
                "rule": "undefined_state_reference",
                "severity": "error",
                "message": f"Transition references undefined source state '{t.get('from', '')}'.",
            })

        if to_state and to_state not in defined_states:
            findings.append({
                "rule": "undefined_state_reference",
                "severity": "error",
                "message": f"Transition references undefined target state '{t.get('to', '')}'.",
            })

    return findings


def check_circular_paths(
    states: List[str],
    transitions: List[Dict[str, str]],
    terminal_states: Set[str],
) -> List[Dict[str, str]]:
    """Detect circular paths that have no exit to a terminal state."""
    findings = []

    # Build adjacency list
    adjacency = {}
    for state in states:
        adjacency[state.lower()] = set()
    for t in transitions:
        from_state = t.get("from", "").lower()
        to_state = t.get("to", "").lower()
        if from_state in adjacency:
            adjacency[from_state].add(to_state)

    # Find strongly connected components using iterative DFS
    def can_reach_terminal(start: str) -> bool:
        visited = set()
        stack = [start]
        while stack:
            node = stack.pop()
            if node in terminal_states:
                return True
            if node in visited:
                continue
            visited.add(node)
            for neighbor in adjacency.get(node, set()):
                stack.append(neighbor)
        return False

    # Check each non-terminal state
    for state in states:
        state_lower = state.lower()
        if state_lower not in terminal_states:
            if not can_reach_terminal(state_lower):
                findings.append({
                    "rule": "circular_no_exit",
                    "severity": "error",
                    "message": f"State '{state}' cannot reach any terminal state. "
                               f"Issues entering this state will never be resolved.",
                })

    return findings


def check_self_transitions(transitions: List[Dict[str, str]]) -> List[Dict[str, str]]:
    """Check for transitions that go from a state to itself."""
    findings = []
    for t in transitions:
        if t.get("from", "").lower() == t.get("to", "").lower():
            findings.append({
                "rule": "self_transition",
                "severity": "info",
                "message": f"State '{t.get('from', '')}' has a self-transition '{t.get('name', '')}'. "
                           f"Ensure this is intentional (e.g., for triggering automation).",
            })
    return findings


# ---------------------------------------------------------------------------
# Main Validation
# ---------------------------------------------------------------------------

def validate_workflow(data: Dict[str, Any]) -> Dict[str, Any]:
    """Run all validations on a workflow definition."""
    states = data.get("states", [])
    transitions = data.get("transitions", [])
    initial_state = data.get("initial_state", states[0] if states else None)

    if not states:
        return {
            "health_score": 0,
            "grade": "invalid",
            "findings": [{"rule": "no_states", "severity": "error", "message": "No states defined in workflow"}],
            "summary": {"errors": 1, "warnings": 0, "info": 0},
        }

    # Determine terminal states
    states_lower = {s.lower() for s in states}
    terminal_states = states_lower & REQUIRED_TERMINAL_STATES

    # Custom terminal states from input
    custom_terminals = data.get("terminal_states", [])
    for ct in custom_terminals:
        terminal_states.add(ct.lower())

    # Run all checks
    all_findings = []
    all_findings.extend(check_state_count(states))
    all_findings.extend(check_dead_end_states(states, transitions, terminal_states))
    all_findings.extend(check_orphan_states(states, transitions, initial_state))
    all_findings.extend(check_missing_terminal_state(states))
    all_findings.extend(check_duplicate_transition_names(transitions))
    all_findings.extend(check_missing_transitions(states, transitions))
    all_findings.extend(check_circular_paths(states, transitions, terminal_states))
    all_findings.extend(check_self_transitions(transitions))

    # Calculate health score
    summary = {"errors": 0, "warnings": 0, "info": 0}
    penalty = 0
    for finding in all_findings:
        severity = finding["severity"]
        summary[severity] = summary.get(severity, 0) + 1
        penalty += SEVERITY_WEIGHTS.get(severity, 0)

    health_score = max(0, 100 - penalty)

    if health_score >= 90:
        grade = "excellent"
    elif health_score >= 75:
        grade = "good"
    elif health_score >= 55:
        grade = "fair"
    else:
        grade = "poor"

    return {
        "health_score": health_score,
        "grade": grade,
        "findings": all_findings,
        "summary": summary,
        "workflow_info": {
            "state_count": len(states),
            "transition_count": len(transitions),
            "initial_state": initial_state,
            "terminal_states": sorted(terminal_states),
        },
    }


# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------

def format_text_output(result: Dict[str, Any]) -> str:
    """Format results as readable text report."""
    lines = []
    lines.append("=" * 60)
    lines.append("WORKFLOW VALIDATION REPORT")
    lines.append("=" * 60)
    lines.append("")

    # Health summary
    lines.append("HEALTH SUMMARY")
    lines.append("-" * 30)
    lines.append(f"Health Score: {result['health_score']}/100")
    lines.append(f"Grade: {result['grade'].title()}")
    lines.append("")

    # Workflow info
    info = result.get("workflow_info", {})
    if info:
        lines.append("WORKFLOW INFO")
        lines.append("-" * 30)
        lines.append(f"States: {info.get('state_count', 0)}")
        lines.append(f"Transitions: {info.get('transition_count', 0)}")
        lines.append(f"Initial State: {info.get('initial_state', 'N/A')}")
        lines.append(f"Terminal States: {', '.join(info.get('terminal_states', []))}")
        lines.append("")

    # Summary
    summary = result.get("summary", {})
    lines.append("FINDINGS SUMMARY")
    lines.append("-" * 30)
    lines.append(f"Errors: {summary.get('errors', 0)}")
    lines.append(f"Warnings: {summary.get('warnings', 0)}")
    lines.append(f"Info: {summary.get('info', 0)}")
    lines.append("")

    # Detailed findings
    findings = result.get("findings", [])
    if findings:
        lines.append("DETAILED FINDINGS")
        lines.append("-" * 30)
        for i, finding in enumerate(findings, 1):
            severity = finding["severity"].upper()
            lines.append(f"{i}. [{severity}] {finding['message']}")
            lines.append(f"   Rule: {finding['rule']}")
            lines.append("")
    else:
        lines.append("No issues found. Workflow looks healthy!")

    return "\n".join(lines)


def format_json_output(result: Dict[str, Any]) -> Dict[str, Any]:
    """Format results as JSON."""
    return result


# ---------------------------------------------------------------------------
# CLI Interface
# ---------------------------------------------------------------------------

def main() -> int:
    """Main CLI entry point."""
    parser = argparse.ArgumentParser(
        description="Validate Jira workflow definitions for anti-patterns"
    )
    parser.add_argument(
        "workflow_file",
        help="JSON file containing workflow definition (states, transitions)",
    )
    parser.add_argument(
        "--format",
        choices=["text", "json"],
        default="text",
        help="Output format (default: text)",
    )

    args = parser.parse_args()

    try:
        with open(args.workflow_file, "r") as f:
            data = json.load(f)

        result = validate_workflow(data)

        if args.format == "json":
            print(json.dumps(format_json_output(result), indent=2))
        else:
            print(format_text_output(result))

        return 0

    except FileNotFoundError:
        print(f"Error: File '{args.workflow_file}' not found", file=sys.stderr)
        return 1
    except json.JSONDecodeError as e:
        print(f"Error: Invalid JSON in '{args.workflow_file}': {e}", file=sys.stderr)
        return 1
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    sys.exit(main())

FILE:_meta.json
{
  "ownerId": "kn7f2gr00xy51fj1nx2y64ckjs800mhn",
  "slug": "jira-expert-brajesh",
  "version": "1.0.1",
  "publishedAt": 1773243802844
}

ClawHub Data Analysis Product+2

O@clawhub-omesh06-e774946a82