---
name: tx-workflow
description: Guide for working with tx task management. Use when picking up tasks, completing work, or managing dependencies.
---

# tx Workflow

## Picking Up a Task

1. Run `tx ready --limit 1 --json` to get the next unblocked task
2. Run `tx show <id>` to see full details, dependencies, and context
3. Run `tx memory context <id>` to get relevant learnings for the task

## Working on a Task

1. Understand the task requirements from `tx show`
2. Check for relevant learnings with `tx memory context <id>` or `tx memory recall <file-path>`
3. If related tasks share context, set it once with `tx group-context set <id> "<shared context>"`
4. If PRD docs are in scope, prefer `ears_requirements` and validate with `tx doc lint-ears <doc-name-or-yaml-path>`
5. Implement the changes
6. Add or update integration tests for critical flows (happy path + failure path)
7. If telemetry code changed, verify OTEL remains non-blocking (noop/configured/exporter-failure paths)
8. Record anything you learned: `tx memory add "what you discovered"`

## Completing a Task

1. Run targeted tests for changed files before completion (`bunx --bun vitest run <paths>`)
2. Run `tx done <id>` to mark the task complete
3. This automatically unblocks any tasks that depended on this one
4. Check `tx ready` to see if new tasks became available

## Creating Sub-tasks

If a task is too large, break it down:

```bash
tx add "Sub-task title" --parent <parent-id> --description "Details"
```

## Managing Dependencies

```bash
# Task B can't start until Task A is done
tx dep block <task-B-id> <task-A-id>

# Remove a dependency
tx dep unblock <task-B-id> <task-A-id>
```

## Recording Learnings

```bash
# General learning
tx memory add "Effect.try catch handler puts errors in the error channel, not success"

# File-specific learning
tx memory learn "src/auth/*.ts" "Auth tokens expire after 24h, refresh logic is in token-service.ts"

# Recall learnings for a file
tx memory recall src/auth/token-service.ts
```