Roadmap Ordering

issy maintains a roadmap — a strict, intentional ordering of all open issues. The roadmap reflects logical dependencies, so no issue should be blocked by one that follows it.

How it works

Every open issue has a position in the roadmap determined by its order field. This field uses fractional indexing — a technique that allows inserting items between any two existing items without reindexing.

When you run issy list, issues appear in roadmap order by default. issy next always returns the first issue — the next thing to work on.

Position flags

When creating or reopening an issue while other open issues exist, you must specify where it fits in the roadmap:

Flag	Description
`--before <id>`	Insert before a specific issue
`--after <id>`	Insert after a specific issue
`--first`	Insert at the beginning
`--last`	Insert at the end

Creating issues

issy create --title "Add auth" --after 0001       # After issue #0001
issy create --title "Fix bug" --before 0003        # Before issue #0003
issy create --title "Urgent" --first               # At the top
issy create --title "Backlog item" --last           # At the bottom

Repositioning issues

Use position flags with update to move an existing issue:

issy update 0001 --first                           # Move to top
issy update 0001 --after 0003                      # Move after #0003
issy update 0001 --last                            # Move to bottom

Reopening issues

When reopening a closed issue, you must also specify a position:

issy reopen 0001 --last
issy reopen 0001 --after 0004

Choosing placement

Think about logical dependency when choosing position:

If issue B requires work from issue A, A must come before B
Place foundational/infrastructure work early
Place user-facing features later
Use --first for urgent work that should be tackled immediately
Use --last when in doubt — it appends to the end

Sorting alternatives

While roadmap order is the default, issy list supports other sort modes:

issy list --sort roadmap     # Default — roadmap order
issy list --sort priority    # By priority level
issy list --sort created     # By creation date
issy list --sort updated     # By last update
issy list --sort id          # By issue ID

Technical details

The order field in issue frontmatter is a string key generated by the fractional-indexing library. Keys sort lexicographically, allowing new items to be inserted between any two existing items without modifying them.

You should not edit the order field manually. Use the position flags instead.