microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
.github/instructions/github/github-backlog-update.instructions.md
219lines · modecode
| 1 | --- |
| 2 | description: 'Execution workflow for GitHub issue backlog management - consumes planning handoffs and executes issue operations' |
| 3 | applyTo: '**/.copilot-tracking/github-issues/**/handoff-logs.md' |
| 4 | --- |
| 5 | |
| 6 | # GitHub Backlog Update Instructions |
| 7 | |
| 8 | Follow all instructions from #file:./github-backlog-planning.instructions.md for planning file templates, field definitions, search protocols, and state persistence. |
| 9 | |
| 10 | Follow community interaction guidelines from #file:./community-interaction.instructions.md when posting comments visible to external contributors. |
| 11 | |
| 12 | ## Purpose and Scope |
| 13 | |
| 14 | The execution protocol processes a handoff plan file to create, update, link, and close GitHub issues in batch. The workflow consumes handoff.md (or triage-plan.md) produced by the discovery or triage workflows and executes planned operations against the GitHub API via MCP tools. |
| 15 | |
| 16 | All operations MUST execute sequentially. Parallel execution is not supported due to dependency chains between Create, Link, and Update operations. |
| 17 | |
| 18 | ### Outputs |
| 19 | |
| 20 | * handoff-logs.md created next to `handoff` containing per-operation processing status and results |
| 21 | * Issues created, updated, linked, or closed in the target GitHub repository |
| 22 | |
| 23 | ### Trigger Conditions |
| 24 | |
| 25 | These instructions apply when processing issue operations from a handoff.md or triage-plan.md file through MCP GitHub tool calls. |
| 26 | |
| 27 | ## Issue Hierarchy |
| 28 | |
| 29 | Issues follow a parent-child hierarchy via sub-issue relationships: |
| 30 | |
| 31 | 1. Epic or tracking issue (top level) |
| 32 | 2. Individual issues (children of tracking issue) |
| 33 | 3. Sub-tasks (children of individual issues) |
| 34 | |
| 35 | Parent issues MUST be created before children to ensure sub-issue linking resolves correctly. |
| 36 | |
| 37 | ## Required Steps |
| 38 | |
| 39 | ### Step 1: Initialize or Resume |
| 40 | |
| 41 | When handoff-logs.md exists next to `handoff`: |
| 42 | |
| 43 | * Read handoff-logs.md and `handoff`. |
| 44 | * Identify operations with unchecked `[ ]` status. |
| 45 | * Rebuild the temporary ID mapping from previously completed Create entries (the Issue Number field in each completed log entry records the `{{TEMP-N}}` to `#actual` mapping). |
| 46 | * Resume processing in priority order: Create → Update → Link → Close → Comment, starting from the first unchecked operation in that sequence. |
| 47 | |
| 48 | When handoff-logs.md does not exist: |
| 49 | |
| 50 | * Create handoff-logs.md using the template from #file:./github-backlog-planning.instructions.md. |
| 51 | * Populate the Operations section from `handoff`. |
| 52 | * Record all inputs in the Execution Summary section. |
| 53 | |
| 54 | Validate the handoff before processing: |
| 55 | |
| 56 | * Confirm `owner` and `repo` are set (from inputs or parsed from the handoff file header). |
| 57 | * Verify all numeric issue references exist by calling `mcp_github_issue_read` with method `get` for each number. Skip `{{TEMP-N}}` placeholders during this validation since those issues do not exist yet. |
| 58 | * Verify label names are valid by calling `mcp_github_get_label` for each unique label in the plan. |
| 59 | * Call `mcp_github_list_issue_types` to confirm whether the organization supports issue types before using the `type` field. |
| 60 | * Map `{{TEMP-N}}` placeholders to execution order so parent issues are created before children that reference them. |
| 61 | * Apply the Content Sanitization Guards from #file:./github-backlog-planning.instructions.md to all GitHub-bound fields (issue titles, bodies, comments, and other text fields) to resolve `.copilot-tracking/` paths and planning reference IDs (`IS[NNN]`) before execution. |
| 62 | * When validation fails for a non-critical field (invalid label, unknown milestone), log a warning and continue. When validation fails for a critical field (missing repository, authentication error), abort with a message. |
| 63 | |
| 64 | ### Step 2: Process Operations |
| 65 | |
| 66 | Process operations in this fixed order, matching the handoff.md template sections: |
| 67 | |
| 68 | 1. Create all issues (parents first, then children) via `mcp_github_issue_write` with method `create`. Each Create MUST include title, body, and at least one label per the Issue Field Matrix in #file:./github-backlog-planning.instructions.md. |
| 69 | 2. Update existing issues via `mcp_github_issue_write` with method `update`. |
| 70 | 3. Link sub-issues via `mcp_github_sub_issue_write` with method `add`, using `issue_number` for the parent and `sub_issue_id` for the child. |
| 71 | 4. Close duplicate or resolved issues via `mcp_github_issue_write` with `state: 'closed'` and the appropriate `state_reason`. |
| 72 | 5. Add comments for context via `mcp_github_add_issue_comment`. |
| 73 | |
| 74 | Checkpoint after each operation completes: |
| 75 | |
| 76 | * Check the autonomy tier to determine whether a confirmation gate is required. Refer to the Three-Tier Autonomy Model in #file:./github-backlog-planning.instructions.md for gate definitions. When the user declines a gated operation, mark it as `Skipped` in handoff-logs.md and continue. |
| 77 | * When `dryRun` is `true`, simulate the operation and log it as `dry-run` without executing (see the Dry Run Mode section). |
| 78 | * After each Create, resolve the `{{TEMP-N}}` placeholder to the actual issue number returned by `mcp_github_issue_write`. Record the mapping in handoff-logs.md. |
| 79 | * When a `{{TEMP-N}}` reference appears in a Link or Update operation, resolve it from the mapping table before calling the MCP tool. |
| 80 | * Before each API call, re-apply the Planning Reference ID Guard from #file:./github-backlog-planning.instructions.md to catch planning reference IDs (such as `IS002`) that became resolvable after new `{{TEMP-N}}` mappings were established. |
| 81 | * Update the checkbox to `[x]` in handoff.md after each operation completes. |
| 82 | * Append an entry to handoff-logs.md recording the issue number, action taken, and any notes. |
| 83 | * On failure, log the error and continue processing remaining operations. Do not abort the batch for a single failure. |
| 84 | |
| 85 | When an operation has no pending changes: |
| 86 | |
| 87 | * Mark the checkbox as `[x]` in handoff.md with a note: "No changes required." |
| 88 | * Skip API calls for that item. |
| 89 | * Continue to the next operation in the processing queue. |
| 90 | |
| 91 | ### Step 3: Finalize and Report |
| 92 | |
| 93 | * Re-read handoff-logs.md and compare against `handoff`. |
| 94 | * Process any missed operations that were skipped due to dependency failures and have since been unblocked. Limit this retry pass to one additional iteration; log any operations still blocked after the retry as `Failed`. |
| 95 | * Cross-check created issues against the plan to confirm all `{{TEMP-N}}` placeholders resolved. |
| 96 | * Generate a handoff summary with counts: issues created, updated, closed, linked, failed, and skipped. |
| 97 | * Provide a completion report listing all processed items with issue numbers. |
| 98 | |
| 99 | ## Supported Operations |
| 100 | |
| 101 | | Operation | MCP Tool | Method | Required Fields | |
| 102 | |------------------|--------------------------------|----------|--------------------------------------------------| |
| 103 | | Create | `mcp_github_issue_write` | `create` | owner, repo, title, body, labels | |
| 104 | | Update | `mcp_github_issue_write` | `update` | owner, repo, issue_number | |
| 105 | | Close | `mcp_github_issue_write` | `update` | owner, repo, issue_number, state, state_reason | |
| 106 | | Add Labels | `mcp_github_issue_write` | `update` | owner, repo, issue_number, labels | |
| 107 | | Set Milestone | `mcp_github_issue_write` | `update` | owner, repo, issue_number, milestone | |
| 108 | | Add Sub-issue | `mcp_github_sub_issue_write` | `add` | owner, repo, issue_number, sub_issue_id | |
| 109 | | Add Comment | `mcp_github_add_issue_comment` | N/A | owner, repo, issue_number, body | |
| 110 | | Set PR Milestone | `mcp_github_issue_write` | `update` | owner, repo, issue_number (PR number), milestone | |
| 111 | | Set PR Labels | `mcp_github_issue_write` | `update` | owner, repo, issue_number (PR number), labels | |
| 112 | | Set PR Assignees | `mcp_github_issue_write` | `update` | owner, repo, issue_number (PR number), assignees | |
| 113 | |
| 114 | Pull request field operations use `mcp_github_issue_write` because GitHub treats pull requests as a superset of issues sharing the same number space. Pass the PR number as `issue_number` to set milestones, labels, or assignees on a pull request. The `mcp_github_update_pull_request` tool does not support these fields. |
| 115 | |
| 116 | When an operation produces community-visible output (closing issues, requesting information, acknowledging contributions), follow the scenario templates in #file:./community-interaction.instructions.md. Apply the comment-before-closure pattern: call `mcp_github_add_issue_comment` with the appropriate scenario template before any state-changing call such as `mcp_github_issue_write` with closure. |
| 117 | |
| 118 | Refer to the Issue Field Matrix and Pull Request Field Operations sections in #file:./github-backlog-planning.instructions.md for complete field requirements per operation type. |
| 119 | |
| 120 | ## Error Handling |
| 121 | |
| 122 | Each error scenario describes the expected behavior. Unrecognized errors SHOULD be logged and processing SHOULD continue with remaining operations. |
| 123 | |
| 124 | ### Failed Create |
| 125 | |
| 126 | Log the error in handoff-logs.md with `Failed` status. Skip dependent child issues and sub-issue links that reference the failed parent. Continue processing remaining operations. |
| 127 | |
| 128 | ### Failed Update |
| 129 | |
| 130 | Log the error in handoff-logs.md with `Failed` status. Continue processing remaining operations. |
| 131 | |
| 132 | ### Issue Not Found (404) |
| 133 | |
| 134 | When an Update, Close, or Link operation targets an issue that no longer exists, log the error in handoff-logs.md with `Failed` status and continue. This can occur when an issue is deleted between planning and execution. |
| 135 | |
| 136 | ### Rate Limit (429) |
| 137 | |
| 138 | Pause and retry up to three times with exponential backoff. Note the delay in handoff-logs.md. If retries are exhausted, log the error and continue with remaining operations. |
| 139 | |
| 140 | ### Authentication or Permission Error (401/403) |
| 141 | |
| 142 | Abort processing and notify the user. Do not retry authentication errors. |
| 143 | |
| 144 | ### Invalid Label |
| 145 | |
| 146 | Log a warning in handoff-logs.md. Skip the invalid label and continue applying other field changes. |
| 147 | |
| 148 | ### Invalid Milestone |
| 149 | |
| 150 | Log a warning in handoff-logs.md. Skip the milestone assignment and continue applying other field changes. |
| 151 | |
| 152 | ### Missing Parent for Sub-issue Link |
| 153 | |
| 154 | Leave the Link operation unchecked with a `Pending: parent` note. Revisit during the Step 3 retry pass. |
| 155 | |
| 156 | ### Transient Network Failure |
| 157 | |
| 158 | Retry up to three times with exponential backoff. If failures persist, log the error and continue with remaining operations. |
| 159 | |
| 160 | ## Conversation Guidance |
| 161 | |
| 162 | ### Internal Operator Updates |
| 163 | |
| 164 | Keep the user informed during processing: |
| 165 | |
| 166 | * Use markdown formatting with proper paragraph spacing. |
| 167 | * Use emojis sparingly to indicate status (success, warning, error). |
| 168 | * Provide brief updates after each operation completes. |
| 169 | * Avoid overwhelming the user with verbose output; summarize progress at natural checkpoints (after all Creates, after all Updates, and so on). |
| 170 | |
| 171 | ### Community-Facing Comments |
| 172 | |
| 173 | Comments posted to GitHub issues or pull requests are visible to external contributors. These comments follow a different voice and tone than internal operator updates. |
| 174 | |
| 175 | * Apply the scenario templates from #file:./community-interaction.instructions.md for all community-visible comments. |
| 176 | * Match the Tone Calibration Matrix in that file. Tone ranges from warm and genuine for acknowledgments to respectful and direct for scope closures to constructive and specific for information requests. |
| 177 | * Fill all template placeholders with specific, actionable details rather than generic language. |
| 178 | |
| 179 | ## Autonomy Levels |
| 180 | |
| 181 | The autonomy model controls confirmation gates during execution. Defaults to Partial Autonomy when `autonomy` is not specified. Refer to the Three-Tier Autonomy Model in #file:./github-backlog-planning.instructions.md for the full specification and gate definitions. |
| 182 | |
| 183 | When the user declines a gated operation, mark it as `Skipped` in handoff-logs.md and continue to the next operation. |
| 184 | |
| 185 | ## Dry Run Mode |
| 186 | |
| 187 | When `dryRun` is `true`: |
| 188 | |
| 189 | * Simulate all operations without calling MCP tools that modify state. |
| 190 | * Read-only validation calls (`mcp_github_issue_read`, `mcp_github_get_label`) still execute to verify references. |
| 191 | * Generate handoff-logs.md with all operations marked as `dry-run` status. |
| 192 | * Present the execution summary for user review. |
| 193 | * Re-invoke with `dryRun` set to `false` to execute the plan. |
| 194 | |
| 195 | ## Handoff File Format |
| 196 | |
| 197 | The execution workflow consumes handoff.md and produces handoff-logs.md. Both templates are defined in #file:./github-backlog-planning.instructions.md. |
| 198 | |
| 199 | ### handoff.md (consumed) |
| 200 | |
| 201 | Read the Issues section of handoff.md. Each checkbox entry represents one operation. Checked entries (`[x]`) are already complete (from a prior execution run); unchecked entries (`[ ]`) are pending. |
| 202 | |
| 203 | ### handoff-logs.md (produced) |
| 204 | |
| 205 | Create handoff-logs.md next to the handoff file. Append an entry after each operation completes. Use the template and field definitions from #file:./github-backlog-planning.instructions.md. The `dry-run` status value extends the template's defined values (`Success`, `Failed`, `Skipped`) for dry run mode operations. |
| 206 | |
| 207 | ## Success Criteria |
| 208 | |
| 209 | Execution is complete when: |
| 210 | |
| 211 | * All planned operations from handoff.md are either executed or logged with a final status. |
| 212 | * All `{{TEMP-N}}` placeholders are resolved to actual issue numbers (or logged as failed). |
| 213 | * handoff-logs.md contains an entry for every operation in the plan. |
| 214 | * The Execution Summary in handoff-logs.md reflects accurate counts for succeeded, failed, and skipped operations. |
| 215 | * A completion report has been presented to the user with issue numbers. |
| 216 | |
| 217 | --- |
| 218 | |
| 219 | Brought to you by microsoft/hve-core |
| 220 | |