backlog-management

# Backlog Management Shared, platform-agnostic conventions for backlog managers across Azure DevOps, GitHub, and Jira. This skill owns the structural core that every platform reuses: how planning files are named and laid out, how planned items are identified, how candidate work is compared to existing work, how autonomy gates mutations, how outbound text is sanitized, and how an interrupted workflow resumes. Each platform contributes only its small delta (the command surface, field vocabulary, reference-ID prefix, and action verbs) through a per-platform reference. ## When to Use Use this skill when running any backlog workflow for a supported platform: * Discovery — turn user requests, artifacts, or queries into candidate work items. * Triage — assess existing items, recommend field, label, priority, and status changes, and flag duplicates. * PRD-to-work-item planning — map a PRD into a validated work-item hierarchy for a separate execution pass. * Sprint and iteration planning — analyze a delivery window for coverage, capacity, dependencies, and gaps, and recommend grooming candidates. * Execution — process a reviewed handoff into sequential create, update, transition or move, and comment operations. Read the platform-agnostic conventions below, then load the reference that matches the active platform for its concrete command surface and vocabulary. ## How This Skill Is Organized * This file — the platform-agnostic core: platform resolution, planning-file lifecycle, directory conventions, planning-type enum, scope normalization, reference-ID scheme, similarity assessment, autonomy tiers, content sanitization, state persistence, and human review triggers. * [references/workflows.md](references/workflows.md) — the platform-agnostic workflow protocols (discovery, triage, execution), the platform binding resolution table, the operation contract, dry-run and error handling, and the shared planning-file templates. * [references/story-quality.md](references/story-quality.md) — work-item quality at epic, feature, user story, and task level: title and description conventions, acceptance criteria, definition of done, scope and sizing signals, evidence sourcing, completeness dimensions, and the authoring and refinement coaching loop. * [references/sprint-planning.md](references/sprint-planning.md) — the platform-agnostic sprint and iteration planning protocol: container binding, coverage and capacity analysis, gap and dependency detection, grooming recommendations, and the sprint-plan template. * [references/task-planning.md](references/task-planning.md) — assigned-work retrieval and enrichment: identity-scoped retrieval, repository-context gathering, discussion integration, and the implementation handoff record. * [references/ado.md](references/ado.md) — Azure DevOps platform delta: MCP ADO command surface, namespaced field vocabulary, the `WI` reference prefix, action verbs, PRD hierarchy (Epic → Feature → User Story), relationship semantics, and work-item tracking paths. * [references/ado-pull-request.md](references/ado-pull-request.md) — Azure DevOps pull request creation: work item discovery and linking, reviewer identification from git history, the seven-phase creation protocol, and its planning-file formats. * [references/ado-build-info.md](references/ado-build-info.md) — Azure DevOps build and pipeline information: pipeline tool surface, build location by PR, build ID, or branch, log extraction, and summarization rules. * [references/github.md](references/github.md) — GitHub platform delta: MCP GitHub command surface, supported operations, field vocabulary and field matrix, search syntax, issue body and type strategy, label taxonomy, milestone protocol, the `IS` reference prefix, action verbs, community-communication guardrails, PRD sub-issue hierarchy, and issue tracking paths. * [references/jira.md](references/jira.md) — Jira platform delta: command surface (delegated to the `jira` skill), field vocabulary, the `JI` reference prefix, action verbs, PRD hierarchy and field-mapping rules, triage and update decisions, and Jira tracking paths. ## Platform Resolution Every backlog workflow resolves its target platform before making any platform call. This section is the single authority for that resolution; an orchestrating agent or a user-invocable workflow command runs it as its first step rather than carrying its own copy. Resolution produces two outputs: the resolved platform, and a readiness verdict for that platform. ### Step 1: Determine the candidate platform Resolve the platform from the strongest available signal, in this order: 1. Explicit user mention of Azure DevOps, GitHub, or Jira. 2. Active tracking root in context: `.copilot-tracking/workitems/**` resolves to Azure DevOps, `.copilot-tracking/github-issues/**` to GitHub, `.copilot-tracking/jira-issues/**` to Jira. 3. Item-key shape: `PROJ-123` resolves to Jira, `#NNN` to GitHub, a bare numeric `System.Id` to Azure DevOps. 4. A configured or credentialed platform when only one passes a non-interactive readiness probe. This is capability evidence, not user intent; see Inferred-Platform Confirmation below. 5. Otherwise, ask which platform to target. When more than one platform remains plausible, summarize the two most likely options with a brief rationale and ask the user to choose. Do not guess a tracker and do not run the workflow against every candidate. A readiness probe is a non-interactive capability check that runs across all three platforms before signal 4 is used. It never prompts, never launches a setup workflow, and never mutates: | Platform | Non-interactive readiness probe | |--------------|--------------------------------------------------------------------------------------------------------| | Azure DevOps | MCP `ado/*` tools are available | | GitHub | MCP `github/*` tools are available | | Jira | `JIRA_BASE_URL` and either `JIRA_API_TOKEN` or `JIRA_PAT` are already set, and a terminal is available | ### Step 2: Run the full preflight for the resolved platform The full preflight runs once, after the platform is resolved. It may resolve identity and may run interactive credential setup, which is why it never runs as a probe. | Platform | Preflight check | |--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Azure DevOps | MCP `ado/*` tools available and an explicit `project` resolvable; call `ado/core_get_identity_ids` to establish authenticated user context before assignment. | | GitHub | MCP `github/*` tools available and identity resolvable via `github/get_me`; the target `owner/repo` is known. | | Jira | A terminal is available for the `jira` skill CLI. The CLI loads supported missing values from `~/.jira.env` in-process without shell evaluation. When its value-free validation reports missing variables, stop and route the user to the separate `jira` credential-setup workflow; do not source the file or run setup inline. | ### Inferred-Platform Confirmation Steps 1 through 3 resolve user intent. Step 4 does not: a single passing preflight proves only that one platform is reachable from this machine, not that the user meant it. When the platform was resolved by step 4 and the workflow performs any externally visible or mutating operation, state the inferred platform and its target scope (`project`, `owner/repo`, or project key), then obtain explicit user confirmation before the first mutating call. Read-only discovery, triage analysis, and planning may proceed on a step-4 inference without confirmation, because they produce no external change. This confirmation is independent of the autonomy mode. Full autonomy removes per-operation gates; it does not authorize acting on an unconfirmed destination. Record the confirmation in `planning-log.md` before the first mutation. ### Step 3: Report the readiness verdict When a platform's prerequisites are unmet, do not route work to it. Name the missing prerequisite and continue with the platforms that are available. A missing prerequisite is reported, never worked around: do not substitute a different platform for the one the user named, and do not proceed with a partial credential set. Record the resolved platform and its verdict in `planning-log.md` so a resumed workflow does not re-resolve from a changed environment. ## Planning File Lifecycle and Directory Conventions Every backlog workflow persists its state under a platform tracking root inside `.copilot-tracking/`. The active platform reference names its exact root (for example, Jira uses `.copilot-tracking/jira-issues/`). The structure below is constant across platforms; only the root segment and file vocabulary change. ```text .copilot-tracking/ <platform-tracking-root>/ <planning-type>/ <scope-name>/ <analysis-file>.md # evolving human-readable analysis (discovery and PRD paths) <plan-file>.md # source of truth for planned operations planning-log.md # progress and resumable state handoff.md # user-reviewable execution contract handoff-logs.md # live per-operation execution checkpoints and resume authority handoff-dryrun.md # simulated-run record; never read by a live run ``` `<analysis-file>` and `<plan-file>` are platform bindings, not fixed names. Resolve them through the active platform reference before creating or reading a planning file; see the Platform Binding Resolution table in [references/workflows.md](references/workflows.md). ### Planning-Type Enum `<planning-type>` is one of: * `discovery` — item discovery from artifacts, requirements, or search scopes. * `triage` — item triage, field cleanup, duplicate review, and workflow-state recommendations. * `execution` — item creation, update, transition or move, and comment processing from finalized plans. * `prds` — PRD-driven hierarchy planning that produces a handoff for a separate execution pass. * `current-work` — retrieval and enrichment of the authenticated user's assigned work into an implementation handoff, per [references/task-planning.md](references/task-planning.md). ### Scope-Name Normalization Normalize `<scope-name>` consistently: * Use lower-case, hyphenated form without a file extension. * Replace spaces and punctuation with hyphens. * Choose the primary artifact when multiple documents are provided. * For triage and execution scopes, use the date (`YYYY-MM-DD`) as the scope name unless a handoff already defines a clearer slug. ## Planning File Requirements Every planning markdown file starts with: ```markdown <!-- markdownlint-disable-file --> <!-- markdown-table-prettify-ignore-start --> ``` Every planning markdown file ends with: ```markdown <!-- markdown-table-prettify-ignore-end --> ``` ## Reference-ID Scheme Planned items carry a stable per-workflow reference ID that pairs a platform prefix with a zero-padded sequence, for example `JI001`, `JI002`. The active platform reference defines its prefix (`WI` for Azure DevOps, `IS` for GitHub, `JI` for Jira). Reference IDs are internal planning identifiers and never leave the workflow for the target platform; see Content Sanitization Guards. Items not yet created use a temporary key of the form `{{TEMP-N}}`, resolved to the real platform key after creation. ## Similarity Assessment Framework Every duplicate decision, merge recommendation, and Human Review Trigger depends on this framework, so assess it explicitly rather than by impression. ### Comparison Aspects Weigh all six aspects before assigning a category. No single aspect decides the outcome on its own. | Aspect | What to compare | Strength of signal | |------------------------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------| | Summary overlap | Title and one-line summary against the candidate's working summary | Strong when the same capability and object are named | | Item-type compatibility | Existing item type against the candidate's planned type | Strong; incompatible types rarely merge | | Status | Whether the existing item is open, in progress, closed, or resolved | Strong; a closed item rarely satisfies a new requirement | | Label and field overlap | Labels, tags, components, priority, and area or project placement | Moderate; corroborates but does not establish a match | | Acceptance-criteria coverage | Whether the existing body already covers the candidate's acceptance criteria | Strong; the primary evidence for Match | | Hierarchy fit | Whether both sit at the same level, or one is the natural parent of the other | Moderate; a level mismatch usually indicates Similar, not Match | ### Similarity Categories | Category | Meaning | Evidence required | |-----------|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | Match | Existing item already covers the requirement with minor or no edits | Summary overlap plus acceptance-criteria coverage, with a compatible type and status | | Similar | Existing item overlaps but requires user review to decide whether to merge or split | Partial overlap, a level mismatch, or coverage of some but not all criteria | | Distinct | Existing item does not cover the requirement | No meaningful summary or criteria overlap | | Uncertain | Available evidence is insufficient for a confident decision | The existing body is empty, truncated, or could not be hydrated | Uncertain is a real outcome, not a fallback for effort. Record it whenever the hydrated item lacks the body or criteria needed to judge coverage, and route it through the Human Review Triggers. ### Recording a Similarity Assessment Record every assessed pair in the analysis file so the decision is auditable and resumable: * The existing item key and its current status and type. * The assigned category and the aspects that drove it. * The action the category maps to in the active workflow. * For Similar and Uncertain, the specific question the user must answer. When one candidate returns more than one Similar existing item, present all of them together rather than picking the first; a single-candidate-to-many-existing fan-out is a Human Review Trigger. ## Three-Tier Autonomy Model This table is the only generic definition of the autonomy tiers. Agents, workflow commands, and platform references point at it rather than restating it; a second copy drifts. | Mode | Behavior |