jlevy / jlevy/tbd

Linear max_nesting skips deep epics silently: no warning at creation, no doctor check, and the sync never converges

Open
#272 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
TypeScript
Stars
79
Forks
9
Avg merge
1d 14h
Merged PRs (30d)
42

Description

## Summary

Epics deeper than `max_nesting` are skipped by the Linear bridge without any warning outside dry-run output. They never reach the tracker and keep the pending count above zero forever.

## What happened

Six epics sit three levels deep under a `max_nesting: 2` config. Every `tbd --dry-run integration sync` prints:

```
linear: would push 6, would pull 1, skipped 6, warnings 5
- p-aaaa: nested 3 levels, past max_nesting 2

```

- Nothing warned when they were created or re-parented to that depth.
- `tbd integration status` and `tbd doctor` report nothing.
- After a full push that updated 173 items, the dry run still says `would push 6`, so the sync can never report converged (compounds #265).

## Suggested change

- Warn at `tbd create --parent` / `tbd update --parent` when the result exceeds the configured depth for an enabled tracker.
- A doctor check listing beads currently past the depth.
- An option to push deep epics as top-level tracker issues with the parent named in the managed description region, instead of dropping them.
- Exclude "skipped" items from `would push` so convergence is readable.

Environment: tbd 0.8.1, Node v24.19.0, macOS 26 (Darwin 25.5), Linear integration enabled. Repository scale when observed: 7,156 beads, 137 open epics, 171 tracker links, about 110 plan specs in `active/`.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reproducing the behavior with `tbd --dry-run integration sync`, then inspect the `tbd create --parent`, `tbd update --parent`, `tbd integration status`, and `tbd doctor` entry points. Done should cover warnings for over-depth parents, a doctor result, an explicit deep-epic handling choice, and convergence output that no longer counts skipped items as pending pushes.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli, devtools
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.