@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 CHANGED
@@ -1,3 +1,106 @@
1
- # Temporary Holding Version
1
+ # @collective-intelligence/backlog
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Agent skills for a Human Backlog: the Azure DevOps project where non-technical
4
+ client stakeholders ask for work and follow it. The skills ship as plain
5
+ folders under `skills/`. Install them beside each other, because each skill
6
+ calls the helper as `../human-backlog-ado/scripts/ado.py`.
7
+
8
+ ## Install
9
+
10
+ In a Harness Intelligence repo that depends on the Collective Intelligence SDK,
11
+ `hi update` installs the seven skills through the `ci-solutions` Pack.
12
+
13
+ Anywhere else, install the package and copy its skill folders into your agent's
14
+ skills directory:
15
+
16
+ ```sh
17
+ npm install @collective-intelligence/backlog
18
+ cp -R node_modules/@collective-intelligence/backlog/skills/* .agents/skills/
19
+ ```
20
+
21
+ The skills need Python 3 and the Azure CLI.
22
+
23
+ ## Skills
24
+
25
+ | Skill | Use |
26
+ | -------------------------- | ---------------------------------------------------------------- |
27
+ | `create-business-request` | Interview the business and create a new Business Request |
28
+ | `analyze-business-request` | Map a Business Request to Epics, Features and PBIs |
29
+ | `update-business-request` | Revise a Business Request and its uncommitted backlog |
30
+ | `plan-sprint` | Plan a two-week sprint of whole Features per developer |
31
+ | `create-bug` | Turn a business user's problem report into a Bug |
32
+ | `setup-human-backlog` | Write and prove the Human Backlog Config; Eject a client zip |
33
+ | `human-backlog-ado` | Reference for `scripts/ado.py`, the helper the other skills call |
34
+
35
+ ## Human Backlog Config
36
+
37
+ `ado.py` reads four values. For each value the first source wins:
38
+
39
+ 1. the `ADO_*` env var: `ADO_PROVIDER`, `ADO_PROJECT_URL`, `ADO_TENANT` and
40
+ `ADO_RATINGS_PIPELINE_URL`;
41
+ 2. `humanBacklog` in the nearest `.devpunks/settings.json` above the working
42
+ directory;
43
+ 3. `config.json` beside `ado.py`, which an Eject writes.
44
+
45
+ ```json
46
+ {
47
+ "humanBacklog": {
48
+ "provider": "azure-devops",
49
+ "projectUrl": "https://dev.azure.com/<org>/<project>",
50
+ "tenant": "<Entra tenant ID>",
51
+ "ratingsPipelineUrl": "<optional pipeline URL>"
52
+ }
53
+ }
54
+ ```
55
+
56
+ `config.json` holds the same keys without the `humanBacklog` wrapper.
57
+
58
+ ## Sign in
59
+
60
+ `ado.py` gets its token only from the Azure CLI, for the configured tenant.
61
+ Sign in once per machine:
62
+
63
+ ```sh
64
+ az login --tenant <tenant>
65
+ python3 skills/human-backlog-ado/scripts/ado.py whoami
66
+ ```
67
+
68
+ ## Set up and Eject
69
+
70
+ Run the `setup-human-backlog` skill once per project. It interviews for the
71
+ Human Backlog Config, writes `humanBacklog` into `.devpunks/settings.json` and
72
+ runs the read-only `ado.py doctor`. `doctor` reports `ready` when the config,
73
+ the sign-in, the project, the work-item types, fields, states, iterations and
74
+ one `validateOnly` create per type all pass; otherwise `blocked` with every
75
+ mismatch. The team creates the Azure DevOps process by hand from
76
+ `skills/setup-human-backlog/references/process.md`.
77
+
78
+ On request, the skill runs `ado.py eject --out PATH`: one zip of the seven
79
+ skills, the resolved config as `human-backlog-ado/scripts/config.json` and a
80
+ `MANIFEST.json` with the package name, a skill-tree sha256, a config sha256 and
81
+ the date. A client runs the zip outside Harness Intelligence.
82
+
83
+ ## Human States
84
+
85
+ A Business Request moves through Received, In analysis, Planned, In progress,
86
+ On staging and Live, or ends as Rejected or Withdrawn. `ado.py set-state` is
87
+ the only command that writes the State. It moves forward only, keeps Live,
88
+ Rejected and Withdrawn final, and writes nothing when the state is already set.
89
+
90
+ | Human State | Writer |
91
+ | ----------- | ------------------------------------------------- |
92
+ | Received | `create-business-request` (initial state) |
93
+ | In analysis | `analyze-business-request` at the first Feature |
94
+ | Planned | `plan-sprint` when the first Feature gets sprint |
95
+ | Rejected | a person, or `update-business-request` on request |
96
+ | Withdrawn | a person, or `update-business-request` on request |
97
+
98
+ Harness Intelligence `write-backlog` writes In progress, On staging and Live
99
+ from delivery evidence.
100
+
101
+ ## Test
102
+
103
+ ```sh
104
+ bun run test # ado.py against an in-memory Azure DevOps fake; no network
105
+ bun run test:pack # tarball check, then test, then the Human State Model
106
+ ```
package/package.json CHANGED
@@ -1,6 +1,22 @@
1
1
  {
2
2
  "name": "@collective-intelligence/backlog",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.1",
4
+ "description": "Human Backlog agent skills and the ado.py Azure DevOps helper: Business Request intake, analysis and revision, sprint planning and Bug intake.",
5
+ "files": [
6
+ "README.md",
7
+ "skills"
8
+ ],
9
+ "scripts": {
10
+ "test": "python3 -m unittest discover -s tests",
11
+ "test:pack": "python3 tools/check-pack.py && bun run test && bun run check:models",
12
+ "check:models": "tsprover",
13
+ "type-check": "bun check"
14
+ },
15
+ "devDependencies": {
16
+ "tsprover": "0.0.2"
17
+ },
18
+ "publishConfig": {
19
+ "access": "public"
20
+ },
21
+ "gitHead": "a2aa507323bc6d3ce0ef6d3e460f28573ef40dd8"
22
+ }
@@ -0,0 +1,193 @@
1
+ ---
2
+ name: analyze-business-request
3
+ description: Analysis of an existing Business Request into Human Backlog Epics, Features and PBIs in Azure DevOps. Finds existing coverage, extends eligible Features, creates the missing items and links them to the Business Request without changing it. Use to refine, decompose or check the backlog coverage of an existing Business Request; use create-business-request for a new business ask.
4
+ ---
5
+
6
+ # Analyze a Business Request into a backlog
7
+
8
+ The goal is a backlog that speaks for itself: every requested capability or deliverable is traced to an existing, extended or new Feature, applicable rules and constraints are preserved, and new Features are broken into functional PBIs. This is the consultants' backlog. Technical design and implementation work are outside this skill's scope and are managed separately. Do not estimate or schedule the work here. Business Value and Urgency are derived from linked Business Requests, not estimated independently.
9
+
10
+ This is a long, iterative session by design. A wrong "this already exists" or a Feature cut along the wrong line is expensive to undo later, so prefer several short rounds of questions over guessing. The user knows the business; you know the backlog after you've read it — combine the two.
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
+ ## The model
15
+
16
+ - Hierarchy: **Epic → Feature → Product Backlog Item** (Bugs sit at PBI level).
17
+ - A **Business Request** sits at Feature level, next to Features. It never has a parent Epic and never has children.
18
+ - The Business Request is immutable during this analysis: do not change its fields or ratings, and do not post discussion comments on it. It takes exactly two kinds of write: the approved Related links to Features, with their coverage comments, and the move from Received to In analysis in step 8, whose `set-state` comment is the only discussion comment. Record refinements in the backlog, not in the Business Request.
19
+ - Business Request ↔ Feature is a **Related** link with a comment saying what it covers, written in words, since the Business Request itself has no numbers: `Realizes Business Request #123: new hires find onboarding documents; employees find HR documents in one place` for new Features, `Already covers Business Request #123: finding a document by describing it (Done)` for existing ones. Linking existing Features too means the Business Request shows its full coverage at a glance.
20
+ - No Effort, Story Points, Remaining Work, legacy Business Value, Time Criticality, Start or Target Date in the fields you create or update. The plan applier rejects these fields on new items; apply the same restriction when updating existing Features. Preserve customer-supplied timing and approval constraints in the descriptions without turning them into a delivery commitment. The new 1–5 BusinessValue and Urgency on Features are the derived exception described below; do not copy ratings to Epics, PBIs or Bugs. Leave Priority, Assigned To and Iteration alone unless the user asks.
21
+
22
+ ## Business Value and Urgency
23
+
24
+ - Read the Business Request's **BusinessValue** (`Custom.BusinessValueScore`) and **Urgency** (`Custom.Urgency`). Both are integers from 1 (minimum) to 5 (maximum), entered by the business. If either is missing or invalid, report the gap and continue drafting the mapping where possible. Do not edit the Business Request, guess a score, substitute Priority, or derive Urgency from a date. Do not apply operations that require unknown source scores; resolving the source data is outside this analysis workflow.
25
+ - For each new or eligible existing Feature, compute the **maximum of all Related Business Requests**, separately for the two fields. Use every linked Business Request, including Business Requests in terminal states; do not introduce a state filter or use a sum, average, or only the Business Request currently being analyzed. For example, Business Request values 3, 4 and 5 yield Feature Business Value 5; Urgency is calculated independently and may come from a different Business Request.
26
+ - Only **New** and **Planned** Features may have their ratings recalculated. From **Committed** onward, preserve the values, even when a new Business Request is linked or an existing Business Request's ratings change. Removed Features are not eligible either. Related links may still record coverage without changing the frozen ratings or scope.
27
+ - Preview the derived values and contributing Business Requests, or clearly label the Feature as frozen. Do not ask the user to score Features independently. A missing or invalid linked Business Request score means the maximum is unknown; report the gap instead of silently treating it as a low score.
28
+ - Put all intended Business Request ↔ Feature Related links in the apply plan, including links to existing Business Requests. The helper derives initial Feature scores before creating it and reconciles eligible Features after the links are written. Do not use standalone `create --type feature`; use `apply` so that the scores have a recorded Business Request source.
29
+ - Helper `link` commands reconcile linked eligible Features immediately. When the Human Backlog Config names a `ratingsPipelineUrl` (`whoami` prints it), that pipeline also reconciles every New/Planned Feature on its schedule, including manual Azure changes to Business Request ratings or Related links. For an immediate manual reconciliation, run `python3 <ado> sync-ratings --all --dry-run`, review the result, then run without `--dry-run`.
30
+ - Before moving an eligible Feature to Committed through the helper, ratings are reconciled and incomplete source scores block commitment. Azure also makes both rating fields read-only in Committed, In Progress, Resolved, Done and Removed. Do not bypass those rules to apply a higher score later.
31
+
32
+ ## Workflow
33
+
34
+ ### 1. Load the Business Request and read its needs
35
+
36
+ ```bash
37
+ python3 <ado> get <Business Request id>
38
+ ```
39
+
40
+ Stop if the item isn't a Business Request. If it already has Related links, an earlier session refined part of it: show what's linked and treat this as a resume.
41
+
42
+ A Business Request written with `create-business-request` summarizes the request under **What we want**. Extract the requirements from the whole Business Request: **Business details**, **Flow and cases**, **Rules**, **Deliverables and approvals**, **Context and Existing Assets**, and any supplied **Success Criteria**. Read source and approval scope carefully. Include intermediate deliverables, mandatory customer constraints and conditions that must be met before other work starts, even if they appear only outside the summary. Compare this complete request with the backlog to establish what already exists and what must change.
43
+
44
+ Number capabilities and deliverables N1…Nn, and rules, constraints and approval conditions R1…Rn, in the order they appear. Use those temporary identifiers in the coverage matrix and discussion; use words in saved item descriptions and link comments. Every Feature and PBI must respect the requirements that apply to it. An older or hand-written Business Request may need its requests restated as clear capabilities or deliverables before mapping.
45
+
46
+ Confirm the interpretation with the user. The PO/developer may supply clarifications from their knowledge or offline customer discussions. Incorporate confirmed refinements directly into Feature descriptions, acceptance criteria and PBIs; do not update the Business Request or require the conversation to be transcribed there. Distinguish original Business Request statements from later user-confirmed refinements in the discussion. Ask about unresolved meaning rather than inventing a business rule.
47
+
48
+ **Done when:** the item is a Business Request, every need and rule has an N or R number, and the user confirms the interpretation.
49
+
50
+ ### 2. Agree on where to search
51
+
52
+ Ask whether the user wants to point you at specific Epics or Features (IDs or names), or wants you to scan everything. The two combine well:
53
+
54
+ - **Directed**: read the indicated subtrees in depth, PBIs included — `backlog --under <id> --types feature,pbi,bug`.
55
+ - **Automatic**: scan all Epics, Features and Business Requests in every state — `backlog --types epic,feature,br --include-removed`. Use `search "<keywords>"` to narrow a large backlog, but don't rely on keywords alone: match by meaning, since the same capability is often named differently.
56
+
57
+ Also look at other Business Requests: an overlapping Business Request, and the Features already linked to it, may cover your needs.
58
+
59
+ **Done when:** the user has chosen the directed scan, the automatic scan or both, and you have read that whole scope.
60
+
61
+ ### 3. Present the coverage matrix
62
+
63
+ | Need | Candidate | State | Coverage | Evidence |
64
+ | ---- | --------------------------- | ----------------- | -------- | --------------------------------------------------------------------------------- |
65
+ | N3 | Feature #42 Document search | Done (2026-09-12) | partial | keyword search only; the Business Request asks for search in the user's own words |
66
+ | N1 | — | — | none | |
67
+
68
+ Include deliverables as needs. For each rule, constraint and approval condition, identify the affected Features/PBIs and how it will be satisfied. Show gaps and conflicts explicitly; a matching capability title alone does not establish full coverage. The final review must account for these conditions as well as the needs.
69
+
70
+ Call out Done items explicitly — "Feature #42 is already Done and seems to cover N3: is that still true, or is something missing?". Done does not mean the need is satisfied: the Business Request may ask for more than what was delivered.
71
+
72
+ For each need, the decision is one of:
73
+
74
+ - **Link as is** — an existing Feature fully covers it; link it Related.
75
+ - **Extend** — only while an existing Feature is New or Planned. Propose the additional PBIs together with the revised Feature description, scope and acceptance criteria, and any necessary title change. Read the full Feature, its existing PBIs and linked Business Requests so the revision preserves earlier requirements. Show the current scope, proposed change and reason to the user, resolve their feedback, and obtain approval of the final fields before updating. Do not change committed scope; create a separate Feature for additional work from Committed onward.
76
+ - **New Feature** — including the evolution of a Done Feature. Don't reopen a Done Feature unless the user explicitly asks; create a new one that references it.
77
+ - **Out of scope** — not covered now; confirm this decision with the user and state the reason in the final coverage report and affected Feature scope. Leave the Business Request unchanged.
78
+
79
+ **Done when:** every need, rule, constraint and approval condition has a matrix row with a candidate or `none`.
80
+
81
+ ### 4. Resolve doubts in rounds
82
+
83
+ Use the environment's available question tool or chat, with a few related questions per round and concrete options built from what you found. Each question must make sense on its own, as if the user had not read the chat: write the need, the rule or the item in words, never only its number ("N3", "R1", "#42"). Typical questions:
84
+
85
+ - Feature #42 "Document search" is Done. Does it already cover "employees find a document by describing it", or is that a different need?
86
+ - Which Epic should the new Feature live in? Is a new Epic needed?
87
+ - "New hires find their onboarding documents" and "employees find any HR document": one Feature or two?
88
+ - What does the Business Request mean by "…"? The answer changes how Features are split.
89
+ - Extending Feature #55 would change its scope and acceptance criteria as shown. Does the proposed version preserve the existing work and capture the additional request?
90
+
91
+ After each round, show a short decision log (need → decision). Expect several rounds; finish when no decision is open. Don't ask about estimates, dates or assignees — they are outside this skill.
92
+
93
+ **Done when:** the decision log has a decision for every need, and no decision is open.
94
+
95
+ ### 5. Draft the backlog
96
+
97
+ **Epic** — only when no existing Epic fits. A thematic product area that can remain open over time: a noun-phrase title, and a Description with purpose and boundaries.
98
+
99
+ **Feature** — a functionality or concrete project deliverable with a verifiable result, suitable for validation with the business and subsequent sprint planning. Title it by outcome, for example "Role-based HR document library" or "Preliminary landing page mockup".
100
+
101
+ - Description: `## Summary`, `## User value`, `## Scope` (in/out), `## Realizes` (Business Request #id and what it covers, in words), and context pointers carried over from the Business Request. Add `## Dependencies and approvals` when relevant, identifying the prerequisite deliverable or condition and the work that depends on it. Preserve confirmed customer constraints.
102
+ - Acceptance Criteria: observable criteria for the whole Feature, including the approval scope and approving role when required by the customer. Start from the applicable Business Request requirements and user-confirmed refinements.
103
+ - For an approved extension, produce a complete revised description and acceptance criteria that retain the earlier scope and incorporate the agreed addition. Preserve other fields. A collection of new PBIs does not replace updating the parent Feature.
104
+
105
+ **PBI** — a functional portion of a Feature that consultants can take responsibility for, track and verify through acceptance criteria. It may depend on other PBIs and need not be independently releasable or demoable. For a project deliverable, describe a verifiable part of the agreed result. Split where this helps internal delivery and verification; do not create a ticket mechanically for every use case. One PBI may suffice for a small Feature. Use a crisp capability or outcome title; a user-story title is optional. The PBI form has no Acceptance Criteria field, so put them in the Description:
106
+
107
+ ```
108
+ ## Context
109
+ Why this portion exists; relevant existing assets and dependencies.
110
+
111
+ ## Acceptance criteria
112
+ - …
113
+ ```
114
+
115
+ Write every Epic, Feature and PBI in plain language, the same way as the Business Request: short sentences in active voice, the business's own words, each fact said once, no filler or selling words (ensure, enable, leverage, seamless, robust), no em dashes, bold only for labels. A developer should understand an item in one read.
116
+
117
+ PBIs specify observable behavior, business rules, relevant exceptions and constraints. Name supplied assets where useful, such as the existing HR SharePoint library. For persistence, specify that tasks remain available at the next login. Database design, storage selection, connectors, migrations and other implementation tasks are outside this skill's scope and are managed separately. Preserve customer-imposed technology constraints without decomposing them into technical work here.
118
+
119
+ For a requested preliminary mockup, use the complete desired functionality recorded in the Business Request. Define the mockup Feature by the representation and approval the customer requested, and record that approval as a prerequisite on the implementation Features. The mockup validates the concrete result before implementation; it is not a reason to defer defining the desired behavior. Record the dependency explicitly in descriptions; do not invent an unsupported dependency-link type for the helper.
120
+
121
+ **Done when:** every need maps to a linked or drafted Feature, and every new Feature has its PBIs.
122
+
123
+ ### 6. Preview and approve
124
+
125
+ Show the tree with existing, extended and new items, the final coverage matrix including constraints and approvals, and a before/after comparison of every proposed existing-Feature update. Show the exact final fields, preserving unrelated content:
126
+
127
+ ```
128
+ Epic #12 Knowledge management (existing)
129
+ ├── Feature #42 Document search (existing, Done) ··· related: already covers N3
130
+ └── Feature [F1] Role-based HR document library (new) ··· related: realizes N1, N2, N4 (R1, R2)
131
+ ├── PBI [P1] As an employee, I see only the HR documents for my role
132
+ └── PBI [P2] As a manager, I also see evaluation procedures
133
+
134
+ Business Request #123 (outside the hierarchy, Related to Features)
135
+ ```
136
+
137
+ Iterate on the user's edits until they approve. Nothing is written before approval.
138
+
139
+ **Done when:** the user approves the exact fields and operations.
140
+
141
+ ### 7. Apply
142
+
143
+ Use the existing commands rather than adding unsupported update entries to the plan. Read `references/plan-format.md` for creation/link plans and separate existing-Feature field files. Preview all proposed operations before any write:
144
+
145
+ ```bash
146
+ python3 <ado> update <existing Feature id> --json /tmp/feature-update.json --dry-run
147
+ python3 <ado> apply /tmp/br-123-plan.json --dry-run
148
+ ```
149
+
150
+ The update dry run previews field operations; it does not ask Azure to validate them. The apply dry run checks hierarchy and forbidden fields and asks Azure DevOps to validate new items without saving them. Neither command checks that revised scope preserves prior requirements or that an existing Feature remains eligible for extension; verify those explicitly.
151
+
152
+ After the user has approved the exact fields and operations, re-read every Feature being extended. Confirm it is still New or Planned and that its current content matches the version reviewed. If it changed, reconcile with the user before overwriting it. Apply the approved Feature updates first, then apply the creation/link plan. If an update fails, stop the dependent operations and report the partial result.
153
+
154
+ Do not put `brComment` or `brCommentPosted` in a plan. Present the coverage matrix and decision log to the user, and keep material refinements in the affected Features and PBIs. The real apply run writes created IDs into the plan file; on retry it skips those items. Keep the files until completion and verify already-applied Feature updates before retrying them.
155
+
156
+ **Done when:** every approved update and the plan have run, or you have stopped and reported the partial result.
157
+
158
+ ### 8. Move the Business Request to In analysis
159
+
160
+ Run this step when the Business Request was Received at step 1 and now has at least one Related Feature link. Its first Feature link moves it to In analysis:
161
+
162
+ ```bash
163
+ python3 <ado> set-state <Business Request id> "In analysis" --comment "<one sentence in the Business Request's language: the analysis started and the date>"
164
+ ```
165
+
166
+ Skip this step when the Business Request was in another Human State at step 1, or when it still has no Feature link. When `set-state` refuses, report its error to the user and leave the state as it is.
167
+
168
+ **Done when:** `get <Business Request id>` reads back `"state": "In analysis"`, or this step was skipped by its condition, or the user has the refusal.
169
+
170
+ ### 9. Close the loop
171
+
172
+ - Re-read the affected Features and PBIs to verify the saved scope, criteria and relationships, and report every created, updated and linked item with its URL.
173
+ - Report uncovered requests, unresolved decisions and any partial application. Leave Business Request fields and ratings unchanged; the approved Feature links and the step 8 move to In analysis are its only writes.
174
+
175
+ **Done when:** the user has the URL of every created, updated and linked item, and the list of uncovered requests and open decisions.
176
+
177
+ ## The helper script
178
+
179
+ `<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`.
180
+
181
+ ```bash
182
+ python3 <ado> get 123 456 # items with fields and links
183
+ python3 <ado> backlog --types epic,feature,br [--include-removed] [--chars 0]
184
+ python3 <ado> backlog --under 12 --types feature,pbi,bug
185
+ python3 <ado> search "document search" --types epic,feature,pbi
186
+ python3 <ado> apply PLAN.json [--dry-run]
187
+ python3 <ado> update <existing Feature id> --json FILE [--dry-run]
188
+ python3 <ado> sync-ratings [42 43 | --all] [--dry-run] # maxima from all linked Business Requests; frozen Features skipped
189
+ python3 <ado> link 123 42 --type related --comment "Already covers Business Request #123: finding a document by describing it (Done)"
190
+ python3 <ado> set-state 123 "In analysis" --comment "Analysis started on 2026-10-30."
191
+ ```
192
+
193
+ `backlog` and `search` truncate long text to 600 and 400 characters respectively; pass `--chars 0` when you need full descriptions of a few candidates, or `get` them.
@@ -0,0 +1,111 @@
1
+ # Plan file format
2
+
3
+ `ado.py apply` takes a JSON file describing new items and links for one Business Request. Items are created in file order, so list parents before their children. Updates to existing Features use separate field files and `ado.py update`, as described below; the plan has no update operation.
4
+
5
+ ```json
6
+ {
7
+ "br": 123,
8
+ "items": [
9
+ {
10
+ "key": "F1",
11
+ "type": "feature",
12
+ "parent": 12,
13
+ "fields": {
14
+ "Title": "Role-based HR document library",
15
+ "Description": "## Summary\n…\n\n## Realizes\nBR #123:\n- New hires find onboarding documents on their own\n- Employees find HR documents in one place\n- Rule: each person sees only the documents for their role",
16
+ "AcceptanceCriteria": "- An employee sees only documents for their role\n- …"
17
+ }
18
+ },
19
+ {
20
+ "key": "P1",
21
+ "type": "pbi",
22
+ "parent": "F1",
23
+ "fields": {
24
+ "Title": "As an employee, I see only the HR documents for my role",
25
+ "Description": "## Context\n…\n\n## Acceptance criteria\n- …"
26
+ }
27
+ }
28
+ ],
29
+ "links": [
30
+ {
31
+ "from": 123,
32
+ "to": "F1",
33
+ "type": "related",
34
+ "comment": "Realizes Business Request #123: new hires find onboarding documents; employees find HR documents in one place"
35
+ },
36
+ {
37
+ "from": 123,
38
+ "to": 42,
39
+ "type": "related",
40
+ "comment": "Already covers Business Request #123: finding a document by describing it (Done)"
41
+ }
42
+ ]
43
+ }
44
+ ```
45
+
46
+ | Key | Meaning |
47
+ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
48
+ | `br` | ID of the Business Request being refined. |
49
+ | `items[].key` | Your temporary name for a new item (`E1`, `F1`, `P1`…), unique within the plan. |
50
+ | `items[].type` | `epic`, `feature`, `pbi` or `bug`. |
51
+ | `items[].parent` | An existing work item ID (integer) or the key of an item listed earlier. Required for Features (parent: Epic), PBIs and Bugs (parent: Feature). Epics have none. |
52
+ | `items[].fields` | Friendly field names, as in `ado.py`: `Title`, `Description`, `AcceptanceCriteria`, `Tags`, `Priority`… Rich-text fields accept the Markdown subset. |
53
+ | `links[]` | Related links only. `from`/`to` are IDs or item keys; `comment` explains the coverage. |
54
+
55
+ Business Request fields, ratings, state and discussion history are immutable in this workflow. Only approved Business Request ↔ Feature Related links may be added, with their coverage comments. Omit `brComment` and `brCommentPosted`: the general-purpose helper supports them, but they would write to the Business Request and must not be used by this skill. Present the coverage and decision log to the user; record refinements in the affected Feature/PBI content.
56
+
57
+ The applier refuses the plan if:
58
+
59
+ - an item's parent has the wrong type (for example a PBI under a Business Request or under an Epic);
60
+ - a Feature, PBI or Bug has no parent;
61
+ - any item carries estimates or dates (Effort, Story Points, Remaining Work, legacy Business Value, Time Criticality, Start/Target Date…);
62
+ - `br` is not a Business Request, or the plan has a `brParent`: a Business Request never has a parent.
63
+
64
+ After a real run, each created item gets an `"id"` in the file; running the same file again skips it. This is a creation-resume marker, not a way to update an existing Feature. The applier does not validate the semantic completeness of the backlog or the eligibility of an existing Feature for extension; check these as part of the skill workflow.
65
+
66
+ ## Extending an existing Feature
67
+
68
+ An extension includes both the approved changes to the parent Feature and the new PBIs. Read the full Feature, its existing PBIs and linked Business Requests before proposing a revision. Only New or Planned Features may be extended. Preserve requirements from all existing scope and ask the user to review the current versus proposed description, scope and acceptance criteria. Change the title only if needed and approved.
69
+
70
+ Put the complete replacement values for only the approved fields into a separate JSON file. For example, after agreeing to extend a personal to-do Feature with attachments:
71
+
72
+ ```json
73
+ {
74
+ "Description": "## Summary\nEach person keeps a private to-do list.\n\n## Scope\n- Existing task creation, editing, completion and deletion remain included.\n- People can also attach, open and remove files on their tasks.\n\n## Realizes\nBR #123: personal task management, including file attachments.\n\n## Context\nThe attachment behavior is the agreed extension to the existing Feature.",
75
+ "AcceptanceCriteria": "- Each person sees only their own tasks.\n- Task changes remain available at the next login.\n- A person can attach one or more files to their tasks, open them again and remove them.\n- Only the task owner can access its attachments."
76
+ }
77
+ ```
78
+
79
+ This example assumes those existing behaviors and attachment rules were confirmed. Actual replacements must retain the Feature's full prior requirements, context, exclusions and Business Request references; do not substitute the example for existing content. Leave ratings, state, estimates, dates and unrelated fields out of the update. The generic update command does not enforce this skill's scope restrictions.
80
+
81
+ The creation/link plan contains the new PBIs with the existing Feature's numeric ID as `parent`, plus the approved Business Request ↔ Feature link. Do not place the existing Feature in `items` or invent an `updates` key, which the applier does not process.
82
+
83
+ Preview both parts before writing:
84
+
85
+ ```bash
86
+ python3 <ado> update 55 --json /tmp/feature-55-update.json --dry-run
87
+ python3 <ado> apply /tmp/br-123-plan.json --dry-run
88
+ ```
89
+
90
+ The update dry run reads the current item and previews field operations locally. The apply dry run asks Azure to validate new items. Neither verifies the proposed business scope or guarantees that a Feature is still New or Planned when the real commands run.
91
+
92
+ After approval of the exact operations, re-read the Feature and compare its state and content with what the user reviewed. Reconcile any intervening change with the user. Apply the approved Feature update, then the creation/link plan:
93
+
94
+ ```bash
95
+ python3 <ado> update 55 --json /tmp/feature-55-update.json
96
+ python3 <ado> apply /tmp/br-123-plan.json
97
+ ```
98
+
99
+ If an update fails, stop its dependent operations. The sequence is not atomic: report completed and pending steps. Before retrying, verify the existing Feature's saved content and use the creation plan's recorded IDs to avoid duplicating work. Re-read affected items and links after success.
100
+
101
+ ## Deliverables and approval dependencies
102
+
103
+ For a customer-requested preliminary mockup, create a Feature with the agreed representation and approval criteria. On the implementation Features, state the required approval under `Dependencies and approvals`, naming the prerequisite deliverable and the approving role. These conditions are part of the scope to preserve during extensions. The helper supports Related links, not predecessor/successor links; record the dependency in the descriptions without inventing a link type or adding a schedule.
104
+
105
+ ## Derived Feature ratings
106
+
107
+ Every new Feature must have at least one Related Business Request in `links`. Each source Business Request must have BusinessValue and Urgency as integers 1–5. The applier derives these fields from all the Feature's planned Related Business Requests before creating it; do not score a Feature independently. If these fields are included explicitly, they must equal the computed maxima. They are not allowed on Epics, PBIs or Bugs.
108
+
109
+ After applying links, the helper recalculates both dimensions separately on eligible Features in New or Planned. From Committed onward, ratings are frozen, and adding a Related Business Request does not change them. The report's `feature_ratings` records updated, unchanged, frozen, or needs_input results. Report missing source scores without changing the Business Request. Drafting may continue, but do not apply operations whose required ratings cannot be derived from recorded source values.
110
+
111
+ The legacy `Microsoft.VSTS.Common.BusinessValue` remains forbidden. JSON `BusinessValue` now refers to `Custom.BusinessValueScore`; `Urgency` refers to `Custom.Urgency`.
@@ -0,0 +1,135 @@
1
+ ---
2
+ name: create-bug
3
+ description: Bug intake for the Human Backlog in Azure DevOps, guided for a business user. Works from screenshots, a screen recording, recorded speech or written input; clarifies observed and expected behavior, checks duplicates, finds the parent Feature, and creates the approved Bug, with no parent when no reliable Feature exists. Use when a business user reports a platform problem; technical investigation stays out.
4
+ ---
5
+
6
+ # Create a Bug
7
+
8
+ Help a business user turn an observed platform problem into a clear Bug. The user is not expected to know the backlog or the parent Feature. Research that association yourself and explain the proposed match in everyday language.
9
+
10
+ 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. Preserve exact error messages and relevant UI labels in their original language. Technical diagnosis, solution design and implementation work are out of scope and managed separately.
11
+
12
+ ## Working rules
13
+
14
+ - A Bug normally has a **Feature** as its parent, not an Epic, PBI or Business Request. If no reliable Feature can be identified, create the approved Bug **without a parent**. A missing parent does not block reporting and must not leave an otherwise complete report as a draft.
15
+ - Keep observations, the user's account, expected behavior and unresolved uncertainty distinct. A screenshot of a stale value is evidence of the visible result, not proof of a database failure.
16
+ - Search Features, their PBIs and existing Bugs. Include completed Features and closed Bugs. Read the relevant full content; a matching title alone is insufficient.
17
+ - Existing Features, PBIs and Business Requests are read-only during this workflow. Do not create a placeholder Feature or reopen a Feature to accommodate a Bug.
18
+ - Ask targeted questions only about material gaps. Do not request technical details, root causes or backlog IDs from the business user.
19
+ - A suspected duplicate or disagreement about expected behavior needs discussion. Do not silently discard the report, reopen an existing Bug or turn the report into a new feature request.
20
+
21
+ ## 1. Read the evidence and suggest a recording
22
+
23
+ Read the supplied text and inspect the screenshots, video and audio using the capabilities actually available in the environment. Combine the sources into one account; do not make the user repeat information that is already clear.
24
+
25
+ If a relevant screen recording has not already been supplied, proactively suggest one early in the conversation, for example:
26
+
27
+ > Can you record a short screen video while you reproduce the problem and attach it here in the chat? Show where you start, what you do and what happens; if you like, also say what you expected. It helps me rebuild the steps and prepare the Bug.
28
+
29
+ Make this an optional aid, not a prerequisite. Continue researching and preparing the report while the user records. If they cannot provide a video or prefer to proceed with sufficient text/screenshots, continue without insisting. When the user says a recording is coming, incorporate it before finalizing the report. Ask for attachments in normal chat rather than a text-only question tool.
30
+
31
+ For each source, retain a useful filename/reference and the relevant observation. Add video or audio timestamps only when actually inspected. Speech can explain intent or context but does not establish that an action is visible in a video. Do not infer a sequence from unordered screenshots without confirmation.
32
+
33
+ If a media format cannot be inspected, disclose that limitation and ask for the specific missing description or screenshots. Preserve an accessible original as evidence when approved, clearly separating user-reported observations from inspected content. Never pretend to have watched or transcribed it. Read `references/examples.md` for examples of evidence handling and parent selection.
34
+
35
+ **Done when:** you have read every supplied source, and you have suggested a recording or the user already supplied one.
36
+
37
+ ## 2. Clarify the problem in business language
38
+
39
+ Give a short account of what you understood, then ask one to three related questions about remaining gaps:
40
+
41
+ - What was the person trying to do, and in which page or workflow?
42
+ - What happened, and what should have happened instead?
43
+ - What starting conditions and steps are known? Ask about role, facility, environment or browser only where relevant and not already evident.
44
+ - Is it repeatable, intermittent or observed once? Record what the user knows; exact reproduction is not mandatory for an intermittent issue.
45
+ - What work is blocked or made difficult? Record the known impact and any known workaround without guessing how many people are affected.
46
+
47
+ Resolve ambiguity that prevents describing the problem. Do not turn the interview into a fixed diagnostic checklist or require a technical cause. Keep independently different problems separate when useful and agree the split with the user.
48
+
49
+ Compare the user's expectation with the candidate Feature/PBI criteria. If they differ, explain the discrepancy and record the confirmed expectation and its source. A missing documented requirement alone does not prove that the report is invalid. If the user confirms that they want a new capability rather than to report a malfunction, suggest `create-business-request` without creating a Business Request automatically.
50
+
51
+ **Done when:** the account names the page or workflow, the actual and expected result, and the known steps, frequency and impact, or the user cannot supply them.
52
+
53
+ ## 3. Research duplicates and the parent Feature
54
+
55
+ `<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`.
56
+
57
+ ```bash
58
+ python3 <ado> backlog --types epic,feature,bug --include-removed
59
+ python3 <ado> search "<functional terms or symptom>" --types feature,pbi,bug
60
+ python3 <ado> get <candidate IDs>
61
+ python3 <ado> backlog --under <candidate Feature ID> --types pbi,bug --include-removed --chars 0
62
+ ```
63
+
64
+ Search by the affected operation, page, role and business behavior. Keywords narrow the candidates but do not replace reading and comparison. The helper's search matches titles/descriptions; inspect Bug ReproSteps from `backlog --types bug --include-removed --chars 0` and `get` as well. Do not claim exhaustive duplicate checking after only a title search.
65
+
66
+ For a possible duplicate, compare context, steps, observed result and expectation. Explain the match and its state. Agree whether to add observations/evidence to the existing Bug or create a distinct report with the difference stated. A Done Bug with a recurring symptom may represent a recurrence; do not reopen it automatically. Preserve existing content when an update is approved.
67
+
68
+ For the parent, inspect the full Feature and relevant PBIs. A Done Feature can be the parent of a newly reported defect. Propose the best supported match with a brief explanation, such as:
69
+
70
+ > I would link it to “Personal task list”: it covers editing due dates, which is the behavior that fails here.
71
+
72
+ The user confirms the functional understanding, not the internal taxonomy. If candidates differ by behavior, ask a concrete question such as whether the problem occurs in the home box or in the full list. A Bug has at most one parent; do not select one arbitrarily when the evidence remains ambiguous.
73
+
74
+ If no reliable Feature is found, or candidates remain unresolved, proceed with **no parent**. Tell the user before creation that the Bug will still be opened and that they should pass its ID to the developer for association. If research failed because of access or tooling, report that limitation instead of claiming that no matching Feature or duplicate exists. Continue without a parent if Bug creation itself is available.
75
+
76
+ **Done when:** every possible duplicate is compared and agreed with the user, and the parent is one confirmed Feature or none.
77
+
78
+ ## 4. Prepare and approve the Bug
79
+
80
+ Use a factual title describing the symptom, for example “Task due date returns to its previous value after reload”. Put the report in **ReproSteps**, using relevant sections only:
81
+
82
+ ```text
83
+ ## Context
84
+ Page/workflow, role and relevant conditions known from the user or evidence.
85
+
86
+ ## Steps observed or reported
87
+ 1. The known sequence, identifying whether it was observed or user-reported.
88
+
89
+ ## Actual result
90
+ What happened, including the exact relevant message if present.
91
+
92
+ ## Expected result
93
+ What should happen, with the user or documented criterion as the source when material.
94
+
95
+ ## Frequency and impact
96
+ Known repeatability, affected work and any known workaround.
97
+
98
+ ## Evidence
99
+ Source filenames and concise observations; inspected timestamps where useful.
100
+
101
+ ## Still unknown
102
+ Relevant remaining uncertainty that does not prevent reporting.
103
+ ```
104
+
105
+ Use plain language and preserve the detail needed to understand the report without the chat. Do not invent missing steps, environment details, impact or causes. Do not make severity scoring, estimates, dates or assignees an intake requirement. Leave those fields and State to their defaults unless explicitly instructed otherwise. Do not add Business Request BusinessValue or Urgency fields to Bugs.
106
+
107
+ Show the exact fields, proposed Feature and reason (or **No parent — developer association required**), and the evidence files that will be attached. Obtain approval of the concrete report and operations, carrying forward valid approval already given. Changes to an existing duplicate Bug also require an agreed preview.
108
+
109
+ **Done when:** the user approves the exact fields, the parent or no parent, and the evidence files.
110
+
111
+ ## 5. Create the Bug and retain evidence
112
+
113
+ Read `references/azure-operations.md` for field JSON, commands, attachment handling and recovery.
114
+
115
+ Use `create --type bug` with `--parent <Feature ID>` only when a reliable match has been selected. Otherwise omit `--parent` entirely. Do not use the analysis `apply` plan for this intake: that format requires a parent and would prevent the explicitly supported no-parent path.
116
+
117
+ Validate the approved fields with `--dry-run`, then create once and retain the returned Bug ID and URL before uploading evidence. If creation returns an ambiguous timeout, inspect recent Bugs before retrying. Never recreate the Bug just because an attachment failed.
118
+
119
+ Attach approved accessible originals using the helper. Keep a separate receipt per file so a failed link can resume without uploading the file again. If media is unavailable, too large or cannot be uploaded, keep the created Bug, state which evidence is missing and offer to add it to that same ID when available. Never claim that a chat attachment is present in Azure until the upload and work-item link are verified.
120
+
121
+ Re-read the Bug to verify its fields, parent or absence of parent, and attached files. If Azure rejects parentless creation, report the actual validation error rather than inventing a Feature or claiming success.
122
+
123
+ **Done when:** the re-read Bug shows the approved fields, parent or no parent, and every approved file attached, or the missing evidence is named.
124
+
125
+ ## 6. Close the loop
126
+
127
+ Return the Bug ID and URL, the parent Feature or **no parent**, and any incomplete evidence transfer. Do not require the user to understand work-item types to use the result.
128
+
129
+ For every created Bug without a parent, explicitly ask the user to communicate its ID to the developer and provide a ready-to-copy message in their language:
130
+
131
+ > I opened Bug #123: ‹URL›. It has no parent Feature because no reliable match was found. Can you check it and link it to the correct Feature?
132
+
133
+ Use the actual returned ID and URL, and adapt the reason if research was unavailable. The user forwards this message; do not contact the developer automatically. A no-parent Bug is a created report awaiting association, not a failed intake.
134
+
135
+ **Done when:** the user has the Bug ID and URL, and for a Bug with no parent, the ready-to-copy message.