1693 Pebble Guide 80d50f5d

# Pebble Guide

Git-backed issue tracker for AI agents. Track all work as Pebble issues.

## Quick Reference

```bash
# What to work on
pb ready                    # Unblocked issues (start here)
pb ready -v                 # With full details
pb blocked -v               # What's blocked and WHY

# Epic overview
pb summary                  # Open epics with completion counts
pb dep tree <epic>          # Full hierarchy (epic → tasks → verifications)
pb list --parent <epic>     # All children of an epic

# Issue details
pb show <id>                # Full issue details
pb verifications <id>       # Verifications targeting this issue

# Create with dependencies (self-documenting)
pb create "Task B" -t task --blocked-by $TASK_A    # B needs A
pb create "Task A" -t task --blocks $TASK_B        # A blocks B

# Basic workflow
pb create "Title" -t task -p 1 --parent $EPIC | jq -r .id
pb claim <id>               # Set in_progress
pb comments add <id> "What was done, file:line"
pb close <id> --reason "Done"

# Dependencies
pb dep add <blocked> <blocker>  # B blocked BY A: pb dep add B A
pb dep tree <id>                # View hierarchy
```

**Types:** `task`, `bug`, `epic`, `verification` | **Priority:** 0 (critical) to 4 (backlog) | **Status:** `open`, `in_progress`, `blocked`, `pending_verification`, `closed`

---

## Core Rules

### 1. One Task at a Time
Only ONE issue `in_progress`. Transition current issue (block/close) before claiming another.

### 2. Comment Before Closing
Every close needs a comment with file paths, line numbers, and what was done. No comment = work isn't verified.

```bash
pb comments add <id> "Implemented X in src/foo.ts:45-78. Tests in foo.test.ts."
pb close <id> --reason "Done"
```

### 3. Every Code Change Gets an Issue
Found and fixed a bug? Create issue → fix → comment → close. Issues are audit records. No issue = invisible fix.

### 4. Dependencies: Blocked BY
`pb dep add B A` means "B is blocked by A" (A must close before B is ready).

**Think:** "B needs A" → `pb dep add B A`

**Self-documenting alternative:** Use `--blocked-by` or `--blocks` when creating:
```bash
pb create "Task B" --blocked-by $TASK_A   # B needs A (clearer)
pb create "Task A" --blocks $TASK_B       # A blocks B (clearer)
```

### 5. Parent ≠ Sequence
`--parent` creates hierarchy only. Children run in parallel unless you add explicit `pb dep add` between them.

### 6. No Orphans
Every issue connects to the work graph (parent epic or dependencies).

### 7. Comprehensive Descriptions
Write like a PM: Purpose, Why It Matters, Requirements, Acceptance Criteria. Future agents need full context.

### 8. Approved Plan Decomposition (Required)
If implementation is based on an approved plan with explicit phases/steps, create Pebble child tasks for each phase/step before or at implementation start (and immediately after resume if missing).

- Parent each step task under the epic (or current phase task for subplans)
- Add dependencies to match required sequence from the plan
- Keep exactly one task `in_progress`, but preserve full step-level traceability in Pebble
- Do not collapse multi-phase execution into a single long-running task

---

## Verification Issues

Verification issues are post-completion checks — they become ready AFTER their target is closed.

```bash
# Create verification that targets a task
pb create "User can log in" --verifies $TASK_ID

# List verifications for an issue
pb verifications $TASK_ID

# Ready verifications (target closed, verification open)
pb ready --type verification
```

### Ready Behavior

| Target Status | Verification Status | In `pb ready`? |
|---------------|---------------------|----------------|
| open | open | No |
| closed | open | **Yes** |
| closed | closed | No |

### Creating Verifications from Plans

When plans have **Verification** sections, each verification step can become a verification issue:

```bash
TASK=$(pb create "Implement login" -t task --parent $PHASE | jq -r .id)

# Each feature = verification issue targeting the task
pb create "User can log in with valid credentials" --verifies $TASK \
  --description "Navigate to /login, enter valid creds, verify redirect to dashboard"
pb create "Invalid password shows error" --verifies $TASK \
  --description "Navigate to /login, enter wrong password, verify error message"
```

### Performing Verification

When a verification appears in `pb ready`, its target is done. **Verify immediately** while context is fresh and environment is set up.

**Steps:**
1. Follow the steps in the description
2. Capture evidence (screenshots, responses, output)
3. Comment with proof
4. Close if passing, or create bug if failing

**Evidence varies by type:**
- **UI**: Screenshot or description of what you observed
- **API**: Request sent, response received (status, body)
- **CLI**: Command run, output produced
- **Data**: Query executed, results returned

```bash
# Good: evidence included
pb comments add $ID "POST /login with valid creds → 200, session cookie set, redirected to /dashboard"
pb close $ID --reason "Verified"

# Bad: no evidence
pb comments add $ID "Works"
```

**If verification fails:** Don't close. Create a bug issue, link it, fix, then re-verify.

**If you can't verify right now** (no browser session, backend not running, need user action):
```bash
# Comment what's blocking, leave open
pb comments add $ID "Cannot verify: backend not running. Need to start server first."
```
Don't close without verification. Don't delete the issue. The record shows verification was attempted and blocked.

### Pending Verification Status

When you close an issue that has open verification issues targeting it, it goes to `pending_verification` instead of `closed`. This enforces that verification actually happens.

```bash
pb close $TASK_ID --reason "Implementation done"
# Output: Issue set to pending_verification. Pending: BEAD-abc123, BEAD-def456

# Complete the verification issues first
pb close BEAD-abc123 --reason "Verified"
pb close BEAD-def456 --reason "Verified"

# Now the task auto-closes, or close it again
pb close $TASK_ID --reason "All verifications passed"
```

---

## Epic Management

### Overview with `pb summary`

See all open epics with completion progress:

```bash
pb summary --pretty

## Open Epics (2)

BEAD-abc123: Implement authentication
  Created: 2 days ago | Updated: 1 hour ago
  Issues: 2/5 done | Verifications: 1/3 done

  Build user auth with login, logout, session management.
```

Include recently closed epics (last 72h):
```bash
pb summary --include-closed --pretty
```

### Full Hierarchy with `pb dep tree`

See complete epic structure including nested children:

```bash
pb dep tree $EPIC --pretty

✓ BEAD-abc123: Implement authentication [epic] P1 ◀
├─ ✓ BEAD-def456: User registration [task] P2
│  ├─ ✓ BEAD-v001: Can register with email [verification]
│  └─ ✓ BEAD-v002: Invalid email shows error [verification]
├─ ○ BEAD-ghi789: Login flow [task] P2
│  ├─ ○ BEAD-v003: Can login [verification]
│  └─ ○ BEAD-v004: Wrong password shows error [verification]
└─ ○ BEAD-jkl012: Session management [task] P2
```

The `◀` marker indicates the requested issue. `✓` = closed, `○` = open.

### List Children with `pb list --parent`

Flat list of all direct children:
```bash
pb list --parent $EPIC --pretty
```

---

## Related Links

Use `pb dep relate` for issues that share context but don't block each other. Unlike `blocks`, related links are bidirectional and don't affect `pb ready`.

```bash
# Link related issues (bidirectional, non-blocking)
pb dep relate $ISSUE1 $ISSUE2

# Remove the link
pb dep unrelate $ISSUE1 $ISSUE2

# View all dependencies including related
pb dep list $ISSUE1
```

**Use cases:**
- Issues that touch the same code but can run in parallel
- Cross-references for context without ordering requirements
- Grouping conceptually linked issues

---

## Finding Issues

### Search
```bash
pb search "auth bug" --pretty          # Search titles and descriptions
pb search "login" --type bug --pretty  # Filter by type
pb search "refactor" --status open     # Filter by status
```

### See Why Something Is Blocked
```bash
pb blocked -v --pretty

## Blocked Issues (2)

BEAD-ghi789: Session management
  Type: Task | Priority: P2 | Created: 12 hours ago
  Epic: BEAD-abc123 (Implement authentication)
  Blocked by: BEAD-def456
```

The `-v` (verbose) flag shows which issues are causing the block.

---

## Common Workflows

### Create Epic with Phases and Tasks (Nested)

For larger work, create a hierarchy: Epic → Phases → Tasks → Subtasks

```bash
# Create epic
EPIC=$(pb create "Feature X" -t epic | jq -r .id)

# Create phases under epic
P1=$(pb create "Phase 1: Design" -t task --parent $EPIC | jq -r .id)
P2=$(pb create "Phase 2: Implementation" -t task --parent $EPIC | jq -r .id)
P3=$(pb create "Phase 3: Testing" -t task --parent $EPIC | jq -r .id)

# Sequence phases
pb dep add $P2 $P1    # Phase 2 needs Phase 1
pb dep add $P3 $P2    # Phase 3 needs Phase 2

# Create tasks under Phase 1
T1A=$(pb create "Design data model" -t task --parent $P1 | jq -r .id)
T1B=$(pb create "Design API contracts" -t task --parent $P1 | jq -r .id)

# Create tasks under Phase 2 (can have subtasks too)
T2A=$(pb create "Implement backend" -t task --parent $P2 | jq -r .id)
T2B=$(pb create "Implement frontend" -t task --parent $P2 --blocked-by $T2A | jq -r .id)

# Create verification issues targeting tasks
pb create "API returns correct schema" --verifies $T2A
pb create "UI displays data correctly" --verifies $T2B
```

Result:
```
Epic: Feature X
├── Phase 1: Design
│   ├── Design data model
│   └── Design API contracts
├── Phase 2: Implementation (blocked by Phase 1)
│   ├── Implement backend
│   └── Implement frontend (blocked by backend)
└── Phase 3: Testing (blocked by Phase 2)
```

### Create Simple Epic (Flat)

For smaller work, flat structure is fine:

```bash
EPIC=$(pb create "Feature X" -t epic | jq -r .id)
T1=$(pb create "Design" -t task --parent $EPIC | jq -r .id)
T2=$(pb create "Implement" -t task --parent $EPIC --blocked-by $T1 | jq -r .id)
T3=$(pb create "Test" -t task --parent $EPIC --blocked-by $T2 | jq -r .id)
```

### Discovered Blocker

```bash
NEW=$(pb create "Found: auth needs refactor" -t bug -p 1 | jq -r .id)
pb dep add $CURRENT $NEW    # Current blocked by new
pb update $CURRENT --status blocked
pb claim $NEW               # Work on blocker
```

### Work Loop

```bash
pb ready                    # What's unblocked
pb claim <id>               # Start work
# ... implement ...
pb comments add <id> "Done: file:line, tests added"
pb close <id> --reason "Implemented"
```

---

## Pitfalls

| Don't | Do |
|-------|-----|
| Multiple `in_progress` | One at a time, transition before switching |
| Close without comment | Comment with file:line first |
| Fix without issue | Create issue → fix → comment → close |
| `pb dep add A B` for "A before B" | `pb dep add B A` — B blocked BY A |
| Assume `--parent` sequences | Add explicit deps for order |
| Terse descriptions | PM-style: purpose, requirements, acceptance criteria |