---
name: update-gotchas
description: "Analyze the current session for mistakes, tool failures, workarounds, and misusages that occurred while executing a skill, then append them to that skill's Gotchas section. Use when the user says '/update-gotchas', 'gotcha 업데이트', 'gotcha 추가', '실수 기록', or asks to record mistakes/lessons learned from the current session into a skill. Also trigger when the user says something like 'add what went wrong to the skill' or '이번 세션 실수 정리해줘'. Do NOT use for creating new skills (use skill-master/skill-creator) or general SKILL.md editing."
---

# Update Gotchas

You analyze the current conversation for operational mistakes, tool misusages, silent failures, and workarounds that occurred during skill execution, then append them to the target skill's Gotchas section.

---

## Step 1: Identify Target Skill

Determine which skill to update:

1. If the user specifies a skill name or path, use that.
2. Otherwise, scan the current conversation for skill invocations (look for `<command-name>` tags or Skill tool calls). Pick the primary skill that was executed.
3. Locate the skill's `SKILL.md` file:
   - Project skills: `.claude/skills/{name}/SKILL.md` (relative to git root)
   - Global skills: `~/.claude/skills/{name}/SKILL.md`
4. Read the SKILL.md to understand its structure and check if a `## Gotchas` section already exists.

If multiple skills were used, ask the user which one to update.

## Step 2: Mine the Conversation for Gotchas

Scan the conversation history for these patterns:

### What counts as a gotcha

- **Tool failures**: a tool call that returned an error and required a workaround (e.g., Write failing because Read wasn't called first)
- **Silent failures**: something that appeared to succeed but produced wrong/incomplete results (e.g., subagent files polluting discovery)
- **Missing prerequisites**: an assumption that turned out to be wrong (e.g., `tree` command not installed)
- **Schema/data mismatches**: old data lacking new fields, format incompatibilities
- **Filter gaps**: items that should have been excluded but weren't (e.g., subagent JSONL files)
- **Ordering mistakes**: steps executed in wrong order causing failures
- **Environment-specific issues**: things that work on one OS but not another

### What does NOT count

- Normal development iteration (trying approach A, switching to B because B is better)
- User-requested changes or preference adjustments
- One-time typos or copy-paste errors with no risk of recurrence
- Issues already documented in the existing Gotchas section
- **Improvement requests disguised as gotchas**: "the agent skips review too often" or "batch size should be larger" are suggestions to change the skill's behavior, not traps to avoid. A gotcha says "watch out for X", an improvement request says "X should work differently". Route improvements to the user as conversation feedback, not as gotcha entries.

## Step 3: Draft Gotcha Entries

For each gotcha found, write a concise entry:

```
N. **Short descriptive title**: Explanation of what went wrong, why it's a trap, and what to do instead. Keep it to 2-3 sentences max. Include the specific error or symptom if it helps recognition.
```

Good gotcha entries are:
- **Recognizable**: someone hitting the same issue should immediately think "oh, that's what this is"
- **Actionable**: clearly states what to do (or not do) to avoid the problem
- **Non-obvious**: if the fix is obvious from the error message, it probably doesn't need a gotcha

## Step 4: Present and Confirm

Show the user:
1. Target skill path
2. Existing gotchas (if any) — to avoid duplicates
3. Proposed new gotcha entries

Ask for confirmation before modifying the file.

## Step 5: Update SKILL.md

1. If `## Gotchas` section exists:
   - Read existing entries to determine the next number
   - Append new entries at the end, continuing the numbering
2. If no `## Gotchas` section:
   - Add it as the last section before any closing content
   - Add a brief intro line: `Mistakes observed in past executions — avoid repeating these:`
3. Use `Edit` to make the change (not Write, to preserve the rest of the file).

## Output

After updating, print:

```
=== Gotcha Update ===
Skill: {skill_name} ({skill_path})
Added: {count}
Existing: {existing_count}
Total: {total_count}
```

## Gotchas

Mistakes observed in past executions — avoid repeating these:

1. **Must Read before Edit**: Always Read the SKILL.md before using Edit to modify it. Edit will fail if the file hasn't been read first in the conversation.
2. **Continue existing numbering**: Check the last number in existing Gotchas entries before adding new ones. Starting from 1 when entries already exist causes duplicate numbering.
3. **Don't misclassify improvement requests as gotchas**: "Batch size should be larger" is a feature request, not a gotcha. Strictly apply the "What does NOT count" criteria in Step 2.
4. **Match content language to the skill, not CLAUDE.md**: When writing gotcha entries, use the same language as the skill's existing content. CLAUDE.md's "Always respond in 한국어" applies to user-facing conversation, not to file content written into SKILL.md files.