orchestrate-prep

Orchestrate Prep Skill

Bulk-prepares FHIR Jira tickets for workgroup review by drawing unprocessed tickets directly from the Jira source, dispatching concurrent ticket-prep sub-agents, and reporting completion back to the source. There is no markdown worklist — the Jira source's ProcessedLocally flag is the sole persistent state.

Prerequisites

• The fhir-augury-cli skill must be available — it is the canonical entry point for talking to the Jira source. Follow its fallback order (CLI → MCP → direct HTTP) for every data interaction.
• The ticket-prep skill must be available — it defines the per-ticket workflow and report format that each sub-agent runs. The report structure, all data-access steps, the repo-analysis briefing dependency, and the disposition rules are all owned by ticket-prep and must not be replicated here.
• The orchestrator service and Jira source service must be reachable. Verify with the CLI's services health check before starting.

Inputs

The user must provide or you must determine:

1. Output directory — where prepared reports are saved, organized by work-group nameClean subfolder. Example: ./cache/output/prepared/.
2. Concurrency (optional, default 4) — maximum number of concurrent sub-agents.
3. Work group (optional) — a single work group to restrict the run to. May be supplied as the work group's code, name, or nameClean (case insensitive). The orchestrator resolves it against the work-group list returned by list-jira-workgroups. If omitted, tickets are drawn at random across all work groups (no per-WG round-robin — the Jira source's random draw handles distribution).
4. Statuses (optional, default ["Triaged"]) — list of Jira statuses to consider unprocessed candidates from. Common alternatives: ["Submitted"], ["Submitted","Triaged"].
5. Projects (optional, default ["FHIR"]) — list of Jira project keys to draw from. Common alternatives: ["UTG"], ["FHIR","UTG"].
6. Additional Jira filters (optional) — any subset of the JiraLocalProcessingFilter shape (e.g., priorities, types, specifications, labels, reporters, changeCategories, changeImpacts, relatedArtifacts). These are forwarded verbatim on every random-draw call.
7. Max tickets (optional) — overall cap on tickets to process this run. If omitted, run until the random draw returns 404 (no more unprocessed tickets matching the filter).
8. Working directory (optional, default temp/prep/ relative to the repo root) — directory the orchestrator and each sub-agent may use for transient files. Created if it does not already exist. Must be writable on the current platform.

Work-Group Names

Work-group records returned by list-jira-workgroups include code, name, and nameClean directly, plus a top-level catalogJoinDegraded flag on the response envelope. Selectors may be supplied as any of the three forms — the shared WorkGroupResolver (see FhirAugury.Common.WorkGroups) accepts code, name, or nameClean interchangeably and falls back to fuzzy display-name matching (Jaro-Winkler ≥ 0.92) when no exact match is found.

• Use nameClean verbatim for output subdirectory names — folder paths must stay stable across runs.
• Use name for human-facing labels — README headings, run reports, and skill prose all render the display name.
• catalogJoinDegraded is a proceed-with-warning signal. Show a single top-of-run banner when set; do not abort. Every entry's nameClean is still populated — the server falls back to Hl7WorkGroupNameCleaner.Clean(name) when the HL7 catalog join is empty.

Jira-source operations used

All operations are reached via the fhir-augury-cli skill. Prefer the typed jira-local-processing family (added in the 2026-04 sync); the generic call form is documented as a fallback only.

Purpose	CLI form (primary, typed)
Health check	{"command":"services","action":"health"}
List work groups (with code/name/nameClean/issueCount)	{"command":"list-jira-workgroups"}
Draw a random unprocessed ticket	{"command":"jira-local-processing","action":"random-ticket","body":{...filter...}}
Mark a ticket processed locally	{"command":"jira-local-processing","action":"set-processed","body":{"key":"FHIR-XXXXX","processedLocally":true}}
Inspect processed flags (admin)	{"command":"jira-local-processing","action":"tickets","body":{...filter...}}
Clear all processed flags (admin)	{"command":"jira-local-processing","action":"clear-all-processed"}

Valid action values for jira-local-processing (per src/FhirAugury.Cli/Dispatch/Handlers/JiraLocalProcessingHandler.cs): tickets, random-ticket, set-processed, clear-all-processed.

Fallback (older call form, still works): the resolver matches Jira.local-processing.<name> first, then falls back to local-processing.<name> — e.g., {"command":"call","source":"jira","operation":"local-processing.get-random-ticket","body":{...}}. Use only when running against a build that predates the typed family.

Pre-run ingestion (optional)

If the bulk run needs fresh Jira data for a single project, scope an ingest with the jiraProject parameter before starting:

fhir-augury-cli --json '{"command":"ingest","action":"trigger","sources":["jira"],"jiraProject":"FHIR"}'

Only the Jira leg of the fan-out receives the parameter; other sources ingest normally. Omit jiraProject to ingest every configured project.

Random-draw filter shape

Build the body for local-processing.get-random-ticket per JiraLocalProcessingFilter (in src/FhirAugury.Source.Jira/Api/JiraContracts.cs). The orchestrator builds one filter per draw using the configured inputs:

{
  "workGroups": ["Orders & Observations"],
  "processedLocally": false,
  "statuses": ["Triaged"],
  "projects": ["FHIR"]
}

• Always include "processedLocally": false.
• Include workGroups only when a single work group was supplied.
• Always include statuses and projects (defaulted if not supplied).
• Merge any Additional Jira filters into this body before each draw.

A successful draw returns a JiraIssueSummaryEntry (key, workGroup, title, status, …). A 404 means no unprocessed tickets remain matching the filter — terminate draws (the run is exhausted).

Workflow

Step 1: Verify services and resolve inputs

1. Health-check the orchestrator and Jira source via the CLI's services command. Abort with a clear message if either is down.
2. Fetch the work-group list with list-jira-workgroups. Read code, name, nameClean, issueCount from the JSON response — the CLI surfaces nameClean directly; do not re-derive it from name.
3. If the user supplied a Work group, resolve it against code / name / nameClean (case insensitive). Abort if no match.
4. Apply defaults: statuses → ["Triaged"], projects → ["FHIR"], concurrency → 4, working directory → temp/prep/ relative to the repo root.

Step 2: Confirm with the user

Before any draws or directory creation, present a one-screen summary and ask the user to confirm. Use the ask_user tool. Include every resolved input so the user can verify defaults haven't masked a typo:

About to start bulk prep with the following configuration:

  Output directory : C:\ai\git\fhir-augury-content\prepared\
  Working directory: temp/prep/   (relative to repo root)
  Work group       : (all)        — or: "Orders & Observations" (nameClean: OrdersAndObservations)
  Statuses         : Triaged
  Projects         : FHIR
  Other filters    : (none)       — or list any additional filters
  Concurrency      : 4
  Max tickets      : (no cap)     — or: 50

Proceed?

Choices: Yes, start, Cancel. Do not proceed on anything except explicit confirmation.

Step 3: Create directories (cross-platform)

Both the output directory and the working directory must exist before dispatching sub-agents. Create them idempotently using a method that works on both Windows (PowerShell) and Unix (bash). Two acceptable patterns:

• Tool-based (preferred when available): use the agent's file-system tool to create directories — it abstracts the platform.
• Shell-based: detect the shell and run the appropriate command:
  • PowerShell: New-Item -ItemType Directory -Path $Path -Force | Out-Null
  • bash/sh: mkdir -p "$Path"

If a single work group was supplied, also create <OutputDir>/<nameClean>/ for that group. Otherwise, create each work-group subdirectory lazily as tickets for that group are returned by the random draw (avoids creating empty directories for inactive WGs).

The working directory should be passed through to each sub-agent so all transient files land in the same controlled location.

Step 4: In-flight tracking

Maintain in memory:

• inFlight — set of ticket keys currently assigned to a running sub-agent. This is the only tracking required, and exists solely to prevent assigning the same ticket to two sub-agents (the random draw is unaware of in-flight state).
• completed / failed counters for progress reporting.

Persist nothing locally; the Jira source's ProcessedLocally flag is the durable state.

Step 5: Draw and dispatch loop

Loop until the in-flight set is empty AND the last draw returned 404, or the optional max-tickets cap is reached:

1. While len(inFlight) < concurrency and the run is not exhausted:
   1. Build the random-draw filter (work group if supplied, processedLocally:false, statuses, projects, any user filters) and call local-processing.get-random-ticket.
   2. Handle the response:
      • 404 / empty → mark the run exhausted; stop drawing. Wait for in-flight agents to d

---

Content truncated.