theam/claude-dev-kit/issue-update

Issue Update

Close the loop: after the code ships, the tracker must reflect it without anyone updating it by hand. This skill speaks to whichever tracker is configured in .claude/dev-kit.json (tracker.type).

Preconditions

• .claude/dev-kit.json exists with a tracker block (otherwise run dev-kit-setup first).
• The adapter's backend is authenticated (MCP connector authorized, or gh/az logged in) — otherwise tell the user how to authenticate and stop.
• A PR URL and a product-facing summary of the delivered work are available from the delivery flow.

1. Comment the delivery summary

Audience: product owners and other non-technical readers. The comment explains what was delivered and why, in user terms — no test counts, coverage percentages, lint, or tooling jargon. All technical evidence lives in the PR, which is linked.

Post a comment (via the adapter below) containing:

Pull request: <PR URL>
 
What was delivered:
- <the new behavior, described as a user would experience it — one bullet per acceptance criterion addressed>
 
Decisions taken:
- <each meaningful decision or interpretation made during implementation, in plain language, with the reason>
 
Out of scope / follow-ups:
- <anything deliberately left out or worth a future ticket, or "Nothing pending.">

Keep it factual and grounded in what was actually built — never a template filled with assumptions. If an acceptance criterion was NOT met, say so here plainly.

2. Ensure the item has a named owner

Every item carries a named owner: if it has no assignee, assign it to the current user. Agents act on a person's behalf — the item must always show whose behalf that is. (Skip only for trackers/flows where assignment is not applicable, and say so.)

3. Transition to review

Move the item to the team's review status. Never hardcode transition/state IDs — discover the available ones and pick the target named like "In Review" / "Code Review" / "Review"; if none matches, ask the user once and persist the choice under tracker.reviewState in .claude/dev-kit.json.

Adapters

Jira (type: "jira")

Honors the same authMode as issue-fetch ("mcp" default, "rest" for clients without the Atlassian MCP — same env credentials and automatic-fallback rule).

• MCP: comment and assign via the Atlassian MCP; transition by fetching available transitions via the MCP (IDs vary per tenant).
• REST: comment with POST <base>/rest/api/3/issue/<KEY>/comment; list transitions with GET <base>/rest/api/3/issue/<KEY>/transitions and apply the review one with POST to the same path; assign with PUT <base>/rest/api/3/issue/<KEY>/assignee. Auth headers as in issue-fetch (Basic for Cloud, Bearer PAT for Server); credentials from the environment, never the config.
• Either way, pick/persist the review transition ID under tracker.reviewState.

Linear (type: "linear")

• Comment and assign via the Linear MCP.
• Transition: set the issue's workflow state to the team's review state (discover states via the MCP; persist the chosen state id).

GitHub Issues (type: "github")

• Comment: gh issue comment <number> --repo <owner/name> --body-file -.
• Owner: gh issue edit <number> --add-assignee @me if unassigned.
• "Review status": GitHub issues have no workflow states — apply the label the team uses (e.g. in-review) via gh issue edit --add-label, and/or move it in the project board if one is configured. Persist the label under tracker.reviewState.
• Verify both writes by read-back — never trust the exit code. gh issue edit can fail while applying nothing (its project-fields prefetch trips on repos whose org ever used classic Projects), which is the worst shape for the step the story is not done without. After editing, run gh issue view <number> --json assignees,labels and confirm the assignee and label actually landed; on a miss, apply via REST instead — gh api repos/<owner>/<repo>/issues/<number>/assignees -f "assignees[]=<login>" / gh api repos/<owner>/<repo>/issues/<number>/labels -f "labels[]=<label>" — and report which path worked.

Azure DevOps (type: "azure")

• Comment and assign via the Azure DevOps MCP or REST / az boards.
• Transition: set System.State to the team's review state (discover valid states for the work-item type; persist under tracker.reviewState).

4. Report

Tell the user, explicitly and always covering all three: comment posted (link), owner ensured (who — or why it could not be assigned), and transition applied (from → to). Anything that could not be done gets a reason — no step is ever skipped silently.

Failure handling

• No matching review state (workflow differs): list the available ones and ask once; persist the answer.
• No permission to transition: report it explicitly — do not silently skip.
• The comment must be posted even if the transition fails.