devops-requirements

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DevOps Requirements Extraction

DevOps需求提取

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

从Azure DevOps工作项中提取并整理可执行需求，生成为结构化的需求简报。

Input / Output

输入/输出

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

输入： 工作项ID或Azure DevOps URL
输出： 需求简报（Markdown格式——可直接展示或保存到工件目录）

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.

当你需要从DevOps工作项中提取结构化信息时，可使用本技能：

获取工作项的描述、设计字段与验收标准
查看父/子关联关系并下载附件
从工作项内容中整理需求简报

本技能仅负责提取与结构化处理——不生成报告、数据源或其他工件。若目标是基于工作项创建内容，请使用对应的创建类技能作为入口；当需要工作项数据时，该技能会自动调用本技能。

Step 1: Fetch the Work Item

步骤1：获取工作项

bash

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

--full

prevents truncation of long fields.

--expand All

includes relations (parent, children, attachments).

Key fields to extract:

Field	What it tells you
`title`	Report name and purpose
`description`	High-level requirements, often includes embedded screenshots of expected output
`design`	Detailed specs — SQL queries, column lists, business rules. This is often the richest source of field/data requirements
`relations.parent`	Broader project context (fetch if needed for background)
`relations.children`	Implementation sub-tasks — may contain additional specs
`relations.attachments`	Existing reports, sample output PDFs, BRDs
`tags`	Sprint/priority context

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.

bash

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

--full

参数用于避免长字段被截断。

--expand All

参数会包含关联关系（父项、子项、附件）。

需提取的关键字段：

字段	说明信息
`title`	报告名称与用途
`description`	高层级需求，通常包含预期输出的嵌入式截图
`design`	详细规格——SQL查询、列列表、业务规则。这通常是字段/数据需求最丰富的来源
`relations.parent`	更广泛的项目上下文（如需背景信息可获取）
`relations.children`	实现子任务——可能包含额外规格
`relations.attachments`	现有报告、示例输出PDF、业务需求文档（BRD）
`tags`	迭代/优先级上下文

description

和

design

字段会自动从HTML转换为Markdown格式。对于较长的设计字段，需扫描其中的SQL

SELECT

语句和列列表——这些可直接映射到模式发现所需的OData字段。

Step 2: Review Relations

步骤2：查看关联关系

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:

bash

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.

向用户展示工作项的关联关系：

该工作项包含：
- 父项：#218666
- 子项：#218813
- 附件：4个文件（ValleyWarehouseReceiptInvoice.rdlx-json, Order 96269-20250041 - Receiving report.pdf, ...）

是否需要获取任何子项以补充上下文信息？

批量获取选定子项：

bash

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

--description

参数包含完整描述；

--discussions

参数包含评论/历史记录。每次请求最多支持200个项目。

请勿自动遍历所有子项——询问用户哪些子项是相关的。类型为"Wavelength Component"的子项通常包含实现细节，而"Bug"或"Task"类型的子项可能与报告设计无关。

Step 3: Validate Scope with the User

步骤3：与用户确认范围

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.

在下载附件或生成需求简报前，请与用户确认需重点关注的内容。 工作项随着时间推移可能积累大量附件、评论和设计笔记——其中部分可能已过时、附加错误或属于其他报告。

展示摘要并询问：

该工作项包含：
- 描述：[1句话摘要]
- 设计字段：[1句话摘要——例如："3个数据集的SQL视图"]
- 附件：[文件名列表]
- 子项：[如有则列出]

在提取报告需求时，我应重点关注哪些内容？
是否有任何附件与本次报告无关？

重要性说明： 工作项可能包含来自相关但不同报告的附件、与当前需求不匹配的示例PDF，或已被取代的设计笔记。若错误地将无关附件作为布局参考，可能导致整个设计方向出错。在将任何附件视为权威参考前，务必让用户确认其相关性。

Step 4: Download Attachments

步骤4：下载附件

List attachments:

bash

dxs devops attachments <ID>

Download by index (faster) or filename:

bash

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):

Extension	Action	Why
`.rdlx-json`	Download + read	Existing report — extract layout, DataSets, field mappings
`.rdl`	Download + read	SSRS source — extract SQL queries and field mappings for migration
`.pdf`	Download only	May or may not match the current report — ask user before using as layout reference
`.docx` , `.xlsx`	Download if BRD/spec	May contain detailed field lists or business rules
`.png` , `.jpg`	Skip	Usually embedded screenshots already visible in description

For downloaded

.rdlx-json

files, use

dxs report inspect

to quickly understand the structure:

bash

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.

列出附件：

bash

dxs devops attachments <ID>

通过索引（更快）或文件名下载：

bash

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

需下载的附件类型（经用户确认相关性后）：

扩展名	操作	原因
`.rdlx-json`	下载并读取	现有报告——提取布局、数据集、字段映射
`.rdl`	下载并读取	SSRS源文件——提取SQL查询和字段映射用于迁移
`.pdf`	仅下载	可能与当前报告匹配也可能不匹配——用作布局参考前需询问用户
`.docx` , `.xlsx`	若为BRD/规格文档则下载	可能包含详细字段列表或业务规则
`.png` , `.jpg`	跳过	通常是已嵌入描述中的截图

对于已下载的

.rdlx-json

文件，可使用

dxs report inspect

快速了解其结构：

bash

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

对于

.rdl

文件（SSRS XML），扫描包含SQL的

<CommandText>

元素——

SELECT

列和

FROM

JOIN

表可映射到OData实体和字段。

若PDF读取失败（如缺少

poppler

）：在需求简报中注明这些文件“已下载但无法读取”，并继续使用工作项的

description

和

design

字段——这些通常包含最具可执行性的信息。对于PDF示例输出，可让用户口头描述预期布局作为备选方案。无论如何，务必将PDF下载到工件目录——用户可手动查看。

Step 5: Compile Requirements Brief

步骤5：整理需求简报

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:

markdown

undefined

收集完工作项数据和附件后，整理需求简报。该简报将用于下游技能（如schema-explorer、datasource-creator、report-creator）。

模板：

markdown

undefined

Requirements Brief

需求简报

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

报告： [来自工作项的标题] 用途： [来自描述的1-2句话摘要] 工作项： #[ID] ([状态])

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]

主实体： [从SQL FROM子句或描述中推导]
关键字段： [来自SQL SELECT或设计字段]
筛选器/参数： [来自SQL WHERE或描述]
关联实体： [来自SQL JOIN或$expand需求]

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 ...))

]

[从设计笔记、SQL WHERE子句和业务需求中提取所有筛选规则]
[对于每条规则，注明原始SQL/描述以及建议的OData等效表达式]
[标记涉及集合检查（子查询）的规则——这些可能需要lambda运算符：
```
any()
```
/
```
all()
```
]
[标记涉及字符串模式（LIKE）的规则——这些可能需要
```
startswith
```
/
```
endswith
```
/
```
contains
```
]

[示例："排除区域04-06中的-10位置" →

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]

页面尺寸： [来自现有报告或描述]
方向： [纵向/横向]
关键区域： [页眉、明细网格、页脚等]
特殊元素： [条形码、Logo、多栏布局]

Entity Keywords for Schema Search

模式搜索用实体关键词

[List of OData entity search terms derived from SQL table names or description nouns]

[从SQL表名或描述名词中推导的OData实体搜索术语列表]

Reference Materials

参考资料

[List downloaded attachments and what each provides]


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

[列出已下载的附件及其提供的内容]


若启用工件功能，将简报保存到 `<artifact_dir>/requirements/requirements-brief.md`。

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

请勿将原始工作项内容直接导入上下文 ——对描述和设计字段进行摘要，仅提取可执行部分（字段列表、SQL、布局规格）
请勿自动获取整个工作项树 ——父项和子项可能无关；请询问用户
请勿忽略设计字段 ——它通常包含最详细的规格，包括可直接映射到OData字段的精确SQL查询
请勿忽略现有的.rdlx-json附件 ——它们提供具体的字段映射和布局，可加速模式发现与原型开发