helix.mcp: Skill for Claude Code

Helix SDK: WorkItemSummary vs. WorkItemDetails Field Surface

Use this pattern when a Helix.Client SDK bump potentially adds new fields to WorkItemSummary (the list-API response), and you need to decide which DetailsAsync (per-item) call sites can be eliminated.

The optimization problem

ListAsync returns a WorkItemSummary for every work item in one HTTP call.
DetailsAsync fetches WorkItemDetails per work item — O(N) HTTP calls.

When the list API starts returning fields that previously required a per-item details call, those details calls become unnecessary (for those fields). The key question: which fields does each call site actually need?

Audit checklist (run after each SDK bump)

For every call site that calls GetWorkItemDetailsAsync:

1. List the fields read from details.
   Common: ExitCode, State, MachineName, Started, Finished, ConsoleOutputUri.

2. Check which of those fields are now on IWorkItemSummary.
   After arcade PR #16722 (client ≥ 11.0.0-beta.26325.x): ExitCode, ConsoleOutputUri.

3. Decision matrix:

Fields needed from details	Can skip DetailsAsync?
ONLY ExitCode	✅ Use summary.ExitCode
ONLY ConsoleOutputUri	✅ Use summary.ConsoleOutputUri
ONLY ExitCode + ConsoleOutputUri	✅ Use both from summary
State or MachineName or Started/Finished (duration)	❌ Keep DetailsAsync

1. For loop/batch callers (N work items): Only skip DetailsAsync for the whole batch if NONE of the loop iterations need State/MachineName/Duration. A hybrid is also valid: use summary.ExitCode to avoid DetailsAsync for zero-exit-code items, still call it for non-zero/null.

The ExitCode=0 fast-path (canonical optimization)

// In a loop over IWorkItemSummary items:
var tasks = workItems.Select(wi => wi.ExitCode == 0
    ? Task.FromResult(CreatePassedResult(wi, id))   // skip DetailsAsync
    : CreateDetailedResultAsync(wi, id, semaphore, ct)) // still calls DetailsAsync
    .ToList();