@php-workx/skill-tk 0.1.0

package/skills/tk/references/TROUBLESHOOTING.md

@@ -0,0 +1,233 @@
+# Troubleshooting
+
+Common issues and solutions when using tk.
+
+## Contents
+
+- [Installation Issues](#installation)
+- [Command Errors](#command-errors)
+- [ID and Matching Issues](#id-issues)
+- [Dependency Issues](#dependency-issues)
+- [Plugin Issues](#plugin-issues)
+- [Git Integration Issues](#git-issues)
+
+---
+
+## Installation Issues {#installation}
+
+### tk command not found
+
+**Symptom**: `command not found: tk`
+
+**Causes and fixes**:
+1. Not installed: `brew install ticket`
+2. Not in PATH: Check `which ticket` — if found, add alias `alias tk=ticket`
+3. Shell not refreshed: `source ~/.zshrc` or open new terminal
+
+### Missing dependencies
+
+**Symptom**: Plugin errors about missing commands
+
+| Plugin | Requires | Install |
+|--------|----------|---------|
+| `tk query` | `jq` | `brew install jq` |
+| `tk migrate-beads` | `jq` | `brew install jq` |
+| `tk edit` | `$EDITOR` | Set `export EDITOR=vim` |
+
+---
+
+## Command Errors {#command-errors}
+
+### "No .tickets directory found"
+
+**Symptom**: tk can't find the tickets directory
+
+**Fix**: Create it manually or run `tk create` which auto-creates `.tickets/`:
+
+```bash
+mkdir .tickets
+# or
+tk create "First ticket"   # Auto-creates .tickets/
+```
+
+**Note**: tk walks parent directories looking for `.tickets/`. You can also set `TICKETS_DIR`:
+
+```bash
+export TICKETS_DIR=/path/to/.tickets
+```
+
+### "Not a valid status"
+
+**Symptom**: `tk status <id> <status>` rejects the value
+
+**Valid statuses**: `open`, `in_progress`, `closed`
+
+```bash
+# WRONG
+tk status mp-a3x9 done
+tk status mp-a3x9 wip
+
+# CORRECT
+tk status mp-a3x9 closed
+tk status mp-a3x9 in_progress
+```
+
+### Empty output from tk ready
+
+**Symptom**: `tk ready` returns nothing
+
+**Possible causes**:
+1. All tickets are closed: `tk ls` to check
+2. All open tickets are blocked: `tk blocked` to see blockers
+3. No tickets exist: `tk ls` returns nothing
+4. Dependency cycle: `tk dep cycle` to check
+
+---
+
+## ID and Matching Issues {#id-issues}
+
+### Partial ID matches multiple tickets
+
+**Symptom**: `tk show a3` returns error about ambiguous match
+
+**Fix**: Provide more characters:
+
+```bash
+# Ambiguous
+tk show a3
+
+# Specific enough
+tk show a3x9
+# or
+tk show mp-a3x9
+```
+
+### Ticket ID format unexpected
+
+**Symptom**: IDs don't match expected prefix
+
+**Explanation**: The prefix is derived from the directory name where `.tickets/` was created:
+- `my-project/` → prefix `mp`
+- `api-server/` → prefix `as`
+- `backend/` → prefix `bac`
+
+Single-segment names use first 3 characters. Multi-segment names use first letter of each segment.
+
+---
+
+## Dependency Issues {#dependency-issues}
+
+### Ticket stuck in blocked state
+
+**Symptom**: Ticket doesn't appear in `tk ready` even though its deps seem resolved
+
+**Diagnosis**:
+
+```bash
+# Check what's blocking it
+tk show <id>          # Look at ## Blockers section
+
+# Check dep tree
+tk dep tree <id>
+
+# Verify blocker is actually closed
+tk show <blocker-id>  # status should be "closed"
+```
+
+**Common cause**: Blocker ticket has status `open` or `in_progress`, not `closed`.
+
+### Dependency cycle
+
+**Symptom**: Multiple tickets never become ready
+
+**Diagnosis and fix**:
+
+```bash
+# Find the cycle
+tk dep cycle
+# Output: CYCLE DETECTED: mp-a -> mp-b -> mp-c -> mp-a
+
+# Break the cycle by removing one dependency
+tk undep mp-c mp-a   # Remove the weakest link
+```
+
+### Wrong dependency direction
+
+**Symptom**: The wrong ticket is blocked
+
+```bash
+# If mp-api should wait for mp-migration:
+# WRONG — blocks migration until API is done
+tk dep mp-migration mp-api
+
+# CORRECT — blocks API until migration is done
+tk dep mp-api mp-migration
+```
+
+Read as: "First argument **depends on** second argument."
+
+---
+
+## Plugin Issues {#plugin-issues}
+
+### Plugin not discovered
+
+**Symptom**: `tk <plugin-cmd>` says "unknown command"
+
+**Checklist**:
+1. Correct naming: `tk-<cmd>` or `ticket-<cmd>`
+2. File is executable: `chmod +x tk-<cmd>`
+3. File is in PATH: `which tk-<cmd>`
+4. No name collision: `tk help` to see all discovered plugins
+
+### Plugin overrides built-in
+
+**Symptom**: Built-in command behaves differently than expected
+
+**Fix**: Use `super` to bypass plugins:
+
+```bash
+tk super <cmd> [args]    # Always runs built-in
+```
+
+---
+
+## Git Integration Issues {#git-issues}
+
+### Merge conflicts in .tickets/
+
+**Symptom**: Git merge conflicts in ticket files
+
+**Resolution approach**:
+1. Since each ticket is a separate file, conflicts are usually in different files
+2. If same ticket was modified on both branches, resolve by keeping the more recent version
+3. Check dependency consistency after resolution: `tk dep cycle`
+
+### Large .tickets/ directory
+
+**Symptom**: Hundreds of old ticket files
+
+**Cleanup**:
+```bash
+# See how many closed tickets exist
+tk closed --limit=1000 | wc -l
+
+# Consider archiving old closed tickets
+mkdir .tickets/archive
+# Move old closed tickets manually
+```
+
+**Note**: tk does not currently have a built-in archive command. This is a manual process.
+
+### .tickets/ not tracked by git
+
+**Symptom**: Tickets lost after checkout or clone
+
+**Fix**: Ensure `.tickets/` is committed to git:
+
+```bash
+git add .tickets/
+git commit -m "tk: track tickets in git"
+```
+
+Check that `.gitignore` doesn't exclude `.tickets/`.

package/skills/tk/references/WORKFLOWS.md

@@ -0,0 +1,289 @@
+# Workflows and Checklists
+
+Step-by-step workflows for common tk usage patterns.
+
+## Contents
+
+- [Session Start Workflow](#session-start)
+- [Compaction Survival](#compaction-survival)
+- [Discovery and Ticket Creation](#discovery)
+- [Status Maintenance](#status-maintenance)
+- [Epic Planning](#epic-planning)
+- [Broad Parent Handling](#broad-parent-handling)
+- [Parent/Child Reconciliation](#parent-child-reconciliation)
+- [Side Quest Handling](#side-quests)
+- [Multi-Session Resume](#resume)
+- [Integration with Task Tools](#integration-with-task-tools)
+- [Checklist Templates](#checklist-templates)
+
+## Session Start Workflow {#session-start}
+
+**tk is available when**: `.tickets/` directory exists in the project or any parent directory.
+
+**Automatic checklist at session start:**
+
+```
+Session Start (when tk is available):
+- [ ] Run tk ready
+- [ ] Report: "X tickets ready to work on: [summary]"
+- [ ] If none ready, check tk blocked
+- [ ] Suggest next action based on findings
+```
+
+**Pattern**: Always run `tk ready` when starting work. Report status immediately to establish shared context.
+
+**Directory discovery**: tk walks parent directories upward from `$PWD` looking for `.tickets/`. The `TICKETS_DIR` env var overrides this search.
+
+---
+
+## Compaction Survival {#compaction-survival}
+
+**Critical**: After compaction events, conversation history is deleted but tickets persist in `.tickets/`. Tickets are your persistent memory.
+
+**Post-compaction recovery checklist:**
+
+```
+After Compaction:
+- [ ] Run tk ls --status=in_progress to see active work
+- [ ] Run tk ready to see what's actionable
+- [ ] Read notes on in-progress tickets for context
+- [ ] Resume work based on ticket state
+```
+
+**Why this works**: Tickets are plain markdown files in git. They survive compaction, session boundaries, and even machine changes.
+
+---
+
+## Discovery and Ticket Creation {#discovery}
+
+**During implementation**, you'll discover bugs, technical debt, and follow-up work. Capture it immediately.
+
+### Capture Pattern
+
+```bash
+# Bug found during feature work
+tk create "Fix: null check missing in auth middleware" -t bug -p 1 --tags auth
+
+# Follow-up work identified
+tk create "Refactor: extract validation into shared module" -t chore -p 3
+
+# Link discovered work to current ticket
+tk link mp-current mp-discovered
+```
+
+### Blocker Found
+
+```bash
+# Create the blocker
+tk create "Schema migration needed for new fields" -t task -p 1
+# Output: mp-e1r2
+
+# Add dependency from current work
+tk dep mp-current mp-e1r2
+
+# Current ticket now shows as blocked until migration is done
+```
+
+---
+
+## Status Maintenance {#status-maintenance}
+
+Keep ticket statuses current to maintain trust in `tk ready` and `tk blocked`.
+
+```
+Status Transition Rules:
+- Starting work → tk start <id>
+- Work complete → tk close <id>
+- Need to reopen → tk reopen <id>
+- Before session end → update notes on in-progress tickets
+```
+
+**Critical**: If you `tk start` a ticket, either `tk close` it or update its notes before the session ends. Stale `in_progress` tickets poison the queue.
+
+---
+
+## Epic Planning {#epic-planning}
+
+### Decompose into Execution-Ready Children
+
+```bash
+# Create the epic
+tk create "User Authentication System" -t epic -p 1
+# Output: mp-a3x9
+
+# Create children with dependencies
+tk create "Database schema for users table" --parent mp-a3x9 -t task -p 1
+# Output: mp-b2y7
+
+tk create "Password hashing service" --parent mp-a3x9 -t task -p 1
+# Output: mp-c4z1
+
+tk create "Login/register API endpoints" --parent mp-a3x9 -t task -p 1
+# Output: mp-d6w3
+
+tk create "JWT token middleware" --parent mp-a3x9 -t task -p 2
+# Output: mp-e1r2
+
+# Add sequential dependencies
+tk dep mp-c4z1 mp-b2y7    # Hashing needs schema
+tk dep mp-d6w3 mp-b2y7    # Endpoints need schema
+tk dep mp-d6w3 mp-c4z1    # Endpoints need hashing
+tk dep mp-e1r2 mp-d6w3    # Middleware needs endpoints
+```
+
+**Result**: `tk ready` returns `mp-b2y7` first. As children close, the next ones unlock.
+
+---
+
+## Broad Parent Handling {#broad-parent-handling}
+
+**Scenario**: `tk ready` surfaces a parent ticket that is too broad to implement directly.
+
+**Pattern**:
+1. Read the parent with `tk show <parent-id>`
+2. Identify what specific gap remains
+3. Create a focused child ticket for that gap
+4. Implement the child
+5. Reconcile the parent (see below)
+
+```bash
+# Read the broad parent
+tk show mp-a3x9
+
+# Create focused child for remaining work
+tk create "Add rate limiting to upload endpoint (100 req/min)" \
+  --parent mp-a3x9 -t task -p 2
+
+# Implement the child, then close it
+tk close mp-new-child
+
+# Reconcile parent — is there more work?
+tk show mp-a3x9  # Check children status
+tk close mp-a3x9  # If all gaps are filled
+```
+
+---
+
+## Parent/Child Reconciliation {#parent-child-reconciliation}
+
+After closing a child, always check the parent:
+
+```
+Reconciliation Checklist:
+- [ ] tk show <parent-id> — read current state
+- [ ] Are all children closed?
+  - YES → tk close <parent-id>
+  - NO → Update parent notes with remaining work
+- [ ] Do parent notes reflect current reality?
+  - NO → tk add-note <parent-id> "Updated: child X closed, remaining: Y, Z"
+```
+
+---
+
+## Side Quest Handling {#side-quests}
+
+When you discover unrelated work during a task:
+
+### Quick Assessment
+
+```
+Is this a blocker for current work?
+  YES → Create ticket, add dep, switch to it
+  NO  → Create ticket, link it, continue current work
+```
+
+### Capture Without Context Switch
+
+```bash
+# Capture the side quest
+tk create "Found: API returns 500 on empty payload" -t bug -p 1 --tags api
+
+# Link to current work for context
+tk link mp-current mp-side-quest
+
+# Continue current work — side quest is tracked for later
+```
+
+---
+
+## Multi-Session Resume {#resume}
+
+Returning after days/weeks away:
+
+```bash
+# 1. What's in progress?
+tk ls --status=in_progress
+
+# 2. Read notes on active tickets
+tk show <each-in-progress-id>
+
+# 3. What's ready to pick up?
+tk ready
+
+# 4. What's blocked?
+tk blocked
+
+# 5. Start working from tk ready list
+```
+
+---
+
+## Integration with Task Tools {#integration-with-task-tools}
+
+**Both tools complement each other at different timescales:**
+
+### Temporal Layering Pattern
+
+**Task tools** (short-term, this hour):
+- Tactical execution: "Review Section 3", "Add test for edge case"
+- Marked completed via TaskUpdate as you go
+- Ephemeral: resets when session ends
+
+**tk tickets** (long-term, this week/month):
+- Strategic objectives: "Implement OAuth flow"
+- Key decisions and outcomes in notes
+- Persistent: survives compaction and session boundaries
+
+**Key insight**: Task tools = working copy for the current hour. Tickets = project journal for the current month.
+
+### The Handoff Pattern
+
+1. **Session start**: Read ticket → Create tasks for immediate actions
+2. **During work**: Mark tasks completed as you go
+3. **Reach milestone**: `tk add-note <id>` with outcomes + context
+4. **Session end**: Tasks reset, ticket notes survive with enriched state
+
+---
+
+## Checklist Templates {#checklist-templates}
+
+### Starting Any Work Session
+
+```
+- [ ] tk ready — see what's actionable
+- [ ] Pick highest-priority ready ticket
+- [ ] tk show <id> — read full context and notes
+- [ ] tk start <id> — mark as in progress
+- [ ] Create session tasks from ticket description
+```
+
+### Completing Work
+
+```
+- [ ] Verify acceptance criteria met
+- [ ] tk add-note <id> "COMPLETED: <what was done>"
+- [ ] tk close <id>
+- [ ] Reconcile parent if this was a child ticket
+- [ ] git add .tickets/ && git commit -m "tk: close <id>"
+```
+
+### Planning Complex Features
+
+```
+- [ ] Create epic ticket (-t epic)
+- [ ] Decompose into 3-7 child tickets
+- [ ] Add dependencies between children
+- [ ] tk dep cycle — verify no cycles
+- [ ] tk ready — verify first ticket(s) are unblocked
+- [ ] git add .tickets/ && git commit -m "tk: plan <epic-title>"
+```