update-specs-status shortcut: bare and ./ sibling links do break on a move, and closed children are countable without reading bead files
- 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