kata-add-issue

Original：🇺🇸 English

Translated

Capture an idea, task, or issue that surfaces during a Kata session as a structured issue for later work. This skill creates markdown issue files in the .planning/issues/open directory with relevant metadata and content extracted from the conversation. Triggers include "add issue", "capture issue", "new issue", "create issue", "log issue", "file issue", "add todo" (deprecated), "capture todo" (deprecated), "new todo" (deprecated).

1installs

Sourcegannonh/kata-skills

Added on2026-02-07

NPX Install

npx skill4agent add gannonh/kata-skills kata-add-issue

SKILL.md Content

View Translation Comparison →

<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 pattern	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`
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:

Read the existing issue
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]
---

## Problem

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

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

Check if already synced:
- Read the just-created local file's frontmatter
- If
```
provenance
```
  already contains
```
github:
```
  , skip (already synced)

Create backlog label (idempotent):

bash

gh label create "backlog" --description "Kata backlog issues" --force 2>/dev/null || true

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`*

Create GitHub Issue:

bash

ISSUE_URL=$(gh issue create \
  --title "$TITLE" \
  --body-file /tmp/issue-body.md \
  --label "backlog" 2>/dev/null)

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

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:

Count issues:

find .planning/issues/open -maxdepth 1 -name "*.md" 2>/dev/null | wc -l

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:

Continue with current work
Add another issue
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>

kata-add-issue

NPX Install

Tags

SKILL.md Content