Skip to main content

​
Core Principles

Follow these best practices to get the most value from Tracer in your agent workflows.

​
1. Always Check Ready Work First

Before starting any new work, check what’s unblocked: 
# At the start of every session
WORK=$(tracer ready --limit 1 --json)
if [ "$(echo $WORK | jq length)" -gt 0 ]; then
  ISSUE_ID=$(echo $WORK | jq -r '.[0].id')
  echo "Working on: $ISSUE_ID"
fi
Why? Starting with tracer ready ensures you work on tasks that are actually unblocked. This prevents wasted effort on tasks that can’t be completed yet.

​
2. File Issues as You Discover Them

Don’t let discovered work get lost: 
# Discovered a bug while working on bd-5
NEW_ID=$(tracer create "Fix null pointer in parser" -t bug -p 0 --json | jq -r '.id')
tracer dep add $NEW_ID bd-5 --type discovered-from
File issues liberally - it’s better to have too many tracked issues than to lose important work. You can always close or consolidate them later.

​
When to File Issues

1

Found a Bug

File immediately as a bug with priority based on severity
2

Identified Improvement

File as a task or feature for later consideration
3

Need to Refactor

File as a task and link it to the current work
4

Missing Tests

File as a task and link with discovered-from

​
3. Use Appropriate Dependency Types

Choose the right dependency type for the relationship:
Use when: One issue cannot start until another is done
# bd-2 cannot start until bd-1 is complete
tracer dep add bd-2 bd-1 --type blocks
Example: Login endpoint (bd-2) blocked by auth schema design (bd-1)
Use when: Creating epic structures with subtasks
# bd-3 is a subtask of epic bd-1
tracer dep add bd-3 bd-1 --type parent-child
Example: “Implement login” (bd-3) is a subtask of “User authentication system” epic (bd-1)
Use when: You found this issue while working on another
# bd-4 was discovered while working on bd-2
tracer dep add bd-4 bd-2 --type discovered-from
Example: Found a validation bug (bd-4) while implementing the login form (bd-2)

​
4. Update Status Regularly

Keep the tracker in sync with reality: 
# Claim the work by updating status
tracer update bd-1 --status in_progress
Regular status updates help other agents (and humans) understand what’s actively being worked on and what’s available.

​
5. Create Epics for Large Features

Break down complex work into manageable pieces: 
# Create epic
EPIC=$(tracer create "User authentication system" -t epic -p 0 --json | jq -r '.id')

# Create child tasks
T1=$(tracer create "Design auth schema" -t task -p 1 --json | jq -r '.id')
tracer dep add $T1 $EPIC --type parent-child

T2=$(tracer create "Implement login endpoint" -t task -p 1 --json | jq -r '.id')
tracer dep add $T2 $EPIC --type parent-child
tracer dep add $T2 $T1 --type blocks  # T2 blocked by T1

T3=$(tracer create "Add session management" -t task -p 1 --json | jq -r '.id')
tracer dep add $T3 $EPIC --type parent-child
tracer dep add $T3 $T1 --type blocks  # T3 blocked by T1

​
Epic Structure Pattern

1

Create Epic

Create the top-level epic with issue_type=epic
2

Identify Subtasks

Break down the epic into concrete tasks
3

Link Subtasks

Use parent-child to link subtasks to the epic
4

Model Dependencies

Use blocks between subtasks that have ordering requirements
Epic naming: Use clear, descriptive names for epics that describe the complete feature or initiative (e.g., “User authentication system”, “Payment processing integration”)

​
6. Use JSON Output for Parsing

Always use --json when parsing Tracer output: 
# Good: Reliable JSON parsing
ISSUE_ID=$(tracer ready --json | jq -r '.[0].id')

# Bad: Parsing text output is fragile
ISSUE_ID=$(tracer ready | grep -oP 'bd-\d+')
JSON output is stable and machine-readable. Text output is designed for humans and may change.
Always link discovered issues back to their source: 
# Discovered during bd-5
NEW_ID=$(tracer create "Add input validation" -t task --json | jq -r '.id')
tracer dep add $NEW_ID bd-5 --type discovered-from
Benefits:
  • Maintains context of where work came from
  • Helps with understanding scope changes
  • Provides audit trail for project evolution

​
8. Check Stats Periodically

Monitor project health with regular stats checks: 
# Check overall progress
tracer stats

# Or parse specific stats
READY=$(tracer stats --json | jq -r '.ready_issues')
echo "$READY tasks ready to work on"
Check tracer stats at the end of major milestones to see the big picture and track progress.

​
9. Use Priorities Consistently

Apply a consistent priority scheme:
PriorityMeaningWhen to Use
0CriticalBlocking bugs, security issues, system down
1HighImportant features, significant bugs
2NormalRegular tasks and features (default)
3LowNice-to-haves, minor improvements
4BacklogIdeas for later consideration
tracer create "System crash on login" -t bug -p 0

​
10. Provide Meaningful Completion Messages

Always include clear reasons when closing issues: 
# Good: Specific and informative
tracer close bd-1 --reason "Implemented login endpoint with OAuth2 support and tests"

# Bad: Too vague
tracer close bd-1 --reason "Done"

​
Configuration Best Practices

​
Set Actor Name

Identify yourself for audit trails: 
# Set in environment (recommended)
export TRACE_ACTOR="agent-claude"

# Or use flag for one-off commands
tracer --actor "agent-claude" create "Task"

​
Use Consistent Database Location

# Set database location
export TRACE_DB="/path/to/project/.trace/issues.db"

# Or initialize in project root
cd /path/to/project
tracer init

​
Anti-Patterns to Avoid

Don’t do these:
  1. Starting work without checking ready - You might work on blocked tasks
  2. Skipping status updates - Others won’t know what you’re working on
  3. Not linking discovered work - Context is lost
  4. Creating too few issues - Work gets lost in implementation
  5. Using wrong dependency types - Breaks the ready work algorithm
  6. Vague completion messages - Audit trail is less useful
  7. Parsing text output - Fragile and error-prone

​
Tips for Claude and Other AI Agents

1

Start with tracer ready

Orient yourself at the beginning of every session
2

File liberally

Better to have too many tracked issues than lose work
3

Use JSON

Always parse with tracer ready --json | jq
4

Update status

Keep humans informed of your progress
5

Link discovered work

Always use discovered-from for found issues
6

Check stats periodically

See the big picture with tracer stats

​
Troubleshooting

# Check what's blocked
tracer blocked

# View dependency tree to find blockers
tracer dep tree <issue-id>

# Remove incorrect dependencies if needed
tracer dep remove <from-id> <to-id>

# Ensure tracer is initialized
tracer init

# Or specify database path
tracer --db .trace/myapp.db ready
If .trace/issues.jsonl has conflicts after git pull:
  1. Resolve the conflict (keep both changes usually)
  2. Import: tracer import -i .trace/issues.jsonl

​
Next Steps

Agent Overview

Learn why agents should use Tracer

Agent Workflow

Master the complete workflow

JSON Output

Understand all JSON formats

CLI Reference

Complete command reference

Build docs developers (and LLMs) love

Get started for freeTalk to us