@collective-intelligence/backlog 0.0.0-stage → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +105 -2
- package/package.json +20 -4
- package/skills/analyze-business-request/SKILL.md +193 -0
- package/skills/analyze-business-request/references/plan-format.md +111 -0
- package/skills/create-bug/SKILL.md +135 -0
- package/skills/create-bug/references/azure-operations.md +56 -0
- package/skills/create-bug/references/examples.md +39 -0
- package/skills/create-business-request/SKILL.md +232 -0
- package/skills/create-business-request/references/example.md +153 -0
- package/skills/create-business-request/references/intake-guide.md +68 -0
- package/skills/human-backlog-ado/SKILL.md +82 -0
- package/skills/human-backlog-ado/scripts/ado.py +1768 -0
- package/skills/plan-sprint/SKILL.md +139 -0
- package/skills/plan-sprint/references/assessment-guide.md +49 -0
- package/skills/plan-sprint/references/operations.md +111 -0
- package/skills/setup-human-backlog/SKILL.md +83 -0
- package/skills/setup-human-backlog/references/eject.md +26 -0
- package/skills/setup-human-backlog/references/process.md +54 -0
- package/skills/update-business-request/SKILL.md +125 -0
- package/skills/update-business-request/references/examples.md +41 -0
- package/skills/update-business-request/references/operations.md +84 -0
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Bug fields, attachments and recovery
|
|
2
|
+
|
|
3
|
+
Use the shared helper `<ado>` named in `../SKILL.md`. No live ticket should be created just to test the skill.
|
|
4
|
+
|
|
5
|
+
## Fields and parent
|
|
6
|
+
|
|
7
|
+
This example assumes the user confirmed the date change, reload and impact. Actual values must come from the supplied evidence and answers.
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"Title": "Task due date returns to its previous value after reload",
|
|
12
|
+
"ReproSteps": "## Context\nPersonal task list in the portal.\n\n## Steps observed\n1. Open an existing task.\n2. Change its due date and save.\n3. Reload the page.\n\n## Actual result\nThe task shows its previous due date after reload.\n\n## Expected result\nThe saved due date should remain after reload, as confirmed by the user.\n\n## Frequency and impact\nObserved once in the supplied recording. The user cannot rely on the saved deadline.\n\n## Evidence\nThe supplied recording shows the edit, save and reload sequence."
|
|
13
|
+
}
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`ReproSteps` maps to `Microsoft.VSTS.TCM.ReproSteps`; the helper converts the supported Markdown to HTML. Do not put parent IDs into this field or the field JSON. Supply the selected Feature through `--parent`:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
python3 <ado> create --type bug --json /tmp/bug.json --parent 55 --dry-run
|
|
20
|
+
python3 <ado> create --type bug --json /tmp/bug.json --parent 55
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
When no reliable Feature was found, use the same approved fields without a parent:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
python3 <ado> create --type bug --json /tmp/bug.json --dry-run
|
|
27
|
+
python3 <ado> create --type bug --json /tmp/bug.json
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The helper permits parentless Bug intake. Its analysis `apply` command still requires parents for Bugs; that separate rule is not changed. Do not replace the missing parent with an Epic, PBI, Business Request or invented Feature.
|
|
31
|
+
|
|
32
|
+
Keep the returned ID and URL. For an agreed update to an existing Bug, read it first and use `update <Bug ID> --json FILE` with only the approved fields, preserving prior observations. Do not reopen or change its state automatically.
|
|
33
|
+
|
|
34
|
+
## Evidence files
|
|
35
|
+
|
|
36
|
+
Obtain local paths using the environment's supported attachment handling. If a chat file has no accessible local copy, do not invent a path or scrape credentials to retrieve it. Explain the limitation and continue with the inspected/user-confirmed description where sufficient.
|
|
37
|
+
|
|
38
|
+
The attachment command uploads the original bytes and links the uploaded file to the existing work item:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
python3 <ado> attach 123 --file /tmp/bug-recording.mp4 --receipt /tmp/bug-123-recording-receipt.json --comment "Recording supplied by the reporter" --dry-run
|
|
42
|
+
python3 <ado> attach 123 --file /tmp/bug-recording.mp4 --receipt /tmp/bug-123-recording-receipt.json --comment "Recording supplied by the reporter"
|
|
43
|
+
python3 <ado> get 123
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Use a different receipt for each file and Bug. Retain it until the attachment is verified. A receipt records the target, filename, file hash and uploaded attachment URL. Retrying with that same receipt can finish the link without another upload and recognizes an already-linked attachment. A receipt from another target/file is rejected.
|
|
47
|
+
|
|
48
|
+
If upload began but no attachment URL was recorded, the result is uncertain: stop and inspect/report the outcome instead of retrying with a fresh receipt. If the link failed after upload, keep the receipt and retry only that attachment on the existing Bug. Do not create another Bug or claim an unlinked upload is an attachment on the ticket.
|
|
49
|
+
|
|
50
|
+
The helper supports simple uploads up to 130 MB; the server may impose a smaller limit. For a rejected or larger recording, report the missing attachment and suggest a shorter relevant recording. Keep the Bug ID so evidence can be added later. Do not silently modify or discard the original evidence.
|
|
51
|
+
|
|
52
|
+
`get` reports work-item relationships and attachments separately. Verify the expected Feature parent, or its absence, and each attached filename/URL. Explain any partial result to the user.
|
|
53
|
+
|
|
54
|
+
## No-parent result
|
|
55
|
+
|
|
56
|
+
Always return the created ID and URL even when no parent exists. Explicitly tell the user to pass the ID to the developer, with a ready-to-copy request to find the correct Feature and associate the Bug. Missing parent assignment never becomes a silent success or a reason to leave a complete report uncreated.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Intake and matching examples
|
|
2
|
+
|
|
3
|
+
## Screenshots and a description
|
|
4
|
+
|
|
5
|
+
The user says: “I change the due date but then the old one comes back” and supplies two screenshots showing different dates.
|
|
6
|
+
|
|
7
|
+
Suggest a short screen recording, attached directly in chat, showing the starting page, edit, save and subsequent behavior. Narration is optional. Meanwhile inspect the screenshots and search task-editing capabilities. The two dates alone do not establish the order of operations or whether Save was selected. Ask about that missing sequence instead of diagnosing persistence.
|
|
8
|
+
|
|
9
|
+
If the user confirms the steps in text and cannot record, proceed with those steps labelled as user-reported. Do not withhold the Bug for lack of a video.
|
|
10
|
+
|
|
11
|
+
## A recording already supplied
|
|
12
|
+
|
|
13
|
+
A video visibly shows a date edit, Save and reload, followed by the old date. Inspect the relevant interval and ask only about unresolved expectation or impact. Do not ask for another recording or for the user to type out the visible steps.
|
|
14
|
+
|
|
15
|
+
If the environment cannot inspect the video, say so, ask for a concise account of the sequence and attach the approved original if accessible. Describe the account as user-reported. Do not invent timestamps or claim to have verified the video.
|
|
16
|
+
|
|
17
|
+
## Feature match expressed in business terms
|
|
18
|
+
|
|
19
|
+
Internal research finds one Feature for the home task box and another for the full personal task list, whose PBI includes editing task dates. Ask whether the problem happens while editing in the full list or merely when viewing the home box if the evidence does not show this.
|
|
20
|
+
|
|
21
|
+
Once confirmed, propose the relevant Feature with a short explanation of the behavior it covers. Do not ask the reporter to choose an Epic, inspect the hierarchy or supply an item ID.
|
|
22
|
+
|
|
23
|
+
## No reliable parent
|
|
24
|
+
|
|
25
|
+
The user clearly describes a broken behavior, but the backlog has no reliable matching Feature, or several candidates remain equally plausible. Complete the Bug report, preview it with “No parent — developer association required”, then create it without `--parent` after approval. Retain the returned ID.
|
|
26
|
+
|
|
27
|
+
Example final response, replacing the illustrative ID and URL with the actual ones:
|
|
28
|
+
|
|
29
|
+
> Bug #123 created: ‹URL›. It has no parent Feature yet. Pass this ID to the developer so they can link it.
|
|
30
|
+
>
|
|
31
|
+
> Message to forward: “I opened Bug #123, ‹URL›. It has no parent; can you check which Feature to link it to?”
|
|
32
|
+
|
|
33
|
+
Do not create a generic Feature or stop at a draft because the reporter cannot identify the parent. Do not message the developer yourself.
|
|
34
|
+
|
|
35
|
+
## Possible duplicate or expectation conflict
|
|
36
|
+
|
|
37
|
+
An existing Bug has the same symptom but different starting conditions. Compare the full reports and explain the uncertainty; ask whether the user's case matches those conditions. Add observations to the existing item only after agreement, or create a distinct Bug that states the difference.
|
|
38
|
+
|
|
39
|
+
If the user's expected result differs from documented acceptance criteria, show the difference in ordinary language. Preserve the confirmed expectation and the observed behavior without inventing a new rule. A clearly requested new capability can be routed to Business Request intake with the user's agreement; a suspected malfunction can still be reported for investigation.
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: create-business-request
|
|
3
|
+
description: Intake for a new Business Request in the Human Backlog (Azure DevOps). Runs a demanding business interview from a short ask, meeting notes, email or documents, checks duplicate Business Requests, and creates the approved item. Use to capture a new business ask, directly or when another skill hands one over; use analyze-business-request to map an existing Business Request to backlog.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Create a Business Request
|
|
7
|
+
|
|
8
|
+
A Business Request records the complete customer request in enough detail that a Product Owner can analyze it without the intake conversation. It uses business language. The `analyze-business-request` skill maps the request into Epics, Features and PBIs. Technical design and implementation work are outside this skill's scope and are managed separately.
|
|
9
|
+
|
|
10
|
+
The Business Request captures the request at intake. Later refinements can be recorded directly in Features and PBIs using the PO/developer's knowledge and any offline customer discussions; keeping the Business Request synchronized with those discussions is not required. This does not lower the intake completeness standard. Explicit corrections or revisions of an existing Business Request are handled by `update-business-request` within its lifecycle rules.
|
|
11
|
+
|
|
12
|
+
Write saved content in the user's language, and keep an existing item's language when you edit it. Talk to the user in their language.
|
|
13
|
+
|
|
14
|
+
## Intake standard
|
|
15
|
+
|
|
16
|
+
Your job is to extract and document the business information the PO needs to understand the request. The central quality test is whether different readers would infer the same intended behavior, not whether the requester can name a decider or supply success metrics. Be direct, specific and constructive. Explain what is unclear and why a decision matters; challenge the answer without judging the person.
|
|
17
|
+
|
|
18
|
+
- The user's sentence sets the scope. Context supplies evidence, not permission to add adjacent requests.
|
|
19
|
+
- Treat the content as claims to clarify, not requirements to accept automatically. Separate confirmed facts, proposals, contradictions and missing decisions. Preserve useful source references in the saved Business Request's Context, including known dates or asset versions. For an existing approval, record what was approved; do not infer approval of other aspects.
|
|
20
|
+
- Stay at Business Request level. Search and compare **only Business Requests**, in every Human State, including Live, Rejected and Withdrawn ones. Do not search, inspect or assess Features, Epics, PBIs, Bugs, implementation or delivery coverage, even if a Business Request links to them. That belongs to `analyze-business-request`.
|
|
21
|
+
- Strong intake is adaptive: no minimum question count, no fixed questionnaire to recite. Ask only about unresolved decisions, but do not accept an incomplete answer merely because you asked the question.
|
|
22
|
+
- Preserve substantive detail in the saved Business Request. Decisions left only in chat are unavailable to the PO. Use a short summary followed by structured detail, examples and rules; never compress away information just to keep the Business Request short. Do not make the requester write the document: extract and organize their answers.
|
|
23
|
+
- A named decision owner and success criteria are optional supporting information. Record them when supplied or useful; do not run question rounds solely to obtain them. When the customer explicitly requires approval before work can proceed, clarify the approving role, what they approve and what depends on that approval. Expected behavior must still be clear even without formal acceptance criteria.
|
|
24
|
+
|
|
25
|
+
## Invocation from another skill
|
|
26
|
+
|
|
27
|
+
Another skill may start this skill using the environment's supported skill mechanism, or by loading this SKILL.md directly. It may supply the initial business ask, source material, relevant context and user-confirmed answers already collected. This does not require a separate agent or change the model.
|
|
28
|
+
|
|
29
|
+
Once started, **this skill conducts the intake directly with the user**. Ask the user for missing business information, challenge vague answers and clarify ambiguities through the normal workflow below. Do not ask the calling skill to supply the answers or route questions back to it. Do not run the interview as a background or non-interactive task. The calling skill's context is a starting point, not a substitute for user input.
|
|
30
|
+
|
|
31
|
+
Reuse facts and answers the user has already confirmed; do not restart the interview unnecessarily. Keep the caller's unverified assumptions separate from confirmed user decisions. If the supplied information already settles a question, do not ask it again just to demonstrate interaction.
|
|
32
|
+
|
|
33
|
+
Show the final Business Request to the user and follow the normal approval and creation workflow. Carry forward any valid approval of the exact same fields and operation; obtain approval if the draft materially changes. Report the resulting Business Request ID and URL to the user. Starting this skill does not automatically start analysis or resume further actions from the calling skill.
|
|
34
|
+
|
|
35
|
+
## Workflow
|
|
36
|
+
|
|
37
|
+
### 1. Read and establish the starting point
|
|
38
|
+
|
|
39
|
+
Read the request and supplied context. Extract the intended users, concrete operations, information involved, business flow, rules, relevant cases, boundaries, requested deliverables, approval conditions and supplied constraints. Record a named decision owner or success criteria if available, without making their absence a gap in business completeness. Identify conflicts and assumptions without resolving them yourself.
|
|
40
|
+
|
|
41
|
+
Check Business Request duplicates by meaning:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
python3 <ado> backlog --types br --include-removed
|
|
45
|
+
python3 <ado> search "<business terms>" --types br
|
|
46
|
+
python3 <ado> get <candidate Business Request ids>
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Use full Business Request descriptions where summaries are insufficient. Similar words are not enough: compare audience, capability and scope. Show any meaningful overlap and its state. Ask whether to request a revision of the existing Business Request, keep a separate request with an explicit distinction, or stop. For an agreed revision, hand off the requested change and confirmed answers to `update-business-request`, which checks lifecycle eligibility and shared impact; do not edit the existing Business Request directly from this intake. Do not silently merge or reopen requests. If access fails, disclose that duplicate checking is incomplete rather than claiming no duplicates exist.
|
|
50
|
+
|
|
51
|
+
**Done when:** the request's elements are extracted, and every candidate duplicate Business Request is compared by meaning or the incomplete duplicate check is disclosed.
|
|
52
|
+
|
|
53
|
+
### 2. Share the diagnosis
|
|
54
|
+
|
|
55
|
+
Give a concise account of:
|
|
56
|
+
|
|
57
|
+
- what the business appears to be asking for;
|
|
58
|
+
- what is already established, with sources;
|
|
59
|
+
- the highest-impact gaps or contradictions;
|
|
60
|
+
- the next decisions needed.
|
|
61
|
+
|
|
62
|
+
Use the quality gates below as a working record, marking each **confirmed**, **open** or **conflicting** with a brief reason. A gate is confirmed by evidence in the context or by a substantive answer, not by the fact that a question was asked. Show the unresolved gates after significant rounds; do not repeat the whole record every turn.
|
|
63
|
+
|
|
64
|
+
**Done when:** the user has seen the diagnosis, and the working record marks each gate confirmed, open or conflicting.
|
|
65
|
+
|
|
66
|
+
### 3. Interview in focused rounds
|
|
67
|
+
|
|
68
|
+
Start with the gaps that change the meaning or boundaries of the request. Usually settle audience and core capability, then clarify the information involved, expected flow, permissions and meaningful variants or exceptions. Ask one to three related questions at a time; avoid mixing unrelated decisions in one question.
|
|
69
|
+
|
|
70
|
+
Use the environment's available question tool when helpful, otherwise ask in chat. Offer choices only when the context supports them, and let the user answer freely. Do not make up options that quietly add requirements. Each question must be understandable on its own.
|
|
71
|
+
|
|
72
|
+
For each answer:
|
|
73
|
+
|
|
74
|
+
1. Check whether it actually resolves the uncertainty.
|
|
75
|
+
2. If it is vague, name the missing decision and ask a concrete follow-up. For example, “easy to use” does not say what the user must be able to do.
|
|
76
|
+
3. Walk through realistic business scenarios to test the intended behavior, including relevant alternative or exception paths. A single happy-path example is insufficient when other cases in the request admit different interpretations. Avoid speculative technical edge cases.
|
|
77
|
+
4. If it conflicts with another answer or source, show the conflict and ask which rule applies.
|
|
78
|
+
5. Restate the resulting decision briefly and update the working record.
|
|
79
|
+
|
|
80
|
+
Do not ask again for facts already established. If the user cannot answer, identify the specific missing business decision and, if known, who could settle it; do not keep rephrasing the same question. Explain the effect of leaving it open.
|
|
81
|
+
|
|
82
|
+
Read `references/intake-guide.md` for gate-specific probes, weak-answer examples and stopping criteria.
|
|
83
|
+
|
|
84
|
+
**Done when:** no answer from the round is vague, conflicting or missing from the working record.
|
|
85
|
+
|
|
86
|
+
### 4. Verify the quality gates
|
|
87
|
+
|
|
88
|
+
A Business Request is ready for normal creation when the relevant business dimensions below are clear. Apply them to the request rather than requiring irrelevant detail or mechanically filling a form:
|
|
89
|
+
|
|
90
|
+
1. **Actors and scope of responsibility.** Who uses the capability, on whose behalf, and which people, facilities or business contexts they can act on. Distinguish roles when their behavior or access differs.
|
|
91
|
+
2. **Operations and information.** What each actor must be able to do and which business information they need to enter, view or change. Clarify ambiguous verbs such as “manage”, “monitor” and “share”. Where material, settle required information, business meanings, allowed values and defaults. Capture business concepts, not database schemas.
|
|
92
|
+
3. **Flow and expected behavior.** When the activity starts, what the user does, how it progresses and what result they expect. Explain business statuses, transitions, responsibilities and notifications only where relevant. Resolve questions such as who may change a status or what another actor sees after the change.
|
|
93
|
+
4. **Rules, variants and exceptions.** Permissions, visibility, business constraints and meaningful alternative cases are explicit. Resolve contradictions. An unanswered question blocks normal completion if different answers would materially change scope or behavior; do not invent rules to fill gaps.
|
|
94
|
+
5. **Boundaries and concrete examples.** Included capabilities and material scope boundaries are clear, with representative examples where wording alone could be misread. Cover the main flow and any relevant variants. Only record exclusions confirmed by the user; do not invent adjacent requirements to interrogate them about.
|
|
95
|
+
6. **Requested deliverables and approval conditions.** Preserve intermediate deliverables and sequencing explicitly requested by the customer, such as a mockup approved before implementation. Clarify what must be delivered, what the approval covers, the approving role and which work depends on it. A mockup validates the intended final result before implementation; it does not replace a complete description of the desired behavior or defer material business decisions from intake.
|
|
96
|
+
|
|
97
|
+
Before previewing, read the draft as the PO receiving it without the conversation. For each capability, ask: “What would I still need to ask the business before I can understand and analyze this?” If that question exposes an ambiguity in meaning, information, behavior or rules, return to the user with a targeted question. If two plausible business interpretations remain, show them and ask which is intended. Do not choose the more likely one silently.
|
|
98
|
+
|
|
99
|
+
Record all material answers in the Business Request, including examples and rules discovered during follow-ups. A terse request plus a long, discarded interview is not a complete handoff. Formal success criteria, KPIs and a named decider are not readiness gates. Backlog decomposition remains for `analyze-business-request`; technical design is outside this skill's scope and is managed separately.
|
|
100
|
+
|
|
101
|
+
A specific Target Date is still needed to satisfy the configured Azure field requirement. Treat it as administrative business input, distinguish a desired date from a fixed deadline when relevant, and never imply a delivery commitment. Do not demand an ROI calculation, implementation inventory, detailed UI specification, estimate or sprint plan.
|
|
102
|
+
|
|
103
|
+
**Done when:** every relevant gate is confirmed, or the user stops and the open decisions are named.
|
|
104
|
+
|
|
105
|
+
### Business ratings
|
|
106
|
+
|
|
107
|
+
For every Business Request, ask the user for two independent ratings and record the confirmed numbers:
|
|
108
|
+
|
|
109
|
+
- **Business Value**: how valuable the requested capability is to the business, from **1 (minimum)** to **5 (maximum)**.
|
|
110
|
+
- **Urgency**: how urgent the requested capability is for the business, from **1 (minimum)** to **5 (maximum)**.
|
|
111
|
+
|
|
112
|
+
These are business judgments, not AI estimates. One may be high while the other is low. Do not infer Urgency from Target Date or use Priority as a substitute. Reuse scores already explicitly supplied; if missing, ask both in one concise question. Include both in the exact field preview. The helper requires both for a new Business Request, including an explicitly incomplete draft; do not invent defaults. Existing Business Requests without scores need a business answer before their linked Features can be scored reliably.
|
|
113
|
+
|
|
114
|
+
During an authorized Business Request revision through `update-business-request`, the helper recalculates the separate maxima on linked Features only in New or Planned. Ratings on Committed, In Progress, Resolved, Done or Removed Features stay unchanged. Report any missing linked-Business Request scores or frozen Features returned by the helper; do not silently treat missing scores as 1. When the Human Backlog Config names a `ratingsPipelineUrl`, that pipeline also reconciles eligible Features on its schedule, covering manual Azure changes. Do not inspect Feature content yourself as part of this creation skill.
|
|
115
|
+
|
|
116
|
+
**Done when:** the user has given both ratings as integers from 1 to 5.
|
|
117
|
+
|
|
118
|
+
### 5. Preview and approve
|
|
119
|
+
|
|
120
|
+
Show the exact fields to save, then briefly state whether the gates are met and which nearby topics were excluded. Let the user correct the draft and obtain approval before writing.
|
|
121
|
+
|
|
122
|
+
If the user wants to stop before the gates are met, provide the current draft and the specific unresolved decisions. Do not call it ready and do not create it automatically. If they explicitly ask to save an incomplete Business Request, honor that instruction: show the gaps in an **Open questions** section, obtain approval of that exact draft, and create it; like every new Business Request, it starts in Received. Azure-required fields still need real values; never invent a date or other required value to bypass validation. Missing optional ownership or success criteria does not make the draft incomplete. A draft with only nonblocking implementation questions can pass: the gates concern business intent, not technical completeness.
|
|
123
|
+
|
|
124
|
+
**Done when:** the user approves the exact fields, or stops and has the draft with its open decisions.
|
|
125
|
+
|
|
126
|
+
### 6. Create the approved Business Request
|
|
127
|
+
|
|
128
|
+
Write the approved fields to a JSON file without a State field, validate, create, then read the item back:
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
python3 <ado> create --type br --json /tmp/br.json --dry-run
|
|
132
|
+
python3 <ado> create --type br --json /tmp/br.json
|
|
133
|
+
python3 <ado> get <new id>
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Received is the initial Human State of a Business Request, so the new item reads back `"state": "Received"`. Later Human States belong to `analyze-business-request`, `plan-sprint`, `update-business-request` and `write-backlog`, through `set-state`. Report the new Business Request's ID and URL and any intentionally unresolved questions. Suggest `analyze-business-request` for subsequent analysis. Existing Business Request revisions belong to `update-business-request`; do not bypass its state and sharing checks with a direct `update`.
|
|
137
|
+
|
|
138
|
+
**Done when:** `get` reads the new Business Request back in Received, and the user has its ID and URL.
|
|
139
|
+
|
|
140
|
+
## What stays out
|
|
141
|
+
|
|
142
|
+
- **Anything outside the topic**, even when the context talks about it.
|
|
143
|
+
- **Implementation inventory and delivery coverage.** Do not investigate the existing product or compare backlog coverage. The current business process, vocabulary or an example may be clarified when necessary to understand the request; record relevant supplied assets in Context. Technical comparison with what exists belongs to `analyze-business-request`.
|
|
144
|
+
- **Unconfirmed solution proposals and agent-selected technology.** If someone suggests a solution, capture the need behind it: "maybe Azure AI Search" becomes "Employees find a document by describing it". When it is unclear whether a named technology or platform is a suggestion or a requirement, ask. Preserve confirmed customer constraints in Context, with their reason when available; for example, publication on the customer's existing WordPress site.
|
|
145
|
+
- **Implementation estimates, sprint plans, staffing and agent-designed delivery phases.** Preserve customer-requested deliverables, sequencing and approval conditions; they are part of the request.
|
|
146
|
+
- **Internal codes** (use-case numbers, requirement IDs, slide numbers) in the business narrative. Keep useful source identifiers and references in Context, with enough detail to locate the material and distinguish its version or approval scope.
|
|
147
|
+
- **Anything invented.** Every sentence comes from the user or the context. If you believe something but nobody confirmed it, ask.
|
|
148
|
+
|
|
149
|
+
## How to write
|
|
150
|
+
|
|
151
|
+
Make the Business Request easy to scan, with a concise summary and enough detail for the PO to understand it independently. There is no one-minute reading limit; clarity and business completeness take priority over brevity.
|
|
152
|
+
|
|
153
|
+
- Short sentences, one idea each, active voice.
|
|
154
|
+
- Everyday words, and the names the business uses.
|
|
155
|
+
- Say each thing once.
|
|
156
|
+
- No filler or selling words (ensure, enable, leverage, seamless, robust, key). No em dashes.
|
|
157
|
+
- Keep lists short. If the request mixes independent business outcomes, propose a split and explain the boundary; do not split solely because of the number of bullets.
|
|
158
|
+
|
|
159
|
+
## Fields
|
|
160
|
+
|
|
161
|
+
Azure DevOps requires Title, Description, Context and Existing Assets, Target Date, Business Value and Urgency. Existing Business Requests with blank ratings must have both filled on their next save. Fill Requester and Request Date when known (Request Date is the date of the call or email, otherwise today). Collect Business Value and Urgency directly from the user as integers from 1 to 5 before normal creation; never assign them yourself or derive them from Priority or Target Date. Set Priority only if the business said so. Never set Start Date, Iteration, Assigned To or State.
|
|
162
|
+
|
|
163
|
+
Rich-text fields accept a small Markdown subset (`##` headings, `-` and `1.` lists, `**bold**`, blank-line paragraphs). The script converts it to HTML.
|
|
164
|
+
|
|
165
|
+
**Title**: what the business wants, in business words, under about 80 characters, no technology. "Employees find their HR documents in the portal".
|
|
166
|
+
|
|
167
|
+
**Description**
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
## What we want
|
|
171
|
+
One sentence: what the business asks for, and for whom.
|
|
172
|
+
- ‹Who› can ‹do what›.
|
|
173
|
+
- ‹Any intermediate deliverable explicitly requested by the customer›.
|
|
174
|
+
|
|
175
|
+
## Business details
|
|
176
|
+
- ‹For each capability: actor, operation, information involved and expected behavior›.
|
|
177
|
+
|
|
178
|
+
## Flow and cases
|
|
179
|
+
- ‹Main business flow and relevant variants or examples›.
|
|
180
|
+
|
|
181
|
+
## Rules
|
|
182
|
+
- ‹Permissions, business constraints and relevant exceptions›.
|
|
183
|
+
|
|
184
|
+
## Deliverables and approvals
|
|
185
|
+
- ‹Requested deliverable, what must be approved, by which role, and what work depends on it›.
|
|
186
|
+
|
|
187
|
+
## Not included
|
|
188
|
+
- ‹Only what the user excluded›.
|
|
189
|
+
|
|
190
|
+
## People
|
|
191
|
+
- ‹Known name or role›: requester / uses it; decider only if supplied
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
**Success Criteria**: optional. Record explicit criteria when provided or already agreed; do not force a separate acceptance exercise or manufacture KPIs. Expected business behavior belongs in Description even when this field is omitted.
|
|
195
|
+
|
|
196
|
+
Use only relevant Description sections and do not repeat the same detail across them. Put material unresolved business questions under **Open questions** when explicitly saving an incomplete draft.
|
|
197
|
+
|
|
198
|
+
**Context and Existing Assets**
|
|
199
|
+
|
|
200
|
+
```
|
|
201
|
+
## What we know
|
|
202
|
+
- ‹Only what the requester or the context points to: a prototype, a document, an example›.
|
|
203
|
+
If there is nothing, write "Nothing known yet."
|
|
204
|
+
|
|
205
|
+
## Constraints
|
|
206
|
+
- ‹Only constraints the business set›.
|
|
207
|
+
|
|
208
|
+
## Sources and existing approvals
|
|
209
|
+
- ‹Known source reference and date or asset version; for an approval, what it covers›.
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
**Business Value**: JSON `BusinessValue`, numeric integer 1–5, stored in `Custom.BusinessValueScore`.
|
|
213
|
+
|
|
214
|
+
**Urgency**: JSON `Urgency`, numeric integer 1–5, stored in `Custom.Urgency`.
|
|
215
|
+
|
|
216
|
+
**Requester**: the person's email (preferred), or "Display Name <email>". **Request Date** and **Target Date**: `YYYY-MM-DD`.
|
|
217
|
+
|
|
218
|
+
For a worked example of substantive follow-ups and a final Business Request, read `references/example.md`.
|
|
219
|
+
|
|
220
|
+
## The helper script
|
|
221
|
+
|
|
222
|
+
`<ado>` is `../human-backlog-ado/scripts/ado.py` relative to this skill's directory. When it stops on the Human Backlog Config or on Azure CLI sign-in, follow `../human-backlog-ado/SKILL.md`.
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
python3 <ado> whoami # check access
|
|
226
|
+
python3 <ado> backlog --types br --include-removed
|
|
227
|
+
python3 <ado> search "onboarding documents" --types br
|
|
228
|
+
python3 <ado> get 123 # an item with its links
|
|
229
|
+
python3 <ado> create --type br --json FILE [--dry-run]
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Field names in the JSON: `Title`, `Description`, `SuccessCriteria`, `Context`, `Requester`, `RequestDate`, `TargetDate`, `BusinessValue`, `Urgency`, and optionally `Priority`, `Tags`.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# Worked example: HR documents
|
|
2
|
+
|
|
3
|
+
## Input
|
|
4
|
+
|
|
5
|
+
Sentence: "HR documents section in the portal"
|
|
6
|
+
|
|
7
|
+
Context, call notes from 14 October:
|
|
8
|
+
|
|
9
|
+
> Call with HR, 14 October. Present: Marta Rossi (HR Director), Luca Bianchi (Internal Comms), Paolo (dev).
|
|
10
|
+
>
|
|
11
|
+
> - Employees cannot find documents: policies, procedures, forms. They are spread across email, shared folders and SharePoint.
|
|
12
|
+
> - An HR SharePoint site already exists, with documents grouped by topic (onboarding, leave, safety, benefits) and permissions by role: managers also see the evaluation procedures.
|
|
13
|
+
> - They would like a "Documents" section in the company portal where each person sees only what is relevant to their role.
|
|
14
|
+
> - Luca: an AI search engine would be nice, maybe Azure AI Search.
|
|
15
|
+
> - Marta: HR gets about 200 requests a month like "where do I find form X?".
|
|
16
|
+
> - It must be ready for the January onboarding: 40 new hires.
|
|
17
|
+
> - Paolo: with the Graph API it takes us 2 sprints.
|
|
18
|
+
> - Documents only in Italian and English.
|
|
19
|
+
> - Employee uploads are not needed.
|
|
20
|
+
> - The new internal communications intranet also came up.
|
|
21
|
+
|
|
22
|
+
## Starting diagnosis
|
|
23
|
+
|
|
24
|
+
The duplicate check reads only Business Requests. In this example no overlapping Business Request is found; no implementation backlog is inspected.
|
|
25
|
+
|
|
26
|
+
> The request is about consulting HR documents in the portal. The notes confirm the languages, visibility by role and no employee uploads.
|
|
27
|
+
>
|
|
28
|
+
> Still ambiguous: what consulting includes, what “AI” search means, which results a person must see and how permissions apply. I will clarify these points before handing the request to the PO.
|
|
29
|
+
|
|
30
|
+
A named decider and a numerical reduction in HR calls are not prerequisites. The gap is the meaning and detail of the requested behavior.
|
|
31
|
+
|
|
32
|
+
## Round 1: clarify operations and scope
|
|
33
|
+
|
|
34
|
+
1. “How should an employee consult documents: by topic, by search, or both?” → “Both. They must be able to open the document and download it.”
|
|
35
|
+
2. “When Luca talks about AI search, what must a person be able to type, and what do they expect to get?” → “It must be smart.”
|
|
36
|
+
3. “The notes exclude employee uploads. Does this request include other document operations besides consulting and downloading?” → “No. Editing and publishing are out too.”
|
|
37
|
+
|
|
38
|
+
Do not accept “smart” as a clear requirement. Record the confirmed operations and exclusions; continue on the ambiguous behavior.
|
|
39
|
+
|
|
40
|
+
## Round 2: make the behavior concrete
|
|
41
|
+
|
|
42
|
+
1. “Give me a real example of what a new hire would type and what they should find.” → “They type ‘how do I request leave?’ and must find the current leave form and the procedure to fill it in.”
|
|
43
|
+
2. “Should the person get a written answer to the question, or a list of relevant documents to open?” → “A list of documents, not a generated answer.”
|
|
44
|
+
3. “What information must they see to recognize the right document in the list?” → “Title, document type and last update date.”
|
|
45
|
+
|
|
46
|
+
The distinction between document retrieval and generated answers changes the business scope. Save it in the Business Request; do not leave it only in the chat. Do not select a search engine or technical architecture.
|
|
47
|
+
|
|
48
|
+
## Round 3: clarify variants and rules
|
|
49
|
+
|
|
50
|
+
1. “An employee searches for an evaluation procedure reserved for managers. Should they see its title without being able to open it, or see no restricted result at all?” → “Not even the title may appear. The same applies when browsing by topic.”
|
|
51
|
+
2. “For a document with several versions, what should the employee find and download?” → “Only the current version. The history is not part of this request.”
|
|
52
|
+
3. “If no accessible document matches the search, what should the person see?” → “That there are no results. They must get no information about restricted documents.”
|
|
53
|
+
|
|
54
|
+
These are relevant business variants, not speculative technical error handling. Their answers resolve plausible alternative interpretations.
|
|
55
|
+
|
|
56
|
+
## Administrative completion
|
|
57
|
+
|
|
58
|
+
The source says January but Azure requires a specific Target Date. Ask for it; the user confirms 11 January 2027, before the new hires start. This records a requested deadline, not a delivery promise. Do not hold up a detailed request to obtain a decision owner or KPI.
|
|
59
|
+
|
|
60
|
+
## Business ratings
|
|
61
|
+
|
|
62
|
+
Ask: “From 1 (minimum) to 5 (maximum), what values do you give business value and urgency? They are two separate ratings.” The user answers: “Value 4, urgency 3.” Record those numbers without inferring either from the January deadline.
|
|
63
|
+
|
|
64
|
+
## Resulting Business Request preview
|
|
65
|
+
|
|
66
|
+
**Title:** Employees find and consult their HR documents in the portal
|
|
67
|
+
|
|
68
|
+
**Request Date:** 2026-10-14 · **Target Date:** 2027-01-11
|
|
69
|
+
|
|
70
|
+
**Business Value:** 4 · **Urgency:** 3
|
|
71
|
+
|
|
72
|
+
**Description**
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
## What we want
|
|
76
|
+
Employees find, open and download the HR policies, procedures and forms relevant to their role in the portal.
|
|
77
|
+
|
|
78
|
+
## Business details
|
|
79
|
+
- Employees browse documents by topic or search by describing what they need, without knowing the document title.
|
|
80
|
+
- Search returns a list of relevant documents to open. It does not generate an answer to the employee's question.
|
|
81
|
+
- Each result shows the title, document type and last update date.
|
|
82
|
+
- Employees find, open and download only the current version of a document.
|
|
83
|
+
|
|
84
|
+
## Flow and cases
|
|
85
|
+
- A new hire searches for “how do I request leave?” and finds the current leave request form and the procedure for completing it.
|
|
86
|
+
- If there are no relevant documents accessible to the employee, search shows no results and discloses no information about restricted documents.
|
|
87
|
+
|
|
88
|
+
## Rules
|
|
89
|
+
- Browsing and search show only documents accessible to the employee's role.
|
|
90
|
+
- Managers can also access evaluation procedures. Other employees cannot see those documents or their titles in browsing or search.
|
|
91
|
+
|
|
92
|
+
## Not included
|
|
93
|
+
- Employee uploads, editing or publication of documents.
|
|
94
|
+
- Generated answers to employee questions.
|
|
95
|
+
- Access to historical document versions.
|
|
96
|
+
|
|
97
|
+
## People
|
|
98
|
+
- Employees, managers and new hires use the capability.
|
|
99
|
+
- Marta Rossi (HR Director) supplied the request.
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
**Context and Existing Assets**
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
## What we know
|
|
106
|
+
- Marta mentioned an HR SharePoint site with documents grouped by topic and permissions by role.
|
|
107
|
+
- HR expects fewer document-related calls.
|
|
108
|
+
|
|
109
|
+
## Constraints
|
|
110
|
+
- Documents exist only in Italian and English.
|
|
111
|
+
- The requested date is 11 January 2027, before the new hires start.
|
|
112
|
+
|
|
113
|
+
## Sources and existing approvals
|
|
114
|
+
- HR call notes from 14 October 2026, supplemented by the answers confirmed during intake and recorded in this Business Request.
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Requester identity, decision owner and Success Criteria are omitted when not supplied. The expected behavior is already documented in Description. Do not invent an email, appoint Marta as decider or convert “fewer calls” into a numerical condition.
|
|
118
|
+
|
|
119
|
+
The preview identifies the excluded nearby topic (the intranet) and discarded implementation proposals and estimate. After checking that the PO can understand the request without the conversation, obtain approval of the exact fields before validation and creation.
|
|
120
|
+
|
|
121
|
+
## If the user stops early
|
|
122
|
+
|
|
123
|
+
After round 1, “no more questions” ends the interview. Return the current draft and identify the unresolved meaning of search and the relevant visibility questions. Do not present it as ready. If the user explicitly requests saving anyway, show those business gaps under Open questions and obtain approval of that exact draft. Missing a decider or formal success criteria alone does not require this incomplete-draft path.
|
|
124
|
+
|
|
125
|
+
## Focused example: landing page, mockup and publication constraint
|
|
126
|
+
|
|
127
|
+
The Business Request already records the complete agreed audience, content, actions and rules for a landing page. The customer also supplies these requirements during intake:
|
|
128
|
+
|
|
129
|
+
> We want to see the desktop and mobile mockup of the agreed page before development. Marketing approves the layout and visual presentation. The page must be published on our existing WordPress site. The attached brand guide, version 3, is already approved for colors and typography.
|
|
130
|
+
|
|
131
|
+
If any of these conditions is ambiguous, ask a targeted follow-up. Once confirmed, preserve them alongside the full functional request. The following excerpts illustrate only the deliverable and constraint handling; they are not a complete Business Request:
|
|
132
|
+
|
|
133
|
+
**Description**
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
## What we want
|
|
137
|
+
- The customer receives a desktop and mobile mockup of the agreed landing page before implementation.
|
|
138
|
+
|
|
139
|
+
## Deliverables and approvals
|
|
140
|
+
- Marketing approves the layout and visual presentation shown in the mockup before implementation starts.
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**Context and Existing Assets**
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
## Constraints
|
|
147
|
+
- The landing page must be published on the customer's existing WordPress site.
|
|
148
|
+
|
|
149
|
+
## Sources and existing approvals
|
|
150
|
+
- Attached brand guide, version 3. The customer confirms that its colors and typography are approved.
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Keep the mockup requirement even though it establishes a sequence. Keep WordPress because the customer requires it. The brand approval covers colors and typography; it does not establish approval of the landing page's layout or behavior. The mockup validates the concrete presentation of the already-defined result. It does not make an otherwise incomplete functional request ready.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Business detail interview guide
|
|
2
|
+
|
|
3
|
+
The PO should receive a self-contained request with clear business meaning, operations, information and rules. Use the dimensions in SKILL.md to find gaps, not as a questionnaire to recite. Do not spend rounds obtaining a decider or formal success criteria when the actual request is already clear.
|
|
4
|
+
|
|
5
|
+
## Replace vague verbs with business operations
|
|
6
|
+
|
|
7
|
+
“Directors manage actions” can mean creating, assigning, editing, closing, deleting or only viewing them. Ask what “manage” includes in this request. Where responsibilities differ, ask which role performs each operation. Do not assume every CRUD operation is needed or offer capabilities unsupported by the context.
|
|
8
|
+
|
|
9
|
+
“Everyone has access” leaves the population and visibility unclear. If the context mentions facilities, clarify whether actors work on their own facility or across facilities.
|
|
10
|
+
|
|
11
|
+
## Clarify business information
|
|
12
|
+
|
|
13
|
+
For each requested operation, ask what information the actor needs to provide or see where that is material to the request. Reuse real examples supplied by the user.
|
|
14
|
+
|
|
15
|
+
For an action with a priority and due date, business ambiguities might be which priorities exist, whether either value is required and who can change them. Do not ask for storage types, field lengths or a database model. Do not blindly ask about every possible field: follow the actual information named by the business.
|
|
16
|
+
|
|
17
|
+
If a term admits different meanings, show the interpretations: “Does due date mean the last day to complete the action, or the day to start it?” Ask only when the meaning is genuinely unclear in context.
|
|
18
|
+
|
|
19
|
+
## Walk through behavior and variations
|
|
20
|
+
|
|
21
|
+
Start with a concrete case: actor, starting situation, operation and expected result. Then probe relevant variations implied by the request. If reassignment is requested, clarify the effect on responsibility and visibility. If statuses are requested, clarify their meanings and who changes them. If notifications are requested, clarify recipient, trigger and useful business content; leave transport and architecture to later analysis.
|
|
22
|
+
|
|
23
|
+
Expected behavior is essential; a separately named acceptance criterion is not. “Smart search” needs a real query and the expected kind of result, not a KPI workshop.
|
|
24
|
+
|
|
25
|
+
## Expose rules and contradictions
|
|
26
|
+
|
|
27
|
+
“Usual permissions” is not a usable rule. Ask the user to state the permissions relevant to the request. If a director sees only their own facility but a later answer says every director can edit every action, show the conflict and ask which rule applies.
|
|
28
|
+
|
|
29
|
+
Discuss business exceptions that are supplied or directly relevant. Avoid a speculative catalogue of failure modes, infrastructure errors and technical retries.
|
|
30
|
+
|
|
31
|
+
## Settle scope without expanding it
|
|
32
|
+
|
|
33
|
+
Ask about an adjacent capability only when the supplied context makes its inclusion ambiguous. Do not add exports, dashboards, notifications or approvals merely because similar products have them.
|
|
34
|
+
|
|
35
|
+
Separate independent business outcomes when useful and let the user decide whether to split. Do not use a fixed number of bullets or document length as evidence that the request is too big.
|
|
36
|
+
|
|
37
|
+
## Optional context and required date
|
|
38
|
+
|
|
39
|
+
Record a requester, named decision owner, success measure or business benefit when supplied. Their absence alone is not a business-completeness blocker. If the customer explicitly conditions work on an approval, clarify the approving role and approval scope as part of that condition. Do not require a quantitative goal, nominate an owner or invent a threshold.
|
|
40
|
+
|
|
41
|
+
Target Date remains required by the Azure configuration. Ask for a real desired date if missing. Do not select the first or last day of a vague month yourself or promise delivery on that date.
|
|
42
|
+
|
|
43
|
+
## Preserve requested deliverables and constraints
|
|
44
|
+
|
|
45
|
+
“We want to approve a mockup before implementation” is part of the customer request. Clarify what the mockup must represent, what approval covers, which role approves it and what work must wait. The desired final behavior must already be clear in the Business Request. Do not treat the mockup as permission to postpone business completeness or ask the customer to design an internal delivery plan.
|
|
46
|
+
|
|
47
|
+
Distinguish a suggested tool from a mandatory constraint. “Maybe WordPress” is a proposal to clarify when material; “publish on our existing WordPress site” may be a requirement. Confirm the distinction if unclear, and preserve a confirmed requirement and its supplied rationale in Context. Do not silently discard it when translating the request into business language.
|
|
48
|
+
|
|
49
|
+
Record source references and known dates or asset versions available during intake. If a prototype was approved, establish whether that approval covers layout, content, behavior or another stated aspect. Preserve that scope without extending it. Do not require source metadata that the user does not have or an ongoing history of later customer discussions.
|
|
50
|
+
|
|
51
|
+
## PO handoff check
|
|
52
|
+
|
|
53
|
+
Read the draft without relying on chat history:
|
|
54
|
+
|
|
55
|
+
- Can the PO identify actors, requested operations and information involved?
|
|
56
|
+
- Are the flow, relevant rules and business variants understandable?
|
|
57
|
+
- Are requested deliverables, approval dependencies and mandatory customer constraints preserved?
|
|
58
|
+
- Can the PO identify the relevant sources and the scope of any existing approval?
|
|
59
|
+
- Would two reasonable readers infer materially different behavior anywhere?
|
|
60
|
+
- Are substantive answers and examples actually recorded in the Business Request?
|
|
61
|
+
|
|
62
|
+
If a material business ambiguity remains, ask about it. If the only open questions concern implementation or decomposition, hand off to analyze-business-request for backlog mapping; technical design is outside this skill's scope and is managed separately. Do not reopen optional ownership or success measurement just to fill a template. Subsequent refinements and offline customer clarifications can be reflected directly in Features and PBIs without updating the original Business Request.
|
|
63
|
+
|
|
64
|
+
If the user cannot answer or stops, state the precise missing business decisions. Save incomplete work only on an explicit request with those gaps visible and Azure-required fields supplied. Missing optional fields alone does not make a Business Request incomplete.
|
|
65
|
+
|
|
66
|
+
## Business ratings
|
|
67
|
+
|
|
68
|
+
Before creating, collect Business Value and Urgency from the user, each an integer from 1 (minimum) to 5 (maximum). Ask for the two numbers together where practical. These prioritization inputs do not replace the business-detail interview. Do not demand a KPI or ROI to justify them and do not choose scores for the user. A concrete requested date is a separate input from subjective urgency.
|