Devops Requirements

DevOps Requirements Extraction

Extract and compile actionable requirements from Azure DevOps work items into a structured requirements brief.

Input / Output

• Input: Work item ID or Azure DevOps URL
• Output: Requirements brief (markdown — in context or saved to artifact directory)

When to Use

This skill applies when you need to extract structured information from a DevOps work item:

• Fetch a work item's description, design field, and acceptance criteria
• Review parent/child relations and download attachments
• Compile a requirements brief from work item content

This skill extracts and structures — it does not create reports, datasources, or other artifacts. If the goal is to create something from a work item, use the appropriate creation skill as the entry point; it will invoke this skill when it needs work item data.

Step 1: Fetch the Work Item

dxs devops workitem <ID> --full --expand All

--full prevents truncation of long fields. --expand All includes relations (parent, children, attachments).

Key fields to extract:

The description and design fields are auto-converted from HTML to markdown. For long design fields, scan for SQL SELECT statements and column lists — these map directly to OData fields needed for schema discovery.

Step 2: Review Relations

Present the work item's relations to the user:

This work item has:
- Parent: #218666
- Children: #218813
- Attachments: 4 files (ValleyWarehouseReceiptInvoice.rdlx-json, Order 96269-20250041 - Receiving report.pdf, ...)

Would you like me to fetch any of the child items for additional context?

To batch-fetch selected children:

dxs devops workitems <ID1>,<ID2> --description --discussions

--description includes full descriptions; --discussions includes comments/history. Up to 200 items per request.

Don't auto-traverse all children — ask the user which are relevant. Child items of type "Wavelength Component" often contain implementation details, while "Bug" or "Task" children may not be relevant to report design.

Ad-hoc queries: dxs devops wiql (dxs ≥ 0.4.18)

When the work item you need isn't reachable from an ID you already have — "every Active item in this area path", "what's assigned to me", "the whole hierarchy under #218666" — run WIQL directly rather than guessing IDs or paging devops search:

# Flat: one row per work item. Columns named in SELECT are fetched for each match.
dxs devops wiql "SELECT [System.Id],[System.Title],[System.State] FROM WorkItems \
  WHERE [System.State] = 'Active' ORDER BY [System.ChangedDate] DESC" --limit 25

# Tree / one-hop: one row per source→target link, target fields merged in.
dxs devops wiql "SELECT [System.Id],[System.Title] FROM WorkItemLinks \
  WHERE [Source].[System.Id] = 218666 \
    AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward' \
  MODE (Recursive)" --project FootPrint

-Q/--query-file reads a long query from a file; --ids-only skips the field fetch when you just want IDs to feed dxs devops workitems. Read metadata.total_count (what the query matched) against metadata.count (what came back after --limit, default 200) and check truncated — a capped result is not the full answer, and the same "ask the user which are relevant" rule applies to whatever it returns.

Step 3: Validate Scope with the User

Before downloading attachments or building a requirements brief, confirm with the user what to pay attention to. Work items often accumulate attachments, comments, and design notes over time — some may be outdated, misattached, or for a different report entirely.

Present a summary and ask:

This work item has:
- Description: [1-sentence summary]
- Design field: [1-sentence summary — e.g., "SQL views for 3 datasets"]
- Attachments: [list filenames]
- Children: [list if any]

Which of these should I focus on for the report requirements?
Are any of the attachments not relevant to this report?

Why this matters: Work items may contain attachments from related but different reports, sample PDFs that don't match the current requirement, or design notes that were superseded. Using the wrong attachment as a layout reference can send the entire design down the wrong path. Always let the user confirm before treating any attachment as authoritative.

Step 4: Download Attachments

List attachments:

dxs devops attachments <ID>

Download by index (faster) or filename:

dxs devops attachments <ID> --download 1 --out <artifact_dir>/requirements/report.rdlx-json
dxs devops attachments <ID> --download "Valley Cold HC BRD.pdf" --out <artifact_dir>/requirements/brd.pdf

Which attachments to download (after user confirms relevance):

For downloaded .rdlx-json files, use dxs report inspect to quickly understand the structure:

dxs report inspect <artifact_dir>/requirements/report.rdlx-json

For .rdl files (SSRS XML), scan for <CommandText> elements containing SQL — the SELECT columns and FROM/JOIN tables map to OData entities and fields.

If PDF reading fails (e.g., missing poppler): Note the files as "downloaded but unreadable" in the requirements brief and proceed with the work item's description and design fields, which usually contain the most actionable information. For .pdf sample output, ask the user to describe the expected layout verbally as a fallback. Always download PDFs to the artifact directory regardless — the user can review them manually.

Step 5: Compile Requirements Brief

After gathering work item data and attachments, compile a requirements brief. This feeds into downstream skills (e.g., schema-explorer, datasource-creator, report-creator).

Template:

## Requirements Brief

**Report:** [title from work item]
**Purpose:** [1-2 sentence summary from description]
**Work Item:** #[ID] ([state])

### Data Requirements
- **Primary entity:** [derived from SQL FROM clause or description]
- **Key fields:** [from SQL SELECT or design field]
- **Filters/parameters:** [from SQL WHERE or description]
- **Related entities:** [from SQL JOINs or $expand needs]

### Filtering & Exclusion Rules
- [Extract EVERY filtering rule from the design notes, SQL WHERE clauses, and business requirements]
- [For each rule, note the original SQL/description AND the proposed OData equivalent]
- [Flag rules involving collection checks (subqueries) — these likely need lambda operators: `any()`/`all()`]
- [Flag rules involving string patterns (LIKE) — these likely need `startswith`/`endswith`/`contains`]
- [Example: "Exclude -10 locations in zones 04-06" → `not (endswith(Name,'-10') and (startswith(Name,'04') or ...))` ]

### Layout Expectations
- **Page size:** [from existing report or description]
- **Orientation:** [portrait/landscape]
- **Key sections:** [header, detail grid, footer, etc.]
- **Special elements:** [barcodes, logos, multi-column layout]

### Entity Keywords for Schema Search
[List of OData entity search terms derived from SQL table names or description nouns]

### Reference Materials
- [List downloaded attachments and what each provides]

Save the brief to <artifact_dir>/requirements/requirements-brief.md if artifacts are enabled.

Anti-patterns

• Don't dump raw work item content into context — summarize the description and design fields, extracting only the actionable parts (field lists, SQL, layout specs)
• Don't auto-fetch the entire work item tree — parent and children may be irrelevant; ask the user
• Don't skip the design field — it often contains the most detailed specs, including exact SQL queries that map to OData fields
• Don't ignore existing .rdlx-json attachments — they provide concrete field mappings and layout that accelerate schema discovery and prototyping