@teurons/vds-diagrams 0.0.0-stage → 0.3.0
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 +170 -2
- package/dist/cli.js +2244 -0
- package/dist/diagrams.css +991 -0
- package/dist/grid.d.ts +1 -0
- package/dist/grid.js +283 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2044 -0
- package/dist/skills/vds-aggregates/SKILL.md +115 -0
- package/dist/skills/vds-ask-or-park/SKILL.md +101 -0
- package/dist/skills/vds-book-to-spec/SKILL.md +136 -0
- package/dist/skills/vds-build-from-published/SKILL.md +89 -0
- package/dist/skills/vds-change/SKILL.md +113 -0
- package/dist/skills/vds-context-map/SKILL.md +125 -0
- package/dist/skills/vds-contexts/SKILL.md +134 -0
- package/dist/skills/vds-diagrams/SKILL.md +88 -0
- package/dist/skills/vds-entities-and-values/SKILL.md +108 -0
- package/dist/skills/vds-language/SKILL.md +106 -0
- package/dist/skills/vds-model-review/SKILL.md +123 -0
- package/dist/skills/vds-ports-and-adapters/SKILL.md +119 -0
- package/dist/skills/vds-publish/SKILL.md +123 -0
- package/dist/skills/vds-reframe/SKILL.md +122 -0
- package/dist/skills/vds-requirements/SKILL.md +128 -0
- package/dist/skills/vds-requirements-review/SKILL.md +121 -0
- package/dist/skills/vds-scenarios/SKILL.md +142 -0
- package/dist/skills/vds-slice-blocks/SKILL.md +127 -0
- package/dist/skills/vds-story-walk/SKILL.md +128 -0
- package/dist/skills/vds-strip-invented/SKILL.md +130 -0
- package/dist/skills/vds-subdomains/SKILL.md +127 -0
- package/dist/skills/vds-which-skill/FILE-SHAPES.md +312 -0
- package/dist/skills/vds-which-skill/SKILL.md +125 -0
- package/dist/types/diagrams/src/grid/camera.d.ts +32 -0
- package/dist/types/diagrams/src/grid/capability.d.ts +11 -0
- package/dist/types/diagrams/src/grid/fold-uj.d.ts +2 -0
- package/dist/types/diagrams/src/grid/grid-canvas.d.ts +95 -0
- package/dist/types/diagrams/src/grid/index.d.ts +5 -0
- package/dist/types/diagrams/src/grid/input.d.ts +93 -0
- package/dist/types/diagrams/src/grid/route.d.ts +21 -0
- package/dist/types/engine/js/bridge.d.ts +12 -0
- package/dist/types/engine/js/index.d.ts +73 -0
- package/dist/types/vds-diagrams/src/canvas.d.ts +43 -0
- package/dist/types/vds-diagrams/src/from-scenarios.d.ts +4 -0
- package/dist/types/vds-diagrams/src/grid-folds.d.ts +1 -0
- package/dist/types/vds-diagrams/src/grid.d.ts +2 -0
- package/dist/types/vds-diagrams/src/index.d.ts +6 -0
- package/dist/types/vds-diagrams/src/types.d.ts +39 -0
- package/dist/types/vds-diagrams/src/user-journey.d.ts +54 -0
- package/dist/types/vds-diagrams/src/workspace.d.ts +25 -0
- package/dist/vds_engine.wasm +0 -0
- package/dist/workspace.d.ts +1 -0
- package/dist/workspace.js +113 -0
- package/package.json +68 -3
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-model-review
|
|
3
|
+
description: "Model review of one capability, before publish: an agent that did not write the model checks its commands, events, read models, aggregates, entities, value objects and ports against the requirements and scenarios, item by item, and reports. Use when a developer asks 'is the model ready?', or when tactical modeling on a capability ends. It reports and never fixes. The story read-back belongs to vds-requirements-review; fixes to vds-slice-blocks, vds-aggregates, vds-entities-and-values or vds-ports-and-adapters; the yes to vds-publish."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Model review
|
|
7
|
+
|
|
8
|
+
A model is right when every requirement and scenario of the capability can run on it and nothing in it is there without one of them asking for it.
|
|
9
|
+
|
|
10
|
+
Scenarios are the test of the model: event modeling (Dilger) says they are "typically translated into unit tests during implementation" (p215). So judge every block against a requirement statement or a scenario line. Taste is no finding: "I would have split this aggregate" is reported only with the rule that forces the split.
|
|
11
|
+
|
|
12
|
+
## When to use
|
|
13
|
+
|
|
14
|
+
- A capability's requirements and scenarios exist and tactical modeling on it has stopped. vds-slice-blocks derived the blocks with no person deciding them; this review and the developer are their first judges.
|
|
15
|
+
- Run it in an agent that did not write the model. The writer reads its own choices as required.
|
|
16
|
+
- Owned by a sibling: is the story whole and ready is vds-requirements-review. A rule nobody stated in a requirement or scenario is vds-strip-invented. Writing or changing any block is vds-slice-blocks, vds-aggregates, vds-entities-and-values or vds-ports-and-adapters. The person's yes is vds-publish.
|
|
17
|
+
|
|
18
|
+
## The pass
|
|
19
|
+
|
|
20
|
+
1. Run `vds check` (tool `vds_check`). It writes nothing. Done when you hold its full output: every problem, or "valid" and the open questions.
|
|
21
|
+
2. Read the capability's requirements, limits and scenarios, then the context's language. Read no model file before these, so the model is judged from what was asked. Done when you can say each requirement in one sentence.
|
|
22
|
+
3. Read the capability's commands, events and read models, then the context's modules, aggregates, entities, value objects and ports. `vds show <id>` (tool `vds_show`) lists the files that mention one id. Done when every block is listed once with the requirement that names it, or marked "nobody names it".
|
|
23
|
+
4. Answer the eight items below, in order. Each answer is yes or no. A no carries its evidence: the id, the line, and the requirement or scenario it fails against. Done when all eight have an answer and every no has its evidence.
|
|
24
|
+
5. Write the report in the fixed shape. Done when every finding names the one skill that would fix it and the developer has the report. Ask nothing; change nothing.
|
|
25
|
+
|
|
26
|
+
## The checklist
|
|
27
|
+
|
|
28
|
+
The machine already answers part of each item. Spend the reading on the right-hand column.
|
|
29
|
+
|
|
30
|
+
| # | Yes means | `vds check` already refuses | Read for | Fix with |
|
|
31
|
+
|---|---|---|---|---|
|
|
32
|
+
| 1 | Every scenario's Given is an event that exists, its When a command that exists, its Then an event or a read model state (Dilger p206-207; a read model scenario has no When, p63) | an unknown event, command or read model in a line; a command that does not produce the Then event; a missing attribute named after `with` | the plain-word lines ("And wrong tries have reached {captchaAfterWrong}"): can the events in the Given, with their attributes, make that state true? | vds-slice-blocks |
|
|
33
|
+
| 2 | Every read model attribute is filled by an event, and every event attribute by its command: the information completeness check (Dilger p60) | an attribute with no `of`; `of` naming an unknown event or attribute; an event attribute no command supplies | does the event named in `of` carry the data the `rule` needs; can the screen or a read model give the person each command attribute (p199) | vds-slice-blocks |
|
|
34
|
+
| 3 | Every event sits under an aggregate, or is listed as "no aggregate yet" | an event in the model outside an aggregate | each event still filed with the capability; list it by name. The open question "on no Entity" marks its command | vds-aggregates |
|
|
35
|
+
| 4 | No command, event or attribute exists that no requirement asks for | a command no scenario names; an event no scenario uses; a read model attribute nothing shows or sees | a command attribute nothing needs (the check accepts it); a block whose only scenario line no requirement statement asks for | vds-slice-blocks; vds-strip-invented when the scenario line itself has no source |
|
|
36
|
+
| 5 | Each aggregate holds only rules that must hold together | an aggregate with no `invariants`, or one naming an unknown requirement | per aggregate, read each requirement in `invariants`: must they be true at the same instant? Does any command produce events of two aggregates? | vds-aggregates |
|
|
37
|
+
| 6 | Every rule on a value sits on a value object | a type that is neither basic nor a real value object | each format, length, range or allowed set in a statement or scenario: find the attribute that carries it; its type must be a value object with `rules` or `values` (the check accepts a bare `string`) | vds-entities-and-values |
|
|
38
|
+
| 7 | Names match the context's language | an aggregate, entity, value object or module name missing from the language | command, event and read model names, and attribute names; the check does not read them | vds-language for a missing term; vds-slice-blocks for a rename |
|
|
39
|
+
| 8 | Nothing from another context's words is inside the model | nothing | attribute and block names copied from an external event or another context; open questions "no port to ..." and "no port for ..." | vds-ports-and-adapters |
|
|
40
|
+
|
|
41
|
+
## Rules
|
|
42
|
+
|
|
43
|
+
- **Quote the requirement a finding fails against.** A finding with no statement, scenario line or cited rule behind it is taste; drop it.
|
|
44
|
+
- Item 2 goes attribute by attribute: "look at every single attribute in a Read Model and verify the source event" (Dilger p60). A sampled read model hides the one missing source.
|
|
45
|
+
- Item 5 uses Vernon's test. An invariant is "a business rule that must always be consistent" (p353), and consistency here means in one transaction (p353-354). Requirements listed in `invariants` that can be true at different moments are what he calls false invariants, "artificial constraints imposed by developers" (p351). Report the aggregate as too large.
|
|
46
|
+
- A command that changes two aggregates is a finding: "a properly designed Bounded Context modifies only one Aggregate instance per transaction in all cases" (Vernon p354, his rule of thumb), and doing otherwise "may be a strong indication that your consistency boundaries are wrong" (p360).
|
|
47
|
+
- An aggregate points at another through `refers_to` with a value object in `by`: refer "only by their globally unique identity" (Vernon p361). Any other link between two aggregates is a finding for vds-aggregates.
|
|
48
|
+
- Item 6: a rule left on a plain string lets domain logic "leak out of the model" (Vernon p225). Report the attribute and the rule's source line.
|
|
49
|
+
- Item 7: a context has one language, and a team should "reject concepts not in the agreed UL" (Vernon p25, as the notes put it). A word the language lists under `tried` is a finding when a block uses it as its name.
|
|
50
|
+
- A read model is "not meant to deliver domain behavior, only data for display" (Vernon p141). An attribute whose `rule` decides what a requirement gives to a command is a finding for vds-slice-blocks.
|
|
51
|
+
- Report a `vds check` problem in plain words with its id: "Code Sent carries deviceModel and no command gives it" for `Code Sent.deviceModel: no command supplies it`.
|
|
52
|
+
- Open questions never fail the check. Report the model ones: "produces no event", "on no Entity", "on N Aggregates", "carries no identity of", "name is not in the past tense", "no port to", "no port for". Leave "nothing follows it", "one outcome only", "ends on ... shows nothing", "nothing is tracked here", "more than one person acts here", "no core subdomain", "serves N subdomains" and "no SCN obeys it" to vds-requirements-review.
|
|
53
|
+
|
|
54
|
+
## Right and wrong
|
|
55
|
+
|
|
56
|
+
Item 4. The check accepts this; no statement or scenario of "Accept a mobile number" mentions a referral:
|
|
57
|
+
|
|
58
|
+
```yaml
|
|
59
|
+
# wrong: reported as "Submit Mobile carries referralCode; no requirement asks for it"
|
|
60
|
+
id: CMD-AUTH--submit-mobile
|
|
61
|
+
attributes:
|
|
62
|
+
- name: mobile
|
|
63
|
+
type: VO-AUTH--mobile
|
|
64
|
+
- name: referralCode
|
|
65
|
+
type: string
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Item 6. The statement says "send a 6-digit code":
|
|
69
|
+
|
|
70
|
+
```yaml
|
|
71
|
+
# wrong, on the command: the rule lives only in the statement
|
|
72
|
+
- name: code
|
|
73
|
+
type: string
|
|
74
|
+
# right, on the command: typed by the value object
|
|
75
|
+
- name: code
|
|
76
|
+
type: VO-AUTH--code
|
|
77
|
+
# right, on the value object: the rule sits on the value
|
|
78
|
+
- name: digits
|
|
79
|
+
type: string
|
|
80
|
+
rules:
|
|
81
|
+
- exactly 6 digits
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## The report
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
Investor auth, model: NOT READY. 3 findings. Check: valid, 6 model open questions.
|
|
88
|
+
1 scenarios run: yes 2 completeness: yes 3 aggregates: yes, 1 event has no aggregate yet
|
|
89
|
+
4 nothing invented: NO 5 boundaries: yes 6 value rules: NO 7 language: NO 8 other contexts: yes
|
|
90
|
+
|
|
91
|
+
Findings
|
|
92
|
+
- 4. Submit Mobile carries referralCode. No requirement or scenario asks for it.
|
|
93
|
+
Fix with: vds-slice-blocks.
|
|
94
|
+
- 6. Submit Code takes the code as plain text. "The system SHALL send a 6-digit code"
|
|
95
|
+
puts a rule on it. Fix with: vds-entities-and-values.
|
|
96
|
+
- 7. The command is named "Push Handset". The language says Mobile. Fix with: vds-slice-blocks.
|
|
97
|
+
No aggregate yet: Security Limits Overridden.
|
|
98
|
+
For requirements review: none.
|
|
99
|
+
You decide: fix these first, or go to publish as it is and name what you accept.
|
|
100
|
+
Current until the model is edited.
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
READY means eight yes answers and a valid check. Any no, or any check problem, is NOT READY.
|
|
104
|
+
|
|
105
|
+
## Symptoms
|
|
106
|
+
|
|
107
|
+
| What you see or hear | Do |
|
|
108
|
+
|---|---|
|
|
109
|
+
| "The check passes, so the model is fine" | the check passes with an unasked command attribute, an off-language command name and a value with no rule; run all eight items |
|
|
110
|
+
| You wrote this model earlier in the session | stop; say the review needs an agent that did not write it |
|
|
111
|
+
| The developer says "just fix it while you are there" | report first; the fix is a new run of the skill named in the finding |
|
|
112
|
+
| A requirement has no scenarios, or a scenario looks wrong | no model finding; list it under "For requirements review" |
|
|
113
|
+
|
|
114
|
+
## Never
|
|
115
|
+
|
|
116
|
+
Never fix what it finds. Never edit, write or delete a file, never run `vds publish`, and never review a model you wrote. The developer decides what happens to each finding.
|
|
117
|
+
|
|
118
|
+
## Not covered
|
|
119
|
+
|
|
120
|
+
- Whether the requirements and scenarios are right or complete: vds-requirements-review and vds-strip-invented.
|
|
121
|
+
- Ports and adapters in a real workspace: the example has no port files, so item 8's port rows are untested there.
|
|
122
|
+
- Sagas and transactions across aggregates (Dilger ch. 9) and aggregates with event sourcing (Vernon appendix A): the notes mark both unread.
|
|
123
|
+
- The notes hold no book checklist for reviewing a whole model. The eight items are VDS's own list; each cited rule is the book's.
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-ports-and-adapters
|
|
3
|
+
description: "Ports and adapters of one VDS bounded context whose architecture is hexagonal: each side of its hexagon and what plugs into it. Use when the check asks \"no port to\" a context or \"no port for\" a person, when a context reaches a store with no port, when an upstream context's words appear in a port or adapter, or to judge the drawn hexagon. The relation and its roles belong to vds-context-map; commands and events to vds-slice-blocks."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Ports and adapters
|
|
7
|
+
|
|
8
|
+
Every thing that drives a hexagonal context or that it drives gets a port named in the context's own words, and the port to an upstream context translates that context's words into this context's value objects before they reach the model.
|
|
9
|
+
|
|
10
|
+
Vernon keeps the outside apart from the inside: the outside "reaches the inside through the application's API" (p126), and the inside "will not leak to the outside parts" (p129). A port is where that holds or fails.
|
|
11
|
+
|
|
12
|
+
## When to use
|
|
13
|
+
|
|
14
|
+
- After tactical modeling has written the context's commands, events and aggregates, and the developer has said the context is hexagonal.
|
|
15
|
+
- vds-context-map owns which contexts relate, the type, the roles (ACL, OHS, PL, CF) and external events; vds-contexts opens a context of kind external. An external event file already records the fact in this context's words and value objects; the adapter's `does` says the translation that makes it so. vds-slice-blocks owns commands, `to:`, `via:` and the translation requirement's blocks. vds-entities-and-values writes the value objects a translation lands in. vds-model-review judges the whole model.
|
|
16
|
+
- Architecture is the developer's choice, made per context (Vernon p132). Ask once if nobody said it.
|
|
17
|
+
|
|
18
|
+
## What spec 0.1 holds
|
|
19
|
+
|
|
20
|
+
Ports are written as files. The engine never derives them. Each port is a folder named by its id beside the context's model, with `port.yaml` (id, name, side, with, does) and one adapter file per adapter (id, name, does) in its adapters folder.
|
|
21
|
+
|
|
22
|
+
- `side` is `driving` (it comes in) or `driven` (it goes out).
|
|
23
|
+
- `with` names people ids and context ids only. A store has no `with`. A provider is an external context on the map, never a bare name.
|
|
24
|
+
- A driven port may be for storage or messaging with no `with` (Vernon p128-129: repositories and messaging are output adapters).
|
|
25
|
+
- The check refuses: a port with no adapter, a context in `with` the map does not relate, the port's own context in `with`, a folder name that differs from the id, a port in a context without `architecture: hexagonal`.
|
|
26
|
+
- The check asks, without failing: "no port to" each related context, "no port for" each person who issues a command in the context.
|
|
27
|
+
- The hexagon is compiled from the ports by `vds compile:hexagons` and drawn by `vds draw:hexagons`. Never write it.
|
|
28
|
+
|
|
29
|
+
## Method
|
|
30
|
+
|
|
31
|
+
1. Confirm the architecture. Read the context file. If `architecture: hexagonal` is missing, ask the developer one question: "Is this context built as a hexagon?" On yes, add the field in the same change as the first port. Done when the field is set or the skill stops.
|
|
32
|
+
2. List what drives the context: each person who issues a command (`by:`), each context that sends it a command or an external event, and time (a domain event with `source: time`). Done when every `by:` person and every relation on the map toward this context is on the list.
|
|
33
|
+
3. List what it drives: each context in a command's `to:`, each store the aggregates are kept in. Done when every `to:` context in the context's commands is on the list.
|
|
34
|
+
4. Group into ports by purpose. One port per purpose; several things may share it. Name it in the context's language and the person's words. Done when every name reads as something the business says and no name is a protocol, a vendor or the upstream's term.
|
|
35
|
+
5. Give each port its adapters: one per way in or out (screens, a message listener, a provider call, a database). Done when every port has an adapter whose `does` says what it turns into what.
|
|
36
|
+
6. Build the anticorruption layer. For each port with an upstream context, the adapter's `does` names the upstream's data and the value object of this context it becomes. Done when no upstream term survives past the adapter.
|
|
37
|
+
7. Write all ports in one checked change (`vds apply --base <rev>` or the `vds_apply` tool), then run `vds check`. Done when the check passes and no "no port" question is left, or each left one is explained to the developer.
|
|
38
|
+
8. Judge the hexagon. Run `vds generate:hexagons` and read the drawing: driving on the left, driven on the right, aggregates in the middle. Done when each side reads to the developer as what the context talks to.
|
|
39
|
+
|
|
40
|
+
## Rules
|
|
41
|
+
|
|
42
|
+
- Name a port for its purpose. Vernon says "there is not a strict definition of what a Port means" and his examples name ports by protocol (p127); naming by purpose is VDS's reading, so the hexagon reads in the business's words.
|
|
43
|
+
- Many adapters may share one port (Vernon p127: browser, REST and SOAP on one HTTP port).
|
|
44
|
+
- Input events enter on their own port, apart from other clients (Vernon p148).
|
|
45
|
+
- The anticorruption layer is an adapter and a translator (Vernon p465). It turns the upstream's data into a value object of the local context (p464) and passes data "with types as defined only in its own Bounded Context" (p453).
|
|
46
|
+
- Translate and keep as immutable values; do not keep them in step with the upstream (p468).
|
|
47
|
+
- `driving` and `driven` are the spec's words. Vernon says input and output port (p127).
|
|
48
|
+
|
|
49
|
+
## Right and wrong
|
|
50
|
+
|
|
51
|
+
A port named by the upstream and its technology:
|
|
52
|
+
|
|
53
|
+
```yaml
|
|
54
|
+
# wrong
|
|
55
|
+
id: PORT-AUTH--cybrilla-profile-api
|
|
56
|
+
name: Cybrilla Profile API
|
|
57
|
+
side: driven
|
|
58
|
+
with: [BC-AUTH--cybrilla]
|
|
59
|
+
does: Calls the profile endpoint
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```yaml
|
|
63
|
+
# right
|
|
64
|
+
id: PORT-AUTH--investor-details
|
|
65
|
+
name: Investor Details
|
|
66
|
+
side: driven
|
|
67
|
+
with: [BC-AUTH--cybrilla]
|
|
68
|
+
does: Asks for an investor's details and hands back what the context can use
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
An adapter that passes the upstream's data through, against one that translates:
|
|
72
|
+
|
|
73
|
+
```yaml
|
|
74
|
+
# wrong
|
|
75
|
+
id: ADP-AUTH--cybrilla-lookup
|
|
76
|
+
name: Cybrilla Lookup
|
|
77
|
+
does: Returns the Cybrilla profile
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```yaml
|
|
81
|
+
# right
|
|
82
|
+
id: ADP-AUTH--cybrilla-lookup
|
|
83
|
+
name: Cybrilla Lookup
|
|
84
|
+
does: Calls Cybrilla and translates its reply into an Email
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
A store has no `with`; a person who starts things sits on a driving port, and one the context only sends to may sit on a driven port:
|
|
88
|
+
|
|
89
|
+
```yaml
|
|
90
|
+
id: PORT-AUTH--credential-store
|
|
91
|
+
name: Credential Store
|
|
92
|
+
side: driven
|
|
93
|
+
does: Keeps MPIN credentials and sessions
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Symptoms
|
|
97
|
+
|
|
98
|
+
| What you see | Do |
|
|
99
|
+
|---|---|
|
|
100
|
+
| "no port to <context>" | add a port with that context in `with`, or tell the developer why none is needed |
|
|
101
|
+
| "no port for <person>" | add the person to a driving port |
|
|
102
|
+
| a person who is only sent to (an SMS reaches them) put on a driving port | a person who starts things sits on a driving port; one the context only sends to (an SMS reaches them) may sit on a driven port |
|
|
103
|
+
| "the context map does not relate" | stop; the relation is vds-context-map's |
|
|
104
|
+
| "ports need the context's architecture to be hexagonal" | step 1 |
|
|
105
|
+
| a port name holds an upstream term, a vendor or a protocol | rename it in the context's language |
|
|
106
|
+
| an upstream context has the ACL role and its port's adapter translates nothing | step 6 |
|
|
107
|
+
| a provider has no context to put in `with` | stop; vds-contexts opens the context of kind external, then vds-context-map relates it |
|
|
108
|
+
|
|
109
|
+
## Never
|
|
110
|
+
|
|
111
|
+
Never let another context's words into the model. Never write the compiled hexagon by hand.
|
|
112
|
+
|
|
113
|
+
## Not covered
|
|
114
|
+
|
|
115
|
+
- The check never ties the ACL role on the map to a port; the agent checks it in step 6.
|
|
116
|
+
- Spec 0.1 has no field for what a translation maps; it lives in the adapter's `does`.
|
|
117
|
+
- Time has no id for `with`; a port for a timer has an empty `with`. No example shows one.
|
|
118
|
+
- No example workspace has a port yet.
|
|
119
|
+
- The notes name no source for driving and driven: Vernon's notes say input and output; the Cockburn notes cover use cases only.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-publish
|
|
3
|
+
description: "Published copy of one capability: publish it on a person's yes. Use when a person says publish, freeze, sign off or \"we are done with this capability\"; when the reviews it needs came back READY; when a capability shows as never published or differs from published and the person wants it decided. To judge readiness use vds-requirements-review and vds-model-review; to edit something already published use vds-change; to build against a version use vds-build-from-published."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Publish
|
|
7
|
+
|
|
8
|
+
Publishing is the only gate in VDS: nothing is decided until a capability is published, and publish runs on a person's yes to one question about one preview.
|
|
9
|
+
|
|
10
|
+
**Never publish with a check problem or without a person's yes.**
|
|
11
|
+
|
|
12
|
+
Use this skill in the publish phase, on one capability at a time. Siblings own the neighbours. Judging whether the requirements read true is vds-requirements-review. Judging the model against them is vds-model-review. Editing something already published is vds-change. Building and recording test runs is vds-build-from-published. This skill edits no spec file.
|
|
13
|
+
|
|
14
|
+
## What publish does
|
|
15
|
+
|
|
16
|
+
Stated from the code and a run on a scratch copy of the example (2026-11-14).
|
|
17
|
+
|
|
18
|
+
- Publish takes the capability's files from the draft, plus every shared file the capability uses that the draft changed: language, people, subdomains, contexts, the context map, the model. The preview lists these as "shared files carried". The person's yes covers them too.
|
|
19
|
+
- The result is one published copy of the workspace, numbered `p1`, `p2` and so on. Each publish writes a whole new copy and moves the pointer to it. Earlier copies stay.
|
|
20
|
+
- Each scenario flow whose compiled content changed gets the next version number: 1 at its first publish, then 2. A flow that did not change keeps its version.
|
|
21
|
+
- Publish refuses when the published copy would have a check problem. It names each problem with file and line, exits 1, and writes nothing.
|
|
22
|
+
- Publish also refuses a capability with any step not modelled yet ("Refused: N step(s) not modelled yet in CAP-...; model them first."), listing each, and writes nothing. `vds check` calls such a draft "valid as a draft"; that is not ready to publish.
|
|
23
|
+
- Publish is two steps. The preview returns a `previewId` bound to the draft's revision and the current published copy. The confirm publishes exactly that preview and refuses as stale (exit 3) if either moved.
|
|
24
|
+
- Publish does not look at whether a review ran, at open hot spots, or at whether anything changed. Those are this skill's job.
|
|
25
|
+
|
|
26
|
+
## Method
|
|
27
|
+
|
|
28
|
+
1. **Name the capability and its state.** Run `vds status` (MCP: `vds_status`). It prints the problem count, the count of steps not modelled yet, and each capability as never-published, equal or differs.
|
|
29
|
+
Done when the capability is never-published or differs, and the problem count is 0. On equal, run the preview (step 3): `vds status` does not see an edited shared file. "shared files carried: none": tell the person nothing changed and stop, since a publish would still write a new copy with no new version. A file carried: go on. On any problem, stop and send it to the skill that owns the file. On any step not modelled yet in this capability, stop: run vds-slice-blocks until the check lists none, then vds-model-review, then start again here. Tell the person the model is not finished; do not ask them to publish.
|
|
30
|
+
2. **Confirm the reviews are current.** The capability has two halves: requirements, scenarios and screens (vds-requirements-review), and the model (vds-model-review). A report is current when no edit to its half happened after it. Each half that changed since the last published copy needs a current report; a half that did not change needs none; a first publish needs both. Find which half changed by comparing the draft with the published copy, as in step 4.
|
|
31
|
+
Done when each needed report is current and says READY, or the person has said in words that they publish on a NOT READY report and named what they accept.
|
|
32
|
+
3. **Preview.** Run `vds publish <CAP-ID>` with no other flag (MCP: `vds_publish_preview`). Keep the `previewId`.
|
|
33
|
+
Done when the preview shows the flows that change, the shared files carried, "capabilities removed: none", and the count of open questions. A refusal sends you back to step 1.
|
|
34
|
+
4. **Work out what is different.** For each changed flow, read its `title` and `end` from the compiled flow: `vds compile:scenario-flows` writes the capability's scenario flows and leaves the revision as it is. Compare the capability's requirements and scenarios in the draft with the last published copy (`.vds/published/<p-number>/domain/`; `current` holds the number) and list what was added, removed or reworded. On a first publish, everything is new: say so and give the counts.
|
|
35
|
+
Done when every changed flow has a plain-words name and every added or removed requirement and scenario is listed by its title.
|
|
36
|
+
5. **List what stays open.** Count the capability's hot spots with `status: open` and read their text. Carry the "blocks" and "can wait" marks over from the vds-requirements-review report; do not ask them again. Take the engine's open questions from `vds check`. The preview's count holds the engine's open questions only; open hot spots are not in it.
|
|
37
|
+
Done when both lists are in hand, each item in the person's words.
|
|
38
|
+
6. **Show the decision and ask once.** One message, in this order: what is new or different, what stays open, what publishing means. On a NOT READY report, repeat back what the person said they accept before the question. Then one yes-or-no question. No ids without their titles. No file paths.
|
|
39
|
+
Done when the message ends on one question mark and the person has replied.
|
|
40
|
+
7. **On yes, confirm.** Run `vds publish --confirm '<previewId>' --by "<the person's name>"` (MCP: `vds_publish` with `previewId` and `by`). On a stale refusal, go back to step 3 and ask again: the person said yes to a preview that no longer exists.
|
|
41
|
+
Done when the command printed "Published p<n>".
|
|
42
|
+
8. **Report the versions.** Tell the person the published copy's number and, for each changed flow, its title and new version number, read from the published copy's record of flow versions (`.vds/published/<p-number>/flows.json`). Run `vds status`.
|
|
43
|
+
Done when the capability shows equal and the person has each version number.
|
|
44
|
+
9. **On no, route each objection.** Publish nothing. Take objections one at a time and send each to its owner (table below). Come back to step 1 when the draft has changed.
|
|
45
|
+
Done when every objection has an owner skill or is parked as a hot spot.
|
|
46
|
+
|
|
47
|
+
## What the person is told publishing means
|
|
48
|
+
|
|
49
|
+
Say these three things every time, in plain words:
|
|
50
|
+
|
|
51
|
+
- This copy is published. It does not move when the draft is edited.
|
|
52
|
+
- Developers build against a scenario flow at a version number from this copy.
|
|
53
|
+
- Any later edit to what is published is a Change: it goes through the phases again and gives the flow a new version.
|
|
54
|
+
|
|
55
|
+
## Rules
|
|
56
|
+
|
|
57
|
+
- A yes covers one preview. "Looks fine", "ok" and "so we publish this" are not a yes; ask the question and wait for the word.
|
|
58
|
+
- Never pass `--yes`. It previews and publishes in one call, so the person never sees what they decide.
|
|
59
|
+
- Pass `--by` with the person's name. Without it the record holds the machine's user name, which is the agent's.
|
|
60
|
+
- One capability per question. Publish accepts several ids, but one yes then covers changes the person did not read apart.
|
|
61
|
+
- Open hot spots and open questions do not block a publish. The person decides whether to publish with them open; the agent never decides that for them, and never closes one to make the list shorter (vds-ask-or-park owns closing).
|
|
62
|
+
- Check the id before the preview. A capability id that is not in the draft is read as a removal: the preview says "capabilities removed: <code>" and a confirm takes it out of the published copy.
|
|
63
|
+
- Never write or edit the published copy by hand. Only `vds publish` writes it; a hand edit breaks the version record.
|
|
64
|
+
- Spec 0.1 has one gate. One publish carries both decisions, requirements and model. Nothing else in the spec or the tools decides.
|
|
65
|
+
|
|
66
|
+
## Right and wrong
|
|
67
|
+
|
|
68
|
+
Right: preview, then confirm what the person saw.
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
vds publish CAP-AUTH
|
|
72
|
+
vds publish --confirm 'd:65b979562d4c6564|p1|CAP-AUTH' --by "Asha Rao"
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Wrong: no preview shown, no name.
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
vds publish CAP-AUTH --yes
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Right message to the person:
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
Investor auth, compared with the last published copy:
|
|
85
|
+
- Changed: the flow "Resetting the MPIN" (ends on "Both codes verified").
|
|
86
|
+
The scenario "Forgot MPIN" was reworded. It becomes version 2.
|
|
87
|
+
- Unchanged: the other 7 flows keep version 1.
|
|
88
|
+
- Still open: 18 questions you raised, for example "Is there a limit
|
|
89
|
+
on resends?", and 35 questions the check asks, for example
|
|
90
|
+
"Code Dispatched: nothing follows it; what happens next?"
|
|
91
|
+
- The published copy stays as it is. Developers build against these
|
|
92
|
+
versions. Any later edit is a Change and gives a new version.
|
|
93
|
+
Publish Investor auth as shown? Yes or no.
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Wrong message: "Check is valid, DGSF-AUTH-bcd8a5ac changes, 35 open. I'll publish now unless you object." It uses ids without titles, leaves out the open hot spots, and takes silence as yes.
|
|
97
|
+
|
|
98
|
+
## Symptoms
|
|
99
|
+
|
|
100
|
+
| What you see or hear | Do |
|
|
101
|
+
|---|---|
|
|
102
|
+
| "Refused: N step(s) not modelled yet in CAP-..." | Publish nothing. vds-slice-blocks models each listed step; then vds-model-review; start again at step 1 |
|
|
103
|
+
| "Refused: the published workspace would have N problem(s)" | Publish nothing. Fix each named problem through the skill that owns the file; start again at step 1 |
|
|
104
|
+
| "The draft or the published version changed since the preview" | Preview again, show the person the new preview, ask again |
|
|
105
|
+
| "capabilities removed: X" and nobody asked to remove X | The id is wrong or the capability is gone from the draft. Stop and ask the person which |
|
|
106
|
+
| "This rule is wrong" or "we never said that" | vds-requirements or vds-strip-invented |
|
|
107
|
+
| "A step is missing from the story" | vds-story-walk |
|
|
108
|
+
| "That failure case is not there" | vds-scenarios |
|
|
109
|
+
| "I can't decide until we know the limit" | vds-ask-or-park; publish waits or goes ahead with it open, on the person's word |
|
|
110
|
+
| "The model is wrong" (command, event, aggregate, port) | vds-slice-blocks, vds-aggregates, vds-entities-and-values or vds-ports-and-adapters, whichever owns the block; then vds-model-review |
|
|
111
|
+
| "That is not our word for it" | vds-language |
|
|
112
|
+
| "Publish, but change this one line first" | Make the edit through its owner skill, rerun the review it touches, preview again |
|
|
113
|
+
| The capability already has a published copy and the person wants an edit | vds-change, then back here |
|
|
114
|
+
| The person asks to undo a publish | No command does this. Say so; the fix is a Change and a new publish |
|
|
115
|
+
|
|
116
|
+
## Not covered
|
|
117
|
+
|
|
118
|
+
- A list of added and removed requirements and scenarios: no command prints it. Step 4 compares the draft with the published copy by reading both.
|
|
119
|
+
- A record that a review ran: spec 0.1 has no field or file for it. Step 2 relies on the session.
|
|
120
|
+
- Who is allowed to say yes: spec 0.1 names no role for it. Take the yes from the person the agent works for.
|
|
121
|
+
- Unpublishing, or returning to an earlier published copy: no command exists.
|
|
122
|
+
- Sync of published copies to a hosted workspace or a team: not built.
|
|
123
|
+
- A review skill that is missing from this workspace: step 2 then asks the person directly whether that review was done.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-reframe
|
|
3
|
+
description: "Premise of a VDS draft: what the agent does when a person says it has the whole thing wrong. Use when a correction changes what the product is for, who it is for, what a core term means, where the story starts or ends, or which step is the centre. Something published belongs to vds-change; a gap nobody can answer to vds-ask-or-park; recording a term to vds-language; judging readiness to vds-requirements-review."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Reframe
|
|
7
|
+
|
|
8
|
+
When the premise is wrong, stop, get the corrected premise confirmed in one sentence, list everything built on the old one, and build those parts again from the method; a part built on a wrong premise carries it in places nobody listed.
|
|
9
|
+
|
|
10
|
+
A premise is what the draft takes for granted: what the product is for, who it is for, what a core term means, where the story starts or ends, which step is the centre. Use this skill in any phase, on any material of the three boxes, while the capability is a draft.
|
|
11
|
+
|
|
12
|
+
Siblings own the neighbours. A published capability that must change is vds-change. A question no person here can answer is vds-ask-or-park. Writing a term, its meaning and its tried wordings is vds-language. Reading the story back to judge readiness is vds-requirements-review; a wrong premise is often caught there and handed here.
|
|
13
|
+
|
|
14
|
+
## Which skill owns the correction
|
|
15
|
+
|
|
16
|
+
Walk the table top to bottom; the first row that fits wins.
|
|
17
|
+
|
|
18
|
+
| Ask | If yes |
|
|
19
|
+
|---|---|
|
|
20
|
+
| Does `vds status` (MCP: `vds_status`) show the capability as `equal` or `differs`? | It has a published copy: vds-change owns it as a premise change and runs steps 2 to 7 of this skill on the draft |
|
|
21
|
+
| Does only the word change, with the meaning unchanged? | A rename: vds-language |
|
|
22
|
+
| Does the correction change what more than one step means? | Reframe |
|
|
23
|
+
| Does it change what a term in the context's language means? | Reframe |
|
|
24
|
+
| Does it change one step, one rule, one limit or one field, and nothing else reads differently? | Detail fix: the skill that owns that material |
|
|
25
|
+
| Does nobody here know the right answer? | vds-ask-or-park |
|
|
26
|
+
|
|
27
|
+
## Method
|
|
28
|
+
|
|
29
|
+
1. **Stop writing.** Write no file and finish no change in progress. Say in one line that the work is paused on the person's correction.
|
|
30
|
+
Done when the last write in the session is from before the correction.
|
|
31
|
+
2. **Restate the premise.** One sentence, in the person's words, with the old premise beside it: "I built this as X. You are saying it is Y. Is that right?" One question, no ids. Repeat until the answer is yes.
|
|
32
|
+
Done when the person said yes to one sentence.
|
|
33
|
+
3. **List what stands on the old premise.** Run `vds index` (MCP: `vds_index`) and read each part with `vds show <ID>` (MCP: `vds_show`). Go through every material in this order and mark each part hit or clear, with one clause of why: subdomain, bounded context, context map, language terms, people, capability, requirements, scenarios, screens, hot spots, commands, domain events, read models, aggregates, entities, value objects, ports and adapters.
|
|
34
|
+
Run from this skill, a hit part inside a capability that `vds status` shows as `equal` or `differs` goes to vds-change with the confirmed sentence, once. Run from vds-change, the list, the removal and the rebuild stay in the draft and vds-change stays the owner.
|
|
35
|
+
Done when every part in the index is marked, and each hit names the sentence of the old premise it rests on.
|
|
36
|
+
4. **Show the list.** Give the person the hits in plain words, grouped by material, and what stays. Ask "is anything missing from this list?"
|
|
37
|
+
Done when the person agreed the list or added to it.
|
|
38
|
+
5. **Record the old wording.** Where a term was wrong, hand vds-language the old word or meaning as a tried wording with the person's reason.
|
|
39
|
+
Done when the context's language holds the corrected term and the old one sits under `tried`.
|
|
40
|
+
6. **Remove the hit parts in one change.** Use `vds apply` (MCP: `vds_apply`) so they leave together, then run `vds check` (MCP: `vds_check`). Keep every hot spot: an addressed one keeps its text, and one that points at a removed part is pointed at the screen when that stays, or loses its `"on"` and names the step in its text.
|
|
41
|
+
Done when the check reports no problem and no hit part is left in the index.
|
|
42
|
+
7. **Rebuild, by running the owning skills again on the corrected premise.** Run only the rows the list hit, in this order. Each skill starts from the person's words and the corrected sentence, never from the removed files.
|
|
43
|
+
|
|
44
|
+
| Order | Hit | Skill |
|
|
45
|
+
|---|---|---|
|
|
46
|
+
| 1 | where the boundary is, which part of the business | vds-contexts, vds-subdomains |
|
|
47
|
+
| 2 | terms, people | vds-language |
|
|
48
|
+
| 3 | the story: start, end, centre, order of steps, screens | vds-story-walk |
|
|
49
|
+
| 4 | requirements, limits | vds-requirements |
|
|
50
|
+
| 5 | scenarios | vds-scenarios |
|
|
51
|
+
| 6 | commands, domain events, read models (the steps rows 4 and 5 saved are modelled here, now or in a later session); who depends on whom, once a command or event crosses | vds-slice-blocks, vds-context-map |
|
|
52
|
+
| 7 | aggregates, entities, value objects, ports, adapters | vds-aggregates, vds-entities-and-values, vds-ports-and-adapters |
|
|
53
|
+
|
|
54
|
+
Done when each hit row has run and `vds check` reports no problem.
|
|
55
|
+
8. **Read it back.** Say the corrected premise and the rebuilt story in plain words. Then hand over to vds-requirements-review.
|
|
56
|
+
Done when the person says the story now starts from the right premise.
|
|
57
|
+
|
|
58
|
+
## Rules
|
|
59
|
+
|
|
60
|
+
- Expect the correction. Storming (Brandolini): a bumpy telling of the story "is a good sign", and everyone "can (and must)" interrupt the narrator (p94-95).
|
|
61
|
+
- Tell a detail from a premise. Storming (Brandolini) adds a missing event or system "on the fly" while the story is told (p95). That is a detail fix. A reframe is when the story itself reads differently afterwards.
|
|
62
|
+
- Be ready to drop work. Storming (Brandolini): "we should be ready to discard parts of our plan" (p95-96). Telling the story backward finds "around 30-40%" that was "buried under the optimistic thinking" (p98).
|
|
63
|
+
- Rename when the meaning moved. Storming (Brandolini) renames "Participant name changed" to "Ticket Transferred" once the real case is understood (p97-98).
|
|
64
|
+
- The person's sentence is the premise. Patton: users often correct the map (research finding 10, one article, no page).
|
|
65
|
+
- List before touching anything. A part fixed before the list is whole leaves the rest standing on the old premise.
|
|
66
|
+
- Rebuild in the order of the table. A requirement written before its term is settled is written twice.
|
|
67
|
+
|
|
68
|
+
## Right and wrong
|
|
69
|
+
|
|
70
|
+
The example's old premise: a lock is a screen the investor is sent to. The person: "No. A lock is a message on the same screen."
|
|
71
|
+
|
|
72
|
+
Right: the old wording kept as a tried wording, in the person's reason.
|
|
73
|
+
|
|
74
|
+
```yaml
|
|
75
|
+
- term: Lock
|
|
76
|
+
means: "A stop of {lockMinutes} minutes after {lockAfterWrong} wrong tries, shown on the same screen."
|
|
77
|
+
tried:
|
|
78
|
+
- term: Blocked
|
|
79
|
+
kept: false
|
|
80
|
+
why: "It was drawn as a screen; a lock is a message on the screen."
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Right: the requirement written again from the corrected premise, on the screens where the lock shows.
|
|
84
|
+
|
|
85
|
+
```yaml
|
|
86
|
+
- id: REQ-AUTH-0022
|
|
87
|
+
title: Show when to try again
|
|
88
|
+
type: state_view
|
|
89
|
+
screen: [SCR-AUTH-02, SCR-AUTH-03, SCR-AUTH-07]
|
|
90
|
+
statement: When a lock is active, the system SHALL show when the investor can try again.
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Wrong: the old requirement kept and relabelled. The title says Lock; the screen of its own and the statement still say the old premise.
|
|
94
|
+
|
|
95
|
+
```yaml
|
|
96
|
+
- id: REQ-AUTH-0022
|
|
97
|
+
title: Show the lock
|
|
98
|
+
type: state_view
|
|
99
|
+
screen: SCR-AUTH-09
|
|
100
|
+
statement: The system SHALL send the investor to the Blocked screen.
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Symptoms
|
|
104
|
+
|
|
105
|
+
| The person says, or the draft shows | Do |
|
|
106
|
+
|---|---|
|
|
107
|
+
| "No, that is not what this is for" | Stop; step 2 |
|
|
108
|
+
| "You keep calling it X. X means something else here" | Reframe; the term goes to vds-language in step 5 |
|
|
109
|
+
| "It does not start there", "the real point is the step you skipped" | Reframe; the story is hit, row 3 |
|
|
110
|
+
| "Step 4 is wrong, the code has 6 digits" | Detail fix; vds-requirements |
|
|
111
|
+
| A third detail fix in a row on the same topic | Ask whether one premise sits behind all three |
|
|
112
|
+
| A search-and-replace of one word across the files | Stop; list first, then rebuild |
|
|
113
|
+
|
|
114
|
+
## Never
|
|
115
|
+
|
|
116
|
+
Never patch the old artifact and relabel it. An artifact built on a wrong premise carries the premise in places nobody listed.
|
|
117
|
+
|
|
118
|
+
## Not covered
|
|
119
|
+
|
|
120
|
+
- Evans on breakthroughs ("not a technique; it is an event", ch. 8): the notes hold no Evans chapter. The research file cites the book text. Not covered.
|
|
121
|
+
- Where the corrected premise is stored: spec 0.1 has no field for what a capability is for. It lives in the capability's title, the language and the rebuilt requirements.
|
|
122
|
+
- A premise that is wrong across two contexts: the notes give no method. Run the skill once per context.
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-requirements
|
|
3
|
+
description: "Requirement (REQ) of a VDS capability: one story step as one typed rule, nfr requirements and limits included. Use when a walked step has no requirement yet, when the type of a requirement is unclear, when a statement reads in technical words, or when a number appears in a statement or title. Finding the steps belongs to vds-story-walk; Given / When / Then to vds-scenarios; commands, events and read models to vds-slice-blocks; the after-the-fact trace to vds-strip-invented."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Requirements
|
|
7
|
+
|
|
8
|
+
Turn one step the person described into one requirement, with one type, a statement in the person's words, and every number named once.
|
|
9
|
+
|
|
10
|
+
Use it after the story walk has named the step and its screen. A requirement is written inside one bounded context, in the capability's requirements. vds-story-walk owns finding the steps and naming screens. vds-scenarios owns the outcomes, `exits` and `start`. vds-slice-blocks derives the command, events, read model and any wiring, in this session or a later one. The person sees and decides the requirement in plain words; show them no id. vds-strip-invented owns checking afterwards that each requirement traces to a person.
|
|
11
|
+
|
|
12
|
+
## Method
|
|
13
|
+
|
|
14
|
+
1. Find the sentence. Quote what the person said about this step. Done when the requirement has a quoted source, or the step goes to vds-ask-or-park as a hot spot.
|
|
15
|
+
2. Pick the type with the table below. Ask the questions in order; take the first yes. Done when exactly one type is chosen.
|
|
16
|
+
3. Split a step that writes and reads. Every write and every read is its own slice (Dilger p163). "Verify the code and open the next screen" is a state_change and a state_view. Done when each requirement has one type.
|
|
17
|
+
4. Word it. Title, then statement, per the wording rules. Done when the statement contains SHALL and uses only words the person used or the context's language holds.
|
|
18
|
+
5. Name every number. Each limit sits once on the capability's limits requirement and is named `{name}` everywhere else. Done when no statement, title or scenario carries a bare number with a unit.
|
|
19
|
+
6. Leave the model fields empty (see "Left empty"). Done when no command, event or read model id was made up for this requirement. A step with only its model missing is never held and gets no hot spot.
|
|
20
|
+
7. Hand it on. Give vds-scenarios the drafted requirement text, any new `limits:` entry, and the screen's id and title when this is the first requirement on that screen. Write no file here: a requirement alone is refused (`no scenario file`). vds-scenarios words the scenarios and saves requirement, scenario file and first screen file as soon as the person agrees them; the check then lists the step as not modelled yet, which is expected. The one exception: an edit to a requirement already saved that leaves every scenario line true (a reworded statement, a changed limit value) is written here with `vds write <path> --base <rev>`, or `vds apply` with the scenario file when the title changes, then `vds check`. Done when vds-scenarios has the text and this skill wrote no file, or the edit passed the check.
|
|
21
|
+
|
|
22
|
+
## Pick the type
|
|
23
|
+
|
|
24
|
+
| # | Question | Yes means | Source |
|
|
25
|
+
|---|---|---|---|
|
|
26
|
+
| 1 | Is it about sending a named tracking event when something is used? | analytics | VDS's own; Dilger names four patterns only |
|
|
27
|
+
| 2 | Does it hold across steps with no screen of its own: storage, security, session, the current limits? | nfr | VDS's own |
|
|
28
|
+
| 3 | Does data arrive from another system, at our edge? | translation | Dilger's fourth pattern (p56-59) |
|
|
29
|
+
| 4 | Does the system act by itself after something happened or time passed, with nobody pressing anything? | automation | Dilger p55-56: a state view plus a state change, run in the background |
|
|
30
|
+
| 5 | Does a person do something that changes what the system holds? | state_change | Dilger p52: the only way to change a system |
|
|
31
|
+
| 6 | Does the person only see something, or does the system choose which screen opens next? | state_view | Dilger p54 |
|
|
32
|
+
|
|
33
|
+
The check enforces the shape of each type:
|
|
34
|
+
- automation, translation, nfr and analytics have no screen. An automation may point at a message box screen only. A state_view may have no screen when an automation reads its read model (a background process, Dilger p54). Such a view requirement is optional: the automation's `read_model` and `sees` already say what it reads.
|
|
35
|
+
- Exits that lead to more than one screen make it a state_view (REQ-AUTH-0031).
|
|
36
|
+
- Only state_change and state_view have exits.
|
|
37
|
+
|
|
38
|
+
## Wording rules
|
|
39
|
+
|
|
40
|
+
- Write the rule the way the domain expert states it. Vernon captures the expert's own sentence and models from it (p33, p288-289); a rewrite in technical words loses the language of the context.
|
|
41
|
+
- Statement: "The system SHALL ...". Use "SHALL NOT" for a ban. Start a reaction with "When <what happened>, ...". The check refuses a statement with no SHALL.
|
|
42
|
+
- Title: a short verb phrase a person would say ("Send the mobile code"). The scenario file's Feature title must equal it.
|
|
43
|
+
- Name people by their people file (investor, Ops). A system is a context, never people.
|
|
44
|
+
- A rule the person stated with no example yet stays in the statement; park "what happens when <rule> is broken?" through vds-ask-or-park.
|
|
45
|
+
- Keep one step per requirement. Two steps in one statement become two requirements.
|
|
46
|
+
|
|
47
|
+
## Limits
|
|
48
|
+
|
|
49
|
+
- A number that differs per item (each fund's minimum amount) is data about that item: say it in the statement in words ("at least the fund's minimum"), never as a limit.
|
|
50
|
+
- A limit is a number the business can change: wrong tries, minutes, seconds, hours. For any other number ask "could the business change this later?": yes makes it a limit, no keeps it in the statement as said ("a 6-digit code").
|
|
51
|
+
- Exactly one nfr requirement per capability holds `limits:`. The check refuses a second holder, an unknown `{name}`, and a number with minutes, seconds or hours. It misses a count ("5 wrong codes"); read every title and statement for one.
|
|
52
|
+
- Write the value the person said. No value said: hold the requirement and park "what is the value?" through vds-ask-or-park, as a hot spot that names the step in its text; a `{name}` missing from `limits:` is refused (`unknown limit {name}`). Never pick a default yourself.
|
|
53
|
+
- Names are camelCase letters only: `lockAfterWrong`, `codeExpiryMinutes`.
|
|
54
|
+
- No holder yet when the first limit gets a value: draft it as below (title "Apply the current limits", type nfr), read its statement to the person for a yes, and hand it on with the step that names the limit. It needs a scenario file of its own and lands in that step's change.
|
|
55
|
+
|
|
56
|
+
Right:
|
|
57
|
+
```yaml
|
|
58
|
+
- id: REQ-AUTH-0023
|
|
59
|
+
title: Lock after {lockAfterWrong} wrong codes
|
|
60
|
+
type: automation
|
|
61
|
+
statement: The system SHALL lock for {lockMinutes} minutes after {lockAfterWrong} wrong codes.
|
|
62
|
+
```
|
|
63
|
+
Wrong (bare numbers; the check refuses "15 minutes" and misses "5 wrong codes"):
|
|
64
|
+
```yaml
|
|
65
|
+
title: Lock after 5 wrong codes
|
|
66
|
+
statement: The system SHALL lock the account for 15 minutes after 5 failed OTP attempts.
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The limits holder, as in the example:
|
|
70
|
+
```yaml
|
|
71
|
+
- id: REQ-AUTH-0028
|
|
72
|
+
title: Apply the current limits
|
|
73
|
+
type: nfr
|
|
74
|
+
limits:
|
|
75
|
+
lockAfterWrong: 5
|
|
76
|
+
lockMinutes: 15
|
|
77
|
+
statement: The system SHALL apply the developer defaults unless an active Ops override replaces them.
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Left empty
|
|
81
|
+
|
|
82
|
+
This skill writes `id`, `title`, `type`, `statement`, `screen` (from the story walk), `limits`, and for analytics `sends`, `on` and `attributes`. It leaves these for later:
|
|
83
|
+
- automation: `trigger`, `read_model`, `sees`, `command`. vds-slice-blocks fills them; until then the check lists the step as not modelled yet.
|
|
84
|
+
- translation: `external`, `command` and `event`.
|
|
85
|
+
- state_view: `read_model`.
|
|
86
|
+
- analytics: `sends` is required, a dotted name (`investor.auth.mobile_entry.submitted`); ask the person for it, and if they have none, hold the step and park the question. `on` names the screen, command or event the person said it tracks: write it at once for a screen; for a command or event, write the id from the person's words and vds-slice-blocks writes the file. `attributes` only as the person stated them.
|
|
87
|
+
- `exits` and `start` name scenario ids; vds-scenarios writes them.
|
|
88
|
+
|
|
89
|
+
A requirement saved before its blocks shows in the check as a step not modelled yet; vds-slice-blocks models it later. Name each block by an id taken from the person's words; never write a block file only to clear the list.
|
|
90
|
+
|
|
91
|
+
Right (the person said "send the code to the mobile"):
|
|
92
|
+
```yaml
|
|
93
|
+
- id: REQ-AUTH-0002
|
|
94
|
+
title: Send the mobile code
|
|
95
|
+
type: automation
|
|
96
|
+
statement: The system SHALL send a code to the mobile.
|
|
97
|
+
```
|
|
98
|
+
The person named no length, so the statement names none. A length the person says and the business can change is a limit; a fixed one is written as said.
|
|
99
|
+
Wrong (wiring guessed while wording, words nobody said):
|
|
100
|
+
```yaml
|
|
101
|
+
title: OTP dispatch handler
|
|
102
|
+
type: automation
|
|
103
|
+
trigger: [EVT-AUTH--otp-requested]
|
|
104
|
+
command: CMD-AUTH--dispatch-otp
|
|
105
|
+
statement: The system SHALL publish an OTP job to the SMS queue.
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Symptoms
|
|
109
|
+
|
|
110
|
+
| The person says, or the draft shows | Do |
|
|
111
|
+
|---|---|
|
|
112
|
+
| "after that it just happens" | automation; leave its wiring empty |
|
|
113
|
+
| "the other system sends us back ..." | translation |
|
|
114
|
+
| "it should be secure", "fast" with no rule | ask for the concrete rule; park it if no answer |
|
|
115
|
+
| a number in a title or statement | move it to `limits:` and write `{name}` |
|
|
116
|
+
| two SHALLs about two steps | split into two requirements |
|
|
117
|
+
| "OTP", "endpoint", "queue" the person never said | reword in the person's words |
|
|
118
|
+
| one requirement both changes and shows | split: state_change and state_view |
|
|
119
|
+
|
|
120
|
+
## Never
|
|
121
|
+
|
|
122
|
+
Never write a requirement nobody stated. A step with no quoted source becomes a hot spot through vds-ask-or-park.
|
|
123
|
+
|
|
124
|
+
## Not covered
|
|
125
|
+
|
|
126
|
+
- Saving the requirement: vds-scenarios, with its scenario file; modelling it: vds-slice-blocks. Read one with `vds show <ID>` (MCP: `vds_show`).
|
|
127
|
+
- The notes give no rule for when an nfr deserves its own requirement over a line in another statement.
|
|
128
|
+
- The notes give no source for the analytics type; it is VDS's own.
|