Back to Details

kata-add-issue

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<objective> Capture an idea, task, or issue that surfaces during a Kata session as a structured issue for later work.
Enables "thought -> capture -> continue" flow without losing context or derailing current work. </objective>
<context> @.planning/STATE.md </context> <process> <step name="deprecation_notice"> **If the user invoked with "todo" vocabulary** (e.g., "add todo", "capture todo", "new todo"):
Display:
Note: "todos" are now "issues". Using 
/kata-add-issue
.
Then proceed with the action (non-blocking). </step>
<step name="check_and_migrate"> Check if legacy `.planning/todos/` exists and needs migration:
bash
if [ -d ".planning/todos/pending" ] && [ ! -d ".planning/todos/_archived" ]; then
  # Create new structure
  mkdir -p .planning/issues/open .planning/issues/closed

  # Copy pending todos to open issues
  cp .planning/todos/pending/*.md .planning/issues/open/ 2>/dev/null || true

  # Copy done todos to closed issues
  cp .planning/todos/done/*.md .planning/issues/closed/ 2>/dev/null || true

  # Archive originals
  mkdir -p .planning/todos/_archived
  mv .planning/todos/pending .planning/todos/_archived/ 2>/dev/null || true
  mv .planning/todos/done .planning/todos/_archived/ 2>/dev/null || true

  echo "Migrated todos to issues format"
fi
Migration is idempotent: presence of 
_archived/
indicates already migrated. </step>
<step name="ensure_directory"> ```bash mkdir -p .planning/issues/open .planning/issues/closed ``` </step> <step name="check_existing_areas"> ```bash find .planning/issues/open -maxdepth 1 -name "*.md" 2>/dev/null | xargs -I {} grep "^area:" {} 2>/dev/null | cut -d' ' -f2 | sort -u ```
Note existing areas for consistency in infer_area step. </step>
<step name="extract_content"> **With arguments:** Use as the title/focus. - `/kata-add-issue Add auth token refresh` -> title = "Add auth token refresh"
Without arguments: Analyze recent conversation to extract:
  • The specific problem, idea, or task discussed
  • Relevant file paths mentioned
  • Technical details (error messages, line numbers, constraints)
Formulate:
  • title
    : 3-10 word descriptive title (action verb preferred)
  • problem
    : What's wrong or why this is needed
  • solution
    : Approach hints or "TBD" if just an idea
  • files
    : Relevant paths with line numbers from conversation
  • provenance
    : (optional) Origin of the issue - "local" (default), "github:owner/repo#N", or other external reference </step>
<step name="infer_area"> Infer area from file paths:
Path patternArea
src/api/*
, 
api/*
api
src/components/*
, 
src/ui/*
ui
src/auth/*
, 
auth/*
auth
src/db/*
, 
database/*
database
tests/*
, 
__tests__/*
testing
docs/*
docs
.planning/*
planning
scripts/*
, 
bin/*
tooling
No files or unclear
general
Use existing area from step 2 if similar match exists. </step>
<step name="check_duplicates"> ```bash find .planning/issues/open -maxdepth 1 -name "*.md" -exec grep -l -i "[key words from title]" {} + 2>/dev/null ```
If potential duplicate found:
  1. Read the existing issue
  2. Compare scope
If overlapping, use AskUserQuestion:
  • header: "Duplicate?"
  • question: "Similar issue exists: [title]. What would you like to do?"
  • options:
    • "Skip" - keep existing issue
    • "Replace" - update existing with new context
    • "Add anyway" - create as separate issue </step>
<step name="create_file"> ```bash timestamp=$(date "+%Y-%m-%dT%H:%M") date_prefix=$(date "+%Y-%m-%d") ```
Generate slug from title (lowercase, hyphens, no special chars).
Write to 
.planning/issues/open/${date_prefix}-${slug}.md
:
markdown
---
created: [timestamp]
title: [title]
area: [area]
provenance: [provenance or "local"]
files:
  - [file:lines]
---
<objective> 在Kata会话中捕获出现的想法、任务或问题，将其整理为结构化的问题以便后续处理。
支持“思考 -> 捕获 -> 继续”的流程，不会丢失上下文或打断当前工作。 </objective>
<context> @.planning/STATE.md </context> <process> <step name="deprecation_notice"> **如果用户使用了"todo"相关指令**（例如"add todo"、"capture todo"、"new todo"）：
显示：
注意： "todos"现已更名为"issues"。将使用
/kata-add-issue
指令。
然后继续执行操作（无阻塞）。 </step>
<step name="check_and_migrate"> 检查是否存在旧的`.planning/todos/`目录并需要迁移：
bash
if [ -d ".planning/todos/pending" ] && [ ! -d ".planning/todos/_archived" ]; then
  # Create new structure
  mkdir -p .planning/issues/open .planning/issues/closed

  # Copy pending todos to open issues
  cp .planning/todos/pending/*.md .planning/issues/open/ 2>/dev/null || true

  # Copy done todos to closed issues
  cp .planning/todos/done/*.md .planning/issues/closed/ 2>/dev/null || true

  # Archive originals
  mkdir -p .planning/todos/_archived
  mv .planning/todos/pending .planning/todos/_archived/ 2>/dev/null || true
  mv .planning/todos/done .planning/todos/_archived/ 2>/dev/null || true

  echo "Migrated todos to issues format"
fi
迁移操作是幂等的：如果存在
_archived/
目录，则表示已完成迁移。 </step>
<step name="ensure_directory"> ```bash mkdir -p .planning/issues/open .planning/issues/closed ``` </step> <step name="check_existing_areas"> ```bash find .planning/issues/open -maxdepth 1 -name "*.md" 2>/dev/null | xargs -I {} grep "^area:" {} 2>/dev/null | cut -d' ' -f2 | sort -u ```
记录已存在的领域，以便在infer_area步骤中保持一致性。 </step>
<step name="extract_content"> **带参数时：** 将参数用作标题/核心内容。 - `/kata-add-issue Add auth token refresh` -> 标题 = "Add auth token refresh"
不带参数时： 分析近期对话内容以提取：
  • 讨论的具体问题、想法或任务
  • 提到的相关文件路径
  • 技术细节（错误信息、行号、约束条件）
整理为：
  • title
    ：3-10个词的描述性标题（优先使用动作动词）
  • problem
    ：问题所在或需求原因
  • solution
    ：方法提示，若只是想法则填"TBD"
  • files
    ：对话中提到的相关路径及行号
  • provenance
    ：（可选）问题来源 - "local"（默认）、"github:owner/repo#N"或其他外部引用 </step>
<step name="infer_area"> 根据文件路径推断领域：
路径模式领域
src/api/*
, 
api/*
api
src/components/*
, 
src/ui/*
ui
src/auth/*
, 
auth/*
auth
src/db/*
, 
database/*
database
tests/*
, 
__tests__/*
testing
docs/*
docs
.planning/*
planning
scripts/*
, 
bin/*
tooling
无文件或不明确
general
如果有匹配的情况，使用步骤2中已存在的领域。 </step>
<step name="check_duplicates"> ```bash find .planning/issues/open -maxdepth 1 -name "*.md" -exec grep -l -i "[key words from title]" {} + 2>/dev/null ```
如果发现潜在重复项：
  1. 读取已存在的问题
  2. 比较范围
如果存在重叠，使用AskUserQuestion：
  • 标题: "Duplicate?"
  • 问题: "存在相似问题：[title]。您想要如何处理？"
  • 选项:
    • "Skip" - 保留现有问题
    • "Replace" - 用新上下文更新现有问题
    • "Add anyway" - 作为独立问题创建 </step>
<step name="create_file"> ```bash timestamp=$(date "+%Y-%m-%dT%H:%M") date_prefix=$(date "+%Y-%m-%d") ```
根据标题生成slug（小写、连字符连接、无特殊字符）。
写入文件
.planning/issues/open/${date_prefix}-${slug}.md
：
markdown
---
created: [timestamp]
title: [title]
area: [area]
provenance: [provenance or "local"]
files:
  - [file:lines]
---

Problem

Problem

[problem description - enough context for future Claude to understand weeks later]
[problem description - enough context for future Claude to understand weeks later]

Solution

Solution

[approach hints or "TBD"]
</step>

<step name="sync_to_github">
**Check GitHub integration:**

```bash
GITHUB_ENABLED=$(cat .planning/config.json 2>/dev/null | grep -o '"enabled"[[:space:]]*:[[:space:]]*[^,}]*' | head -1 | grep -o 'true\|false' || echo "false")
If 
GITHUB_ENABLED=false
: Log "Local-only issue (GitHub integration disabled)" and skip to next step.
If 
GITHUB_ENABLED=true
:
  1. Check if already synced:
    • Read the just-created local file's frontmatter
    • If 
      provenance
      already contains 
      github:
      , skip (already synced)
  2. Create backlog label (idempotent):
    bash
    gh label create "backlog" --description "Kata backlog issues" --force 2>/dev/null || true
  3. Build issue body file: Write to 
    /tmp/issue-body.md
    :
    markdown
    ## Problem

[problem section from local file]

## Solution

[solution section from local file]

---
*Created via Kata `/kata-add-issue`*
  4. Create GitHub Issue:
    bash
    ISSUE_URL=$(gh issue create \
  --title "$TITLE" \
  --body-file /tmp/issue-body.md \
  --label "backlog" 2>/dev/null)
  5. Extract issue number and update provenance:
    bash
    if [ -n "$ISSUE_URL" ]; then
  ISSUE_NUMBER=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')
  REPO_NAME=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null)
  # Update local file's frontmatter with provenance
  # provenance: github:owner/repo#N
fi
  6. Update local file frontmatter:
    • Read the local issue file
    • Replace 
      provenance: local
      with 
      provenance: github:${REPO_NAME}#${ISSUE_NUMBER}
    • Write updated file
Non-blocking error handling: All GitHub operations are wrapped to warn but continue on failure. Local file creation is never blocked by GitHub failures.
bash
if ! gh auth status &>/dev/null; then
  echo "Warning: gh CLI not authenticated. GitHub sync skipped."
fi
</step> <step name="update_state"> If `.planning/STATE.md` exists:
  1. Count issues: 
    find .planning/issues/open -maxdepth 1 -name "*.md" 2>/dev/null | wc -l
  2. Update "### Pending Issues" under "## Accumulated Context" </step>
<step name="git_commit"> Commit the issue and any updated state:
Check planning config:
bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
If 
COMMIT_PLANNING_DOCS=false
: Skip git operations, log "Issue saved (not committed - commit_docs: false)"
If 
COMMIT_PLANNING_DOCS=true
(default):
bash
git add .planning/issues/open/[filename]
[ -f .planning/STATE.md ] && git add .planning/STATE.md
git commit -m "$(cat <<'EOF'
docs(issue): capture issue - [title]

Area: [area]
EOF
)"
Confirm: "Committed: docs(issue): capture issue - [title]" </step>
<step name="confirm"> ``` Issue saved: .planning/issues/open/[filename]
[title] Area: [area] Files: [count] referenced GitHub: #[number] (if synced, otherwise "local only")
Would you like to:
  1. Continue with current work
  2. Add another issue
  3. View all issues (/kata-check-issues)
</step>

</process>

<output>
- `.planning/issues/open/[date]-[slug].md`
- Updated `.planning/STATE.md` (if exists)
- GitHub Issue #N with `backlog` label (if github.enabled=true)
</output>

<anti_patterns>
- Don't create issues for work in current plan (that's deviation rule territory)
- Don't create elaborate solution sections - captures ideas, not plans
- Don't block on missing information - "TBD" is fine
</anti_patterns>

<success_criteria>
- [ ] Directory structure exists
- [ ] Issue file created with valid frontmatter
- [ ] Problem section has enough context for future Claude
- [ ] No duplicates (checked and resolved)
- [ ] Area consistent with existing issues
- [ ] STATE.md updated if exists
- [ ] Issue and state committed to git
- [ ] GitHub Issue created with backlog label (if github.enabled=true)
- [ ] Provenance field set in local file (if GitHub synced)
</success_criteria>
[approach hints or "TBD"]
</step>

<step name="sync_to_github">
**检查GitHub集成：**

```bash
GITHUB_ENABLED=$(cat .planning/config.json 2>/dev/null | grep -o '"enabled"[[:space:]]*:[[:space:]]*[^,}]*' | head -1 | grep -o 'true\|false' || echo "false")
如果
GITHUB_ENABLED=false
： 记录“本地仅存问题（GitHub集成已禁用）”并跳至下一步。
如果
GITHUB_ENABLED=true
：
  1. 检查是否已同步：
    • 读取刚创建的本地文件的前置元数据
    • 如果
      provenance
      已包含
      github:
      ，则跳过（已完成同步）
  2. 创建backlog标签（幂等操作）：
    bash
    gh label create "backlog" --description "Kata backlog issues" --force 2>/dev/null || true
  3. 构建问题内容文件： 写入文件
    /tmp/issue-body.md
    ：
    markdown
    ## Problem

[problem section from local file]

## Solution

[solution section from local file]

---
*Created via Kata `/kata-add-issue`*
  4. 创建GitHub Issue：
    bash
    ISSUE_URL=$(gh issue create \
  --title "$TITLE" \
  --body-file /tmp/issue-body.md \
  --label "backlog" 2>/dev/null)
  5. 提取问题编号并更新来源信息：
    bash
    if [ -n "$ISSUE_URL" ]; then
  ISSUE_NUMBER=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')
  REPO_NAME=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null)
  # Update local file's frontmatter with provenance
  # provenance: github:owner/repo#N
fi
  6. 更新本地文件的前置元数据：
    • 读取本地问题文件
    • 将
      provenance: local
      替换为
      provenance: github:${REPO_NAME}#${ISSUE_NUMBER}
    • 写入更新后的文件
非阻塞错误处理： 所有GitHub操作均已包装，失败时仅发出警告但继续执行。本地文件的创建不会因GitHub操作失败而被阻塞。
bash
if ! gh auth status &>/dev/null; then
  echo "Warning: gh CLI not authenticated. GitHub sync skipped."
fi
</step> <step name="update_state"> 如果`.planning/STATE.md`存在：
  1. 统计问题数量：
    find .planning/issues/open -maxdepth 1 -name "*.md" 2>/dev/null | wc -l
  2. 更新“## Accumulated Context”下的“### Pending Issues”部分 </step>
<step name="git_commit"> 提交问题文件及所有更新的状态：
检查规划配置：
bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
如果
COMMIT_PLANNING_DOCS=false
： 跳过git操作，记录“问题已保存（未提交 - commit_docs: false）”
如果
COMMIT_PLANNING_DOCS=true
（默认）：
bash
git add .planning/issues/open/[filename]
[ -f .planning/STATE.md ] && git add .planning/STATE.md
git commit -m "$(cat <<'EOF'
docs(issue): capture issue - [title]

Area: [area]
EOF
)"
确认：“已提交：docs(issue): capture issue - [title]” </step>
<step name="confirm"> ``` Issue saved: .planning/issues/open/[filename]
[title] Area: [area] Files: [count] referenced GitHub: #[number] (if synced, otherwise "local only")
Would you like to:
  1. Continue with current work
  2. Add another issue
  3. View all issues (/kata-check-issues)
</step>

</process>

<output>
- `.planning/issues/open/[date]-[slug].md`
- 更新后的`.planning/STATE.md`（如果存在）
- 带有`backlog`标签的GitHub Issue #N（如果github.enabled=true）
</output>

<anti_patterns>
- 不要为当前计划中的工作创建问题（这属于偏差规则范畴）
- 不要创建复杂的解决方案部分 - 仅捕获想法，而非完整计划
- 不要因信息缺失而阻塞 - 填"TBD"即可
</anti_patterns>

<success_criteria>
- [ ] 目录结构已存在
- [ ] 已创建包含有效前置元数据的问题文件
- [ ] 问题部分包含足够上下文，方便未来Claude在数周后理解
- [ ] 无重复项（已检查并解决）
- [ ] 领域与现有问题保持一致
- [ ] 若存在STATE.md则已更新
- [ ] 问题和状态已提交至git
- [ ] 已创建带有backlog标签的GitHub Issue（如果github.enabled=true）
- [ ] 本地文件中已设置来源字段（如果已同步至GitHub）
</success_criteria>