jlevy / jlevy/tbd

update-specs-status shortcut: bare and ./ sibling links do break on a move, and closed children are countable without reading bead files

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

Description

## Summary

Two instructions in the shipped `update-specs-status` shortcut are wrong in practice.

## 1. "Bare filenames … which a move does not break"

The shortcut says to rewrite inbound references on the `specs//` fragment because that "catches every path-bearing form at once while leaving bare filenames alone, which a move does not break."

Bare and `./` sibling links break whenever the target changes lifecycle folder. Moving 17 specs in one pass required 69 fragment rewrites *and* 33 bare or `./` sibling-link rewrites across 48 files; the second set is the one the sentence says does not exist. Several of the bare links were also already dangling from earlier moves that followed the instruction as written.

## 2. "Read the committed bead files directly"

To count closed children per spec, the shortcut says: "read the committed bead files directly and tally `spec_path` against `status`; they live under the data-sync worktree." That contradicts the skill's own "you operate tbd" rule, and `tbd list --all --parent --count` and `tbd list --all --spec --count` already answer the question without touching storage (see the companion issue on an epic child-count view).

## Suggested change

- Replace the bare-filename sentence with: rewrite the fragment form *and* every bare or `./` sibling link to a moved file, and verify with a relative-link check over the changed files.
- Replace the read-bead-files step with the `tbd list --all …` forms.

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 locating the shipped update-specs-status shortcut and read the two instructions described in the issue. Update the link-rewrite guidance and replace direct bead-file reading with the stated tbd list --all --parent --count and tbd list --all --spec --count forms. Done means the shortcut covers bare and ./ sibling links, uses tbd commands for closed-child counts, and calls for a relative-link check over changed files.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js
Domain
cli, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.