@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,41 @@
|
|
|
1
|
+
# Revision examples
|
|
2
|
+
|
|
3
|
+
## Received, no linked backlog
|
|
4
|
+
|
|
5
|
+
User: “Business Request #123 is still Received. Add that the landing page must also be in English.”
|
|
6
|
+
|
|
7
|
+
Read the Business Request and check the relationships. With no implementation backlog, update the language requirement and any directly contradictory wording. Do not ask the entire intake questionnaire again, require a new KPI or create translation Features. The Business Request stays Received. The user's clear instruction authorizes this scoped edit.
|
|
8
|
+
|
|
9
|
+
## In analysis, unshared and uncommitted
|
|
10
|
+
|
|
11
|
+
User: “In the already analyzed request, let's add the phone contact and remove the newsletter sign-up.”
|
|
12
|
+
|
|
13
|
+
Verify all linked Features are New or Planned, not just the two likely to change. Map the added contact behavior and removed newsletter behavior. Preserve unrelated parts of the Business Request and landing page. Update existing Feature/PBI scope and criteria where appropriate; create a missing Feature only if the existing backlog has no suitable coverage. Detach and retire the newsletter Feature if that entire Feature is now obsolete and unshared. If only one part is obsolete, revise that portion rather than cancelling the whole Feature.
|
|
14
|
+
|
|
15
|
+
Present any unresolved decomposition choices as a concrete proposal. Do not rerun business intake for requirements untouched by this revision.
|
|
16
|
+
|
|
17
|
+
## Shared Feature, untouched
|
|
18
|
+
|
|
19
|
+
A linked document-search Feature also serves another Business Request. The requested change affects only an unshared home-page Feature. Report the shared Feature as unchanged and proceed with the authorized edit. Sharing alone is not a reason to interrupt the revision.
|
|
20
|
+
|
|
21
|
+
## Shared Feature, removal or change
|
|
22
|
+
|
|
23
|
+
The user removes document search from Business Request #123. Feature #55 still realizes document search for Business Request #200.
|
|
24
|
+
|
|
25
|
+
Explain that retiring #55 would also withdraw planned work for #200. Offer the relevant choice, such as removing only the #123 link and leaving the shared Feature intact. Show any resulting rating change. Wait for explicit feedback on that impact before changing the Business Request, the link or the Feature.
|
|
26
|
+
|
|
27
|
+
If the user instead wants to change shared search behavior, show which criteria and PBIs would change and how that affects #200. A statement such as “yes, also change the shared search, keeping these constraints…” can settle the shown proposal. An unrelated earlier “go ahead” cannot.
|
|
28
|
+
|
|
29
|
+
## A protected Feature anywhere in the linked set
|
|
30
|
+
|
|
31
|
+
Business Request #123 is In analysis. Feature #55 is New, and Feature #56 is Committed. The user asks to change only #55.
|
|
32
|
+
|
|
33
|
+
Block the entire revision before writing. Explain that this version of the workflow requires all linked Features to be New or Planned and suggest a new Business Request for the change. Do not first detach #56, move it back to Planned, or update the Business Request alone.
|
|
34
|
+
|
|
35
|
+
## Received with existing backlog, or another Human State
|
|
36
|
+
|
|
37
|
+
A Business Request is Received but already linked to a Feature, or is In progress, On staging, Live, Rejected or Withdrawn. None of those cases is one of the two supported paths. Report the actual state/link and stop without writing. Do not repair workflow states as a side effect of editing.
|
|
38
|
+
|
|
39
|
+
## Concurrent change
|
|
40
|
+
|
|
41
|
+
After the proposal is prepared, a Feature becomes Committed or another Business Request is linked to it. Re-read before applying. The prior check and shared-feedback decision no longer cover the same situation. Stop before writing if no changes have begun; otherwise stop the remaining operations and report exactly which earlier writes succeeded. Do not replace the old expected revision with the current one and continue silently.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Revision operations
|
|
2
|
+
|
|
3
|
+
Use the shared helper `<ado>` named in `../SKILL.md`. Other skills use it too, so its generic write commands do not independently enforce the whole revision workflow. Run the dedicated read-only checks and preserve the reviewed snapshots before invoking them.
|
|
4
|
+
|
|
5
|
+
## Eligibility and shared feedback
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
python3 <ado> revision-check 123
|
|
9
|
+
python3 <ado> get 123 55 56
|
|
10
|
+
python3 <ado> backlog --under 55 --types pbi,bug --include-removed --chars 0
|
|
11
|
+
python3 <ado> revision-check 123 --touch 55 56
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
`revision-check` reads every directly linked Feature, even if it is outside `--touch`. It allows only Received with no implementation backlog, or In analysis or Planned with every linked/affected Feature in New or Planned. Missing or inaccessible items prevent a reliable check. Source attachments and references are not backlog. Unsupported direct Epic/PBI/Bug or hierarchy links on the Business Request are not silently repaired.
|
|
15
|
+
|
|
16
|
+
`--touch` lists existing Features and PBIs that the proposed operation affects. The helper follows a touched PBI to its Feature to detect sharing. Also list the existing parent of a new PBI, an existing Feature receiving a new Business Request link, a Feature being detached, and any Feature with a projected rating change. Do not list newly planned item keys or an Epic used only as a parent for a new Feature.
|
|
17
|
+
|
|
18
|
+
Once the user has explicitly addressed the displayed impact on shared Feature #55, the checked plan may use:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
python3 <ado> revision-check 123 --touch 55 56 --shared-approved 55
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
This flag records which specific decisions the operator has obtained; it does not obtain consent itself. It cannot bypass Committed or other disallowed states, and a stale decision does not cover a changed proposal or a different set of affected Business Requests.
|
|
25
|
+
|
|
26
|
+
Keep the JSON result and read the full fields needed for replacement values. `get` includes each item's `rev`. The check is a snapshot, not a lock; refresh and compare immediately before applying.
|
|
27
|
+
|
|
28
|
+
## Free edit
|
|
29
|
+
|
|
30
|
+
Write only changed fields to a JSON file. For example, after the user explicitly changes the language requirement:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"Description": "## What we want\nVisitors read the service information on the landing page.\n\n## Business details\nThe page is available in Italian and English."
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
This illustrates the format, not a replacement for a real Business Request. Preserve its existing content outside the requested change. Leave out State (`update` refuses it on a Business Request), parent fields, implementation planning and invented values.
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
python3 <ado> update 123 --json /tmp/br-123-update.json --expected-rev 7 --dry-run
|
|
42
|
+
python3 <ado> update 123 --json /tmp/br-123-update.json --expected-rev 7
|
|
43
|
+
python3 <ado> get 123
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Use the actual reviewed revision, not the sample number. A mismatched revision fails before writing. The update dry run previews operations locally and checks scores/revision; it does not ask Azure to validate all business rules. An Azure-required field error must be resolved with real input, without restarting unrelated intake questions.
|
|
47
|
+
|
|
48
|
+
## Cascade files and sequence
|
|
49
|
+
|
|
50
|
+
Prepare separate field JSON files for the Business Request and each existing Feature/PBI, plus a creation/link plan using the format documented in `../../analyze-business-request/references/plan-format.md`. Reuse that plan format and functional definitions, not the analysis workflow's prohibition on Business Request edits. Do not call analysis and then silently override its Business Request immutability rule.
|
|
51
|
+
|
|
52
|
+
Do not add an `updates` or `removals` property to an apply plan: the helper does not process those operations. Keep them in the local review record and use explicit commands.
|
|
53
|
+
|
|
54
|
+
After all eligibility, sharing and scope decisions are settled:
|
|
55
|
+
|
|
56
|
+
1. Recheck the full graph and reviewed content before the first write.
|
|
57
|
+
2. Update the current Business Request's agreed fields using its reviewed revision. Other Business Requests remain unchanged. If ratings change, capture the helper's resulting Feature-rating updates in the record.
|
|
58
|
+
3. Apply agreed existing Feature/PBI content changes, preserving unaffected requirements and using reviewed revisions. Account for verified rating changes caused by the previous step.
|
|
59
|
+
4. Validate and apply the creation/link plan. It creates new items and uses current recorded Business Request scores to derive new Feature ratings. Keep its saved IDs so retries resume instead of recreating items.
|
|
60
|
+
5. Remove obsolete Business Request ↔ Feature coverage links. Cancel obsolete PBIs/Features by setting State to Removed where that cancellation was agreed. Keep their hierarchy for traceability and do not hard-delete them or their Epic. For an entire withdrawn Feature, detach the current Business Request link before marking the Feature Removed so it is no longer represented as current coverage.
|
|
61
|
+
6. Verify the final fields, links, scope and derived ratings. Reconcile affected eligible Features with `sync-ratings <IDs> --dry-run`, then apply a reconciliation if the preview belongs to the agreed change.
|
|
62
|
+
|
|
63
|
+
Before each group, verify that remaining linked Features are still eligible and that sharing has not changed unexpectedly. Compare against the reviewed baseline plus verified changes from this operation. Any unexpected protected state or new shared impact stops the remaining writes; report a partial application if earlier writes succeeded. A fresh check is not permission to discard the earlier comparison.
|
|
64
|
+
|
|
65
|
+
If all Features are removed from an In analysis or Planned Business Request, it keeps its Human State in this workflow. A later eligible revision may add new coverage. If a cancellation affects a shared Feature, preserve the agreed handling of the other requests and report resulting coverage gaps explicitly.
|
|
66
|
+
|
|
67
|
+
## Removing a coverage link
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
python3 <ado> unlink 123 55 --type related --expected-rev 9 --dry-run
|
|
71
|
+
python3 <ado> unlink 123 55 --type related --expected-rev 9
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Use the current reviewed revision of the **source** item, updated only for verified writes from this same operation. The helper locates the actual relation index and uses a revision test before removing it, so an intervening edit cannot cause removal of a different relationship. It removes only Related links; it does not delete either item or change hierarchy.
|
|
75
|
+
|
|
76
|
+
The dry run previews removal and Feature scores after excluding the departing Business Request, using currently saved values. The real operation recalculates ratings from the remaining Business Requests. A Feature losing its last Business Request temporarily has no rating source; if it is being retired, complete the agreed Removed transition and verify the final result. Do not invent replacement ratings or leave an unintended active Feature without a source.
|
|
77
|
+
|
|
78
|
+
If a Feature still serves another Business Request, detaching the current Business Request normally leaves the Feature and its PBIs active. The link and any rating change remain part of the explicit shared-impact decision.
|
|
79
|
+
|
|
80
|
+
## Failure and recovery
|
|
81
|
+
|
|
82
|
+
Preflight blocks must happen before updating the Business Request or any other item. Write operations across items are not atomic. Retain the reviewed change set, source revisions, created IDs and operation results. If a response is lost, read the item/relationship to determine whether the intended operation took effect before retrying.
|
|
83
|
+
|
|
84
|
+
The apply plan's saved IDs prevent recreating already-created items. `unlink` recognizes an absent relation, and `update --expected-rev` rejects stale writes. Re-read and reconcile a failed or uncertain step; do not change expected revisions blindly. Report any fields saved without their complete cascade, and resume only after the outstanding eligibility and shared decisions remain valid.
|