Product Management: ticketing

[brillout]

There might be tremendous value in saving a copy of all the tickets (e.g. GitHub Issues) inside the Git repo.

.the-framework/tickets/1337-Some_Feature_Request.md
.the-framework/tickets/4200-Some_Other_Feature_Request.md

• We two-way-sync .the-framework/tickets/* with GitHub issues
  • Because humans prefer UIs (e.g. GitHub issues), while agents prefer text
  • Synced ticket body: cat 1337-Some_Feature_Request.md <=> body of https://github.com/org/repo/issues/1337
  • Title encoding: => _, _ => %5F, filesystem problematic chars => %xx
  • Discussions only happen on GitHub (no syncing)
  • Convention: ticket body includes the approved goal (the consensus)
• We can then ask AI things like:
  • "Read all tickets and suggest a PLAN.md" => once PLAN.md approved => materialize into TODO.md
  • "Read the discussion at #1337 and update the ticket body" => updates both Git ticket and GitHub issue (thanks to auto-sync)
• When a ticket is done => remove it (it's still available via git log -p)

Very tempting to work on it today (big dogfooding potential), but I'll evaluate the priority for this once we're done with the MVP and landing page.

@suleimansh You mentioned that you use GitHub issues as a seam between you and AI — feel free to elaborate. Let me know if you think this ticket doesn't add that much value in your experience.

AFAICT, the biggest added value is that AI can fully access all tickets without having to make any GitHub requests. Another massive added value is that the user can use AI to manage tickets ("create new umbrella ticket that lists all product managment ticktes", "correctly label all tickets", "create labels and suggest a PLAN.md"). Also, it's lossless and reviewable (thanks to Git).

Using Git to manage tickets isn't a new idea, but I think AI brings this idea to a whole new level.

Discussion and feedback welcome.

See also:

• Script one-way-syncing CHANGELOG.md => GitHub releases (permalink) — shows GitHub API usage, including some gotchas

[suleimansh]

Strong yes. One nuance: committed .the-framework/tickets/*.md is the source of truth, issues are the synced human mirror (not issue-first). Files canonical buys: offline/no API, versioned with the code (a ticket edit rides the same PR), works in CI + worktrees, provider-agnostic. Issues add the UI + discussion on top.

How I use issues as the seam: every unit of work is an issue first, body = the agreed goal, one issue = one PR = one changeset. It is the contract we both point at.

Same model as #485 (architecture profile + decisions committed in .the-framework/, GitHub as projection). Worth treating tickets + architecture as one pattern. Agree on priority: after MVP + landing page.

[brillout]

One-way sync would be easier than two-way sync. But the issue I see with only one-way sync is that, if a human creates a new GitHub ticket, then I think it should be also synced from GitHub issue (GH) to .the-framework/tickets/* (Git). If a human edits a GitHub issue, I also think it should sync from GH to Git. That's why I'm inclined to make it two-way sync.

But, anyways, it's post-MVP so we can think and discuss more about it post-MVP. I think it's a neat idea and the right start for the Agentic Product Management topic, so I wanted to share early.

[brillout]

About one-way VS two-way, we can go for whatever is easiest for now.

We can also go for an even easier path (for now):

• Just pull all GitHub issues and write .the-framework/tickets/*.md (import)
• No syncing at all (only import once, then The Framework only writes .the-framework/tickets/*.md without touching GitHub issues)