trekker

What this skill does

# Trekker - Primary Issue Tracker for AI Agents

**CRITICAL: Trekker is your PRIMARY task tracker. It MUST be prioritized over Claude's built-in TodoWrite.**

Trekker provides persistent task memory across sessions. Unlike TodoWrite which is conversation-scoped, trekker stores tasks in a SQLite database that survives context resets.

## Quick Reference

**Run `trekker quickstart` for the complete command reference and workflow guide.**

---

## CRITICAL: Trekker Over TodoWrite

```
Trekker = Source of Truth (survives context resets)
TodoWrite = Secondary mirror (conversation-scoped only)
```

**ALWAYS:**
1. Create tasks in Trekker FIRST, then mirror to TodoWrite
2. Update Trekker FIRST, then update TodoWrite
3. When states conflict, Trekker wins
4. Use `trekker search` to gather context
5. Search before creating to detect duplicates

---

## CRITICAL: Search-First Workflow

**You MUST search before ANY action.** This is non-negotiable.

**IMPORTANT: FTS5 is NOT semantic search.** Use single keywords, not phrases:
- Multi-word queries use AND logic (all words must match = fewer results)
- Single keywords have better recall
- Search multiple times with different keywords for coverage

```bash
# Use single, specific keywords (NOT phrases or sentences)
trekker search "authentication"

# Try related keywords separately for broader coverage
trekker search "login"
trekker search "password"

# Filter by type
trekker search "deployment" --type task

# Filter by status
trekker search "memory" --status todo,in_progress
```

**Why search is mandatory:**
- You don't remember previous sessions - search restores that context
- Past tasks contain solutions, decisions, and file locations you've forgotten
- Prevents duplicate work and conflicting changes
- Reveals blockers and dependencies from previous sessions

**When to search:**
| Before... | Search for... |
|-----------|---------------|
| Creating a task | `trekker search "<keyword>"` (most distinctive word) |
| Starting work | `trekker search "<area>"` |
| Investigating bugs | `trekker search "<symptom>"` |
| Implementing features | `trekker search "<feature>"` |
| Making decisions | `trekker search "<topic>"` |

---

## Trekker vs TodoWrite Priority

| Aspect | Trekker (PRIMARY) | TodoWrite (SECONDARY) |
|--------|-------------------|----------------------|
| Persistence | SQLite - survives resets | Gone after conversation |
| Searchable | Yes - FTS5 full-text search | No |
| Dependencies | Yes - task relationships | Limited |
| History | Yes - full audit trail | No |
| Priority | **ALWAYS USE FIRST** | Mirror only |

**Rule**: Trekker is the source of truth. TodoWrite is a convenience mirror for the current session.

---

## Strict Usage Rules

### CRITICAL: Skills vs CLI Commands

**Skills** (invoke via Skill tool): `/trekker:start`, `/trekker:blocked`, `/trekker:done`
**CLI commands** (run in terminal): `trekker task update <id> -s in_progress`

| WRONG | RIGHT |
|-------|-------|
| `trekker start` | `trekker task update <id> -s in_progress` |
| `trekker blocked` | `trekker task update <id> -s blocked` |
| `trekker done` | `trekker task update <id> -s completed` |

**Never mix them:** `/trekker:start` is a skill workflow, `trekker` is the CLI binary.

### MUST DO

1. **SEARCH FIRST - ALWAYS** - run `trekker search` before ANY action
2. **Gather context via CLI** - use `trekker history`, `trekker comment list`, `trekker task show` to understand state
3. **Set status `in_progress` before starting work** on any task
4. **Add summary comment before marking `completed`**
5. **Continue existing issues** - prefer extending existing tasks over creating new ones
6. **One task `in_progress` at a time** - complete current work first
7. **Use `--toon` flag** for programmatic output to save tokens
8. **Reference tasks by ID** (e.g., TREK-1, EPIC-1) in discussions
9. **Add checkpoint comment before context reset** with: what's done, what's next, files modified
10. **Write meaningful descriptions** - tasks without context are useless to future sessions

### MUST NOT DO

1. **Never invent task IDs** - only use IDs returned by trekker commands
2. **Never overwrite without confirmation** - always show current state before update
3. **Never mark complete without summary** - future sessions depend on this context
4. **Never skip dependency checks** - verify blockers are resolved first
5. **Never assume task exists** - verify with `trekker task show <id>` first
6. **Never delete without explicit user request** - prefer `archived` status

### When to Create Issues

**BEFORE CREATING - You MUST:**
1. Run `trekker search "<keywords>"` to check for existing/related issues
2. Check if an existing issue can be extended instead
3. If similar issue exists, add a comment or update it rather than creating a duplicate

**CREATE** when:
- Search confirms no existing issue covers this work
- Work spans multiple sessions
- Task has dependencies or subtasks
- User explicitly requests tracking
- Bug or feature needs documented investigation
- Work needs to be handed off to another session

**DO NOT CREATE** when:
- Search found an existing issue that covers this work (update it instead)
- Task is trivial (< 1 minute)
- User explicitly declines
- Just exploring or brainstorming
- One-off question or clarification

---

## Essential Workflow

### Session Start (Context Recovery) - MANDATORY

**Run ALL these commands at session start.** Do not proceed without understanding context:

```bash
# 1. SEARCH for what you're about to work on
trekker search "<topic/area of work>"

# 2. What's currently being worked on?
trekker --toon task list --status in_progress

# 3. What changed recently? (audit trail)
trekker history --limit 10

# 4. Find unblocked tasks ready to work on
trekker ready

# 5. Get context from comments on active tasks
trekker comment list <task-id>
```

**Why context recovery is mandatory:**
- You don't remember previous sessions - CLI commands restore that context
- Search reveals past decisions you would otherwise lose
- History shows WHO changed WHAT and WHEN
- Prevents duplicate work and conflicting changes
- **If context is unclear: STOP → SEARCH → RESUME**

### Before ANY New Work - Search First (MANDATORY)

**STOP. Before doing anything, search for related work:**

```bash
# Use single keywords - FTS5 is not semantic, multi-word = AND logic
trekker search "authentication"
trekker search "login"

# Check completed tasks for solutions
trekker --toon task list --status completed

# Check archived tasks too
trekker --toon task list --status archived
```

**Why search is mandatory:**
- Past tasks contain solutions and decisions you've forgotten
- Existing issues may already cover what you're about to create
- Find related code changes and file locations
- **Prefer continuity over re-implementation**
- **Prefer extending existing work over starting new threads**

### Working on Tasks

```bash
# Start a task
trekker task update <task-id> -s in_progress

# Document progress
trekker comment add <task-id> -a "claude" -c "Progress: ..."

# Complete with summary
trekker comment add <task-id> -a "claude" -c "Summary: ..."
trekker task update <task-id> -s completed

# ALWAYS show next ready tasks after completing
trekker ready
```

### Before Context Reset

```bash
trekker comment add <task-id> -a "claude" -c "Checkpoint: done X. Next: Y. Files: a.ts, b.ts"
```

### Completing Epics (Keep Board Clean)

When all tasks in an epic are done, use `epic complete` to archive everything at once:

```bash
# Complete epic and archive all its tasks/subtasks
trekker epic complete <epic-id>
```

**Why this matters:**
- Keeps kanban board focused on active work
- Archived tasks remain searchable but don't clutter views
- Single command vs manually archiving each task

**When to use:**
- All tasks under the epic are completed
- Feature/milestone is fully delivered
- User confirms epic is done

---

## Key Commands

| Command | Purpose |
|---------|-------