Best Practices

Proven patterns and best practices for AI agents using Tracer effectively

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:

blocks

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)

parent-child

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)

discovered-from

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)

related

Use when: Issues are connected but don’t block each other

# bd-5 and bd-1 are related but independent
tracer dep add bd-5 bd-1 --type related

Example: Login UI (bd-5) and login API (bd-1) are related but can be developed independently

4. Update Status Regularly

Keep the tracker in sync with reality:

Starting Work

# 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.

7. Link Discovered Work Back to Parents

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:

Priority	Meaning	When to Use
0	Critical	Blocking bugs, security issues, system down
1	High	Important features, significant bugs
2	Normal	Regular tasks and features (default)
3	Low	Nice-to-haves, minor improvements
4	Backlog	Ideas for later consideration

Critical Bug

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

No Ready Work Found

# 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>

Database Not Found

# Ensure tracer is initialized
tracer init

# Or specify database path
tracer --db .trace/myapp.db ready

Git Conflicts

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