kata-add-issue

<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