agent-issue-tracker-workflow

name	agent-issue-tracker-workflow
description	Discipline an AI agent needs to work an issue/task tracker (Jira, Linear, GitHub Issues) as the shared source of truth: pull the right next item instead of inventing work, search before creating to avoid duplicates, write actionable items with checkable acceptance criteria, keep status transitions honest, and link work to items via branches/PRs/commits so progress is legible. Use when an agent picks up tracker work, files a new issue, updates status, or closes an item. NOT for authoring the PR itself (use agent-pr-authoring), roadmap-level planning and prioritization (use legible-roadmap-with-sidequests), or the mechanics of multiple agents coordinating on the same codebase (use multi-agent-coordination).
license	Apache-2.0
allowed-tools	Read,Write,Edit,Bash,Grep,Glob
metadata	{"category":"Agent & Orchestration","tags":["issue-tracker","tracker-discipline","status-legibility","dedupe-search","work-item-linking"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"agent-work-receipt-designer","reason":"A receipt is the evidence a tracker item's \"done\" transition should point at."},{"skill":"port-daddy-agent-skill","reason":"Supplies the claims/notes/salvage substrate that keeps a tracker item's status honest across sessions."},{"skill":"next-move","reason":"Decides what to work next; this skill governs the discipline once an item is picked up."}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]"],"produces":["[Truncated]"]}}

Agent Issue Tracker Workflow

Work a tracker (Jira/Linear/GitHub Issues) the way a trusted human collaborator would: as a shared queue and a legible record, never a private notepad.

Use This For

• Deciding whether to pull an existing tracker item, refine one, or file a new one — and proving a search happened first.
• Writing or refining an item so it is actionable: explicit scope, reproduction/context, and acceptance criteria a reviewer can check.
• Moving an item through todo -> in-progress -> done honestly, backed by observable work rather than optimism.
• Linking a change to its item — branch names, Roadmap-Item:/issue-key PR trailers, commit references — so the item traces to its diff.
• Capturing newly-discovered work as new tracker items instead of quietly expanding the current item's scope.

Do Not Use This For

• Writing the PR body/diff itself once the item is scoped (agent-pr-authoring).
• Deciding roadmap priority, sequencing, or which epic an item belongs to (legible-roadmap-with-sidequests).
• Multi-agent file-locking, worktree isolation, or message-passing mechanics (multi-agent-coordination).

Process

flowchart TD
  A[Read tracker as authoritative queue] --> B[Search before creating]
  B --> C{Existing item found?}
  C -->|Yes| D[Pull it: check deps + acceptance criteria]
  C -->|No| E[File new item: scope + repro + acceptance criteria]
  D --> F[Do the work]
  E --> F
  F --> G[Link branch/PR/commit to the item]
  G --> H[Transition status only on observed evidence]
  H --> I{New work discovered?}
  I -->|Yes| J[File as new item, do not scope-creep]
  I -->|No| K[Close with evidence]
  J --> K

1. Read the tracker as the authoritative work queue: pull the next item by priority and unmet dependencies, don't invent work the tracker doesn't know about. GitHub Copilot's cloud agent and port-daddy's own roadmap (ADR-0086 migration toward Jira-style items with slugs) both assume the tracker, not the chat, is ground truth.
2. Before filing anything, search for an existing item covering the same work. Never keyword-grep titles as a substitute — read the top candidates and confirm by hand; a missed near-duplicate is worse than a slow search.
3. If filing new, write it so a stranger could pick it up: explicit scope, reproduction/context, and acceptance criteria stated as checkable conditions ("cargo test -p core bin_resolver:: exits 0"), not vibes ("make it work better").
4. Do the work, then link it to the item — a branch name, a PR trailer (this repo's convention: Roadmap-Item: <slug>), or a commit reference — before or as part of the same change, never as an afterthought days later.