[Research] Query UX for tickets, queues, and workspace state

[StatPan]

Goal

Research whether Gira needs a dedicated query UX, and if so, what problem it should solve.

Context

The PyPI gira project advertises advanced query/search capabilities over local .gira project-management state. In Gira, the data model is different: GitHub remains the source of truth, while CLI commands compute lifecycle state from issues, branches, PRs, checks, labels, and workspace config.

A query feature may be useful, but only if it improves over existing list/status/queue commands without turning Gira into a generic database query tool.

Reference:

• https://pypi.org/project/gira/

Candidate Use Cases

• Find ready tickets across one repo or workspace.
• Find tickets missing acceptance criteria or readiness labels.
• Find in-review issues without a linked PR.
• Find PRs with failed checks or missing closing links.
• Find finish-ready tickets.
• Find stale open issues or stale PRs.
• Find agent-ready work by label, milestone, or owner.

Design Options

1. No dedicated query language; improve ticket list, workspace status, and queue filters.
2. Add simple filter flags only, such as --queue, --label, --milestone, --stale, --json.
3. Add named queries, such as gira query finish-ready.
4. Add an expression language later only if simple filters are insufficient.

Questions

• What should query do that ticket list and workspace status cannot?
• Should query be repo-local only or workspace-aware?
• Should query return raw records or named operational queues?
• Should query syntax be stable enough for automation?
• Should saved queries live in .gira/config.yaml?

Acceptance Criteria

• Define the first 5 real query use cases.
• Decide whether to implement query as named queues, filter flags, or a dedicated gira query command.
• Decide whether saved queries belong in .gira/config.yaml.
• Create follow-up implementation issues only if a clear UX emerges.