Tour: ask the backlog with the issue dependency graph

Issues depend on other issues - that structure is real, but it usually lives in someone’s head. madtea lets you write it down and then sorts the backlog by what unblocks the most.

Full reference: issues.md.

Wire the dependency graph

madtea issue deps add "103 -> 102 -> 101" --epic 100   # a chain + its tracking epic, one validated call

madtea issue deps add checks every edge before writing anything: does each issue exist, does any edge self-reference, does any edge create a cycle? A bad edge at position 50 means nothing is applied - the graph is never left half-wired.

Rank the backlog

madtea issue rank acme             # every repo in the org: keystones / free leaves / blocked
madtea issue rank acme/api         # a single repo

madtea issue rank sorts every open issue into three buckets, each tagged [blocked-by:N unblocks:M]:

• Keystones - ready now, unblocks the most downstream work. Do these first.
• Free leaves - ready now, no downstream dependencies. Safe to parallelize.
• Blocked - sorted nearest-ready first, so you can see what clears next.

One query, one repo or the whole org. No manual dependency picture to rebuild.

Track epics

madtea issue epic status 100       # roll up children: done / open / blocked
madtea issue epic tick 100         # sync the epic's checklist to child state

status rolls up the epic’s child issues into a state summary. tick fixes only the checkboxes in the epic body that drifted from child state - your hand edits are left alone.

madtea finish closes a branch-named issue only when nothing still blocks it. A tracking epic gets a reference instead of a close. If the dependency check itself errors, finish refuses to close - never the other way around.

File a whole roadmap at once

madtea issue import roadmap.json   # milestones + dependency-ordered issues from one JSON spec

madtea issue import validates the whole spec first, then files milestones and issues with dependencies already wired. If it crashes mid-run, re-running resumes from where it stopped without duplicating anything already filed.

Typical session

# 1. File the roadmap
madtea issue import roadmap.json

# 2. See what to work on now
madtea issue rank acme

# 3. Take a keystone, wire its branch
madtea issue develop 101           # cuts issue-101-<slug> branch

# 4. Implement, finish
madtea finish "feat: thing" --closes 101

# 5. Check how the epic moved
madtea issue epic status 100
madtea issue epic tick 100

Part of the guides - madtea documentation.