Skip to content

fix: make work item state transitions mandatory and explicit#22

Open
fedeoliv wants to merge 1 commit into
mainfrom
fix/work-item-state-transitions
Open

fix: make work item state transitions mandatory and explicit#22
fedeoliv wants to merge 1 commit into
mainfrom
fix/work-item-state-transitions

Conversation

@fedeoliv
Copy link
Copy Markdown
Contributor

@fedeoliv fedeoliv commented May 7, 2026

Problem

The implement coordinator and the devsquad.implement.finalize worker treated board updates as advisory. Result observed in a recent session: GitHub issues and Azure DevOps work items stayed in New through the full implement -> PR cycle even though every required tool (ado/wit_update_work_item, github/issue_write) was wired up.

The agent acknowledged the gap directly when asked: "The work-item-workflow skill exists exactly for this and I haven't been invoking it." So this is not a knowledge gap. It is an invocation and enforcement gap, and it recurs across sessions.

Two reinforcing causes:

  1. Source classification weakness. The work-item-workflow skill's source-detection rule treated "no explicit ID in this message" as tasks.md only, even when a work item ID was present in the recent conversation or the tasks.md being implemented.
  2. Soft language at the finalize step. devsquad.implement.finalize instructed "Update the work item state as appropriate" with no state machine, no preconditions, and no observable output the coordinator could check.

Changes

  • skills/work-item-workflow/SKILL.md: Source detection now resolves to board mode whenever a work item ID is reachable from the user's request, recent conversation, or the tasks.md being implemented (e.g., "implement the Terraform task" with #1690 upthread). Phase 2 makes state transitions mandatory, with a re-read confirmation and a single retry before surfacing failure. If the board MCP is unreachable, the agent surfaces a blocking error rather than skipping.
  • agents/devsquad.implement.agent.md: Phase 1 documented as a precondition. No code-editing tool runs until the task and parent user story are Active with the current user as assignee. Added a Notes rule reaffirming that transitions are mandatory and that MCP failures must surface, not be skipped.
  • agents/devsquad.implement.finalize.agent.md: "Update as appropriate" replaced with an explicit per-platform state machine (Active on start -> Resolved on PR open -> Closed on merge), procedural steps that use ado/wit_get_work_item to verify preconditions, and a structured Board Updated: #<id> <prev> -> <new> output line so the coordinator can detect skipped transitions.

Out of Scope

  • No hook. The instruction-level fix should be measured first. If the gap recurs after these changes ship, a deterministic hook becomes the next iteration with stronger justification.
  • No harness-learnings entry. This is a framework gap that affects every consumer, not a per-codebase pattern. The skill itself excludes "learnings about the framework" from capture (SKILL.md line 39).
  • No automatic close on merge. The existing rule stands: PR uses Closes #N for GitHub; ADO transition to Closed remains the developer's action.

The implement coordinator and the finalize worker treated board updates
as advisory, so issues and Azure DevOps work items routinely stayed in
New through the full implement and PR cycle, even though every required
tool was wired up.

Changes:

- work-item-workflow source detection now resolves to board mode
  whenever a work item ID is reachable from the user request, recent
  conversation, or the tasks.md being implemented, including phrasings
  like 'implement the Terraform task' or 'continue the work'. tasks.md
  mode only applies when no ID is reachable.

- work-item-workflow Phase 2 makes state transitions mandatory, with a
  re-read confirmation and a single retry before surfacing failure. If
  the board MCP is unreachable, the agent surfaces a blocking error
  rather than skipping silently.

- devsquad.implement orchestration documents Phase 1 as a precondition.
  No code-editing tool runs until the task and parent user story are
  Active with the current user as assignee.

- devsquad.implement.finalize replaces 'update as appropriate' with an
  explicit state machine (Active on start, Resolved on PR open, Closed
  on merge), per-platform procedure, and a structured 'Board Updated:
  #<id> <previous> -> <new>' output so the coordinator can detect
  skipped transitions.

CHANGELOG entry to be landed alongside the existing Unreleased WIP.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@fedeoliv fedeoliv changed the title fix(implement): make work item state transitions mandatory and explicit fix: make work item state transitions mandatory and explicit May 7, 2026
@fedeoliv fedeoliv requested a review from dmakogon May 7, 2026 18:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant