@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.
Files changed (51) hide show
  1. package/README.md +170 -2
  2. package/dist/cli.js +2244 -0
  3. package/dist/diagrams.css +991 -0
  4. package/dist/grid.d.ts +1 -0
  5. package/dist/grid.js +283 -0
  6. package/dist/index.d.ts +1 -0
  7. package/dist/index.js +2044 -0
  8. package/dist/skills/vds-aggregates/SKILL.md +115 -0
  9. package/dist/skills/vds-ask-or-park/SKILL.md +101 -0
  10. package/dist/skills/vds-book-to-spec/SKILL.md +136 -0
  11. package/dist/skills/vds-build-from-published/SKILL.md +89 -0
  12. package/dist/skills/vds-change/SKILL.md +113 -0
  13. package/dist/skills/vds-context-map/SKILL.md +125 -0
  14. package/dist/skills/vds-contexts/SKILL.md +134 -0
  15. package/dist/skills/vds-diagrams/SKILL.md +88 -0
  16. package/dist/skills/vds-entities-and-values/SKILL.md +108 -0
  17. package/dist/skills/vds-language/SKILL.md +106 -0
  18. package/dist/skills/vds-model-review/SKILL.md +123 -0
  19. package/dist/skills/vds-ports-and-adapters/SKILL.md +119 -0
  20. package/dist/skills/vds-publish/SKILL.md +123 -0
  21. package/dist/skills/vds-reframe/SKILL.md +122 -0
  22. package/dist/skills/vds-requirements/SKILL.md +128 -0
  23. package/dist/skills/vds-requirements-review/SKILL.md +121 -0
  24. package/dist/skills/vds-scenarios/SKILL.md +142 -0
  25. package/dist/skills/vds-slice-blocks/SKILL.md +127 -0
  26. package/dist/skills/vds-story-walk/SKILL.md +128 -0
  27. package/dist/skills/vds-strip-invented/SKILL.md +130 -0
  28. package/dist/skills/vds-subdomains/SKILL.md +127 -0
  29. package/dist/skills/vds-which-skill/FILE-SHAPES.md +312 -0
  30. package/dist/skills/vds-which-skill/SKILL.md +125 -0
  31. package/dist/types/diagrams/src/grid/camera.d.ts +32 -0
  32. package/dist/types/diagrams/src/grid/capability.d.ts +11 -0
  33. package/dist/types/diagrams/src/grid/fold-uj.d.ts +2 -0
  34. package/dist/types/diagrams/src/grid/grid-canvas.d.ts +95 -0
  35. package/dist/types/diagrams/src/grid/index.d.ts +5 -0
  36. package/dist/types/diagrams/src/grid/input.d.ts +93 -0
  37. package/dist/types/diagrams/src/grid/route.d.ts +21 -0
  38. package/dist/types/engine/js/bridge.d.ts +12 -0
  39. package/dist/types/engine/js/index.d.ts +73 -0
  40. package/dist/types/vds-diagrams/src/canvas.d.ts +43 -0
  41. package/dist/types/vds-diagrams/src/from-scenarios.d.ts +4 -0
  42. package/dist/types/vds-diagrams/src/grid-folds.d.ts +1 -0
  43. package/dist/types/vds-diagrams/src/grid.d.ts +2 -0
  44. package/dist/types/vds-diagrams/src/index.d.ts +6 -0
  45. package/dist/types/vds-diagrams/src/types.d.ts +39 -0
  46. package/dist/types/vds-diagrams/src/user-journey.d.ts +54 -0
  47. package/dist/types/vds-diagrams/src/workspace.d.ts +25 -0
  48. package/dist/vds_engine.wasm +0 -0
  49. package/dist/workspace.d.ts +1 -0
  50. package/dist/workspace.js +113 -0
  51. package/package.json +68 -3
@@ -0,0 +1,121 @@
1
+ ---
2
+ name: vds-requirements-review
3
+ description: "Requirements review of one capability, before publish: an agent that did not write them narrates the story forward then backward in plain words, runs the check, reads the open questions and open hot spots, and reports ready or not ready per requirement. Use when a person asks 'is this ready?', or after vds-strip-invented has run. It reports and never fixes. Commands, events and read models go to vds-model-review; the person's yes and the publish command go to vds-publish."
4
+ ---
5
+
6
+ # Requirements review
7
+
8
+ A capability's requirements are ready when a person has heard the whole story told back, forward and backward, and nothing in it surprised them, stopped them or ended in the air.
9
+
10
+ A streamlined story hides its gaps. Storming (Brandolini): after the walk-through and the backward pass, "around 30-40%" of the system is usually found that "was buried under the optimistic thinking" (p98). The check finds what the files lack. Only the person hearing the story finds what the story lacks.
11
+
12
+ ## When to use
13
+
14
+ - A person asks whether a capability is ready, or requirement discovery on it has stopped.
15
+ - Run it after vds-strip-invented. An invented rule read back sounds stated, and the person nods it through.
16
+ - **Run it in an agent that did not write the requirements.** The writer reads its own gaps as filled. If you wrote them, say so and stop.
17
+ - Owned by a sibling: tracing a rule to its source is vds-strip-invented. The read-back inside vds-story-walk only confirms the walk is whole; this one judges readiness. The built half (commands, events, read models, aggregates, ports) is vds-model-review. Asking for the yes and publishing is vds-publish.
18
+
19
+ ## The review
20
+
21
+ 1. **Read the material.** The capability's requirements, each one's scenarios, the screens, and every open hot spot on them. Order the steps by following each requirement's `start` and `exits` from the first screen. Steps with no screen (an automation, a wait) keep their place in the order. Done when every requirement sits in the story or on a list named "not in the story".
22
+ 2. **Narrate forward.** Tell the story to the person from the first step to each end, in plain words, **no ids**. At each step say what the software must do, then each outcome, failures included: "If the code is wrong, ...". Pause after each step. Storming (Brandolini): speaking the story aloud forces rethinking, and everyone "can (and must)" interrupt the narrator (p94-95). Done when every scenario of every step has been spoken once.
23
+ 3. **Note, do not repair.** Write down every place the person corrects you, hesitates, says "it depends", or you cannot say what happens next. A bumpy telling "is a good sign" (p94). When a talk does not settle, note it as a hot spot to raise and move on: "it won't be forgotten" (p95-96). An answer the person gives goes in the report; the owning skill records it afterwards and vds-ask-or-park marks the hot spot addressed. Done when each note names the step in the person's words.
24
+ 4. **Narrate backward.** Start from each end of the story: the last thing the person sees. Ask what had to happen just before it, and say it. Storming (Brandolini): "no magic gaps" (p96). Use his two prompts: "So [A] is all it takes to have [B]?" and "What needs to happen, to have [C] happen?" (p97). Start from the ends first, then from each step where one stretch of the story closes (p98). Done when every end has been traced back to the first step, or to a noted gap.
25
+ 5. **Run the machine check.** `vds check` (tool: `vds_check`). A problem means not ready; list each one. With no problems it prints "valid" and the open questions. Done when you have the full output.
26
+ 6. **Say each open question in plain words**, using the table below. The check does not list open hot spots, so read those from the capability yourself. Done when every open question about requirements, scenarios or screens, and every open hot spot, has one plain sentence.
27
+ 7. **Ask what blocks, one hot spot at a time.** For each open hot spot: "Can this be built without an answer to: <the question>?" The person's no makes it blocking. Never rank them yourself. Done when every open hot spot is marked blocks or can wait by the person.
28
+ 8. **Give the report** in the format below. Done when every finding has a requirement in plain words and one skill that would fix it, and the person has been told the decision is theirs.
29
+
30
+ If time is short, storming (Brandolini) says to "sacrifice the depth" of both passes (p98). Say in the report which steps were not narrated. A step not narrated is not ready.
31
+
32
+ ## The engine's open questions, in plain words
33
+
34
+ | The check prints | Say to the person | Would fix it |
35
+ |---|---|---|
36
+ | `<story line>: ends on <step>, which shows nothing` | "This path ends without showing the investor anything. What do they see last?" | vds-requirements (a state_view on a screen) |
37
+ | `<command>: one outcome only; what if it fails?` | "We only wrote what happens when this works. What happens when it does not?" | vds-ask-or-park, then vds-scenarios |
38
+ | `<event>: nothing follows it; what happens next?` | "This happens and then the story says nothing more about it. Does anything follow?" | vds-ask-or-park, then vds-requirements |
39
+ | `<screen>: nothing is tracked here; what should analytics send?` | "Other screens send analytics. This one sends none. Is that meant?" | vds-requirements (type analytics) |
40
+ | `REQ-...: no SCN obeys it` | "This rule has no example showing it applied." | vds-scenarios |
41
+ | `no port to ...`, `no port for ...`, `on no Entity`, `on N Aggregates`, `produces no event`, `carries no identity of`, `name is not in the past tense` | do not narrate; list under "For model review" | vds-model-review |
42
+
43
+ An open question never fails the check. It still goes in the report: a person answers it, by a scenario or a screen.
44
+
45
+ ## What makes a requirement not ready
46
+
47
+ | Finding | How you know | Would fix it |
48
+ |---|---|---|
49
+ | A rule or limit with no scenario | the statement names a rule, a failure or a `{limit}` and no scenario shows it | vds-scenarios |
50
+ | A limit nobody gave a value for | an open hot spot says nobody gave the number, or the person cannot say who chose it | vds-ask-or-park, then vds-requirements |
51
+ | An open hot spot that blocks | the person said no in step 7 | vds-ask-or-park |
52
+ | A step that leads nowhere | an "ends on" or "nothing follows" question, or a backward pass that hit a gap | vds-requirements |
53
+ | An outcome nobody could state | you could not say what happens on failure | vds-ask-or-park |
54
+ | A correction | the person said "no, it works like this" | vds-requirements or vds-scenarios |
55
+ | A missing or misplaced step | the person added a step or reordered two | vds-story-walk |
56
+ | A word the person does not use | they repeated the step in other words | vds-language |
57
+ | The whole story is told from the wrong angle | "that is not what this is about" | vds-reframe |
58
+ | A rule the person does not recognise | "who asked for that?" | vds-strip-invented |
59
+
60
+ One finding makes its requirement not ready. One not-ready requirement makes the capability not ready. The verdict line says READY only with no finding and a valid check; otherwise NOT READY, the same two words vds-model-review and vds-publish use. Example mapping reads many open questions on one story as "too much is unknown" (research finding 4); the count goes on the verdict line for that reason.
61
+
62
+ ## The report
63
+
64
+ ```
65
+ Investor auth: NOT READY. 3 of 41 requirements not ready. 2 blocking hot spots.
66
+ Narrated: forward yes, backward yes. Check: valid, 35 open questions.
67
+
68
+ Not ready
69
+ - Send the mobile code: only the working case is written. What if the SMS is not sent?
70
+ Open hot spot, blocks (your answer). Fix with: vds-ask-or-park, then vds-scenarios.
71
+ - Override the limits: no scenario shows the rule applied. Fix with: vds-scenarios.
72
+ - Signing up, consent declined: ends without showing the investor anything.
73
+ Fix with: vds-requirements.
74
+
75
+ Can wait (your answer)
76
+ - "Is there a limit on resends?"
77
+
78
+ For model review
79
+ - 5 open questions about ports.
80
+
81
+ You decide: fix these first, or go to publish as it is and name what you accept.
82
+ Current until the requirements, scenarios or screens are edited.
83
+ ```
84
+
85
+ Wrong, the same finding as a tool would print it and with the fix decided:
86
+
87
+ ```
88
+ - CMD-AUTH--send-code: one outcome only. Added SCN-AUTH-0002-02 for SMS failure.
89
+ ```
90
+
91
+ The person cannot read the first half and never agreed to the second.
92
+
93
+ A hot spot the report quotes is the file's own text:
94
+
95
+ ```yaml
96
+ id: HOT-AUTH--sms-send-fails
97
+ text: "What if Neptune fails to send?"
98
+ "on": CMD-AUTH--send-code
99
+ status: open
100
+ ```
101
+
102
+ ## Symptoms
103
+
104
+ | What you see or hear | Do |
105
+ |---|---|
106
+ | The person says "yes, fine" to every step without a pause | slow down; ask one failure question on the next step: "and if this goes wrong?" |
107
+ | "Wait, go back" | note the step and the words; continue from there |
108
+ | You are about to say an id or a command name | say what the investor does or sees instead |
109
+ | The check prints problems | report not ready with each problem; still narrate, the story may hold more |
110
+ | The person asks "so is it ready?" before the backward pass | say the forward pass is done and the backward pass finds what it hid (p96) |
111
+
112
+ ## Never
113
+
114
+ **Never fix what it finds.** Write no requirement, scenario, screen or hot spot, and change no status. Never mark a hot spot addressed. Never run `vds publish`. Never call the capability decided: the report says ready or not ready, and the person decides.
115
+
116
+ ## Not covered
117
+
118
+ - The spec has no place to store a read-back or its result; the report lives in the conversation and is handed to vds-publish.
119
+ - A hot spot has no field for "blocks"; the mark exists only in the report.
120
+ - Example mapping's readiness vote is known here from the research file only, with no book notes behind it. The vote itself is left out.
121
+ - Brandolini's walk-through is written for a group with several narrators taking turns. With one agent narrating to one person, the relay is dropped. This is VDS's adaptation.
@@ -0,0 +1,142 @@
1
+ ---
2
+ name: vds-scenarios
3
+ description: "Scenario (SCN) of a VDS requirement, written as Given / When / Then in the requirement's .feature file. Use when a requirement has no scenarios, when a rule, limit or failure has no scenario of its own, or when a scenario mixes two rules or reads in technical words. The requirement's statement, type and limits belong to vds-requirements; an example nobody can answer goes to vds-ask-or-park; reading the whole story back belongs to vds-requirements-review."
4
+ ---
5
+
6
+ # Scenarios
7
+
8
+ One scenario proves one rule or one limit, so a test can pass or fail on that rule alone.
9
+
10
+ Use it in requirement discovery, once vds-requirements has drafted the requirement. It hands over the requirement text, any new limit, and the screen's id and title when this is the first requirement on that screen.
11
+ A wrong statement or a missing rule goes to vds-requirements. An example nobody can answer goes to vds-ask-or-park.
12
+
13
+ ## Method
14
+
15
+ 1. **List the rules.** Read the requirement: its statement, its type, the limits it names (`{name}`). Write down each SHALL and SHALL NOT clause and each limit as one line.
16
+ Done when every clause and every `{limit}` in the statement is on the list once.
17
+ 2. **Find one example per rule, in plain words, with the person.** Ask one question at a time: "Say a code was sent six minutes ago. The investor types it. What happens?" Write no Gherkin yet.
18
+ For each rule find the outcome that works, then ask "how can this go wrong?". Write only the failures the person names; an obvious one they did not name is asked about, never written. Each failure is its own example.
19
+ Done when every line of step 1 has at least one example, and every failure the person named has its own.
20
+ 3. **Write the scenarios.** The agent writes the file; the person never writes Gherkin. Use the format below.
21
+ Done when each example from step 2 is one scenario, and no scenario holds two of them.
22
+ 4. **Read each scenario back in one plain sentence, with no ids.** "If a code is more than five minutes old, it is not accepted. Right?"
23
+ Done when the person says yes to each, or the open one is handed to vds-ask-or-park.
24
+ 5. **Save the step.** As soon as the person agreed, save in one change the requirement (its `exits` and `start` included), its scenario file, any new `limits:` entry, and the screen file (id and title) when this is the first requirement on that screen: `vds apply --base <rev>` (MCP: `vds_apply`), then `vds check` (MCP: `vds_check`). Scenarios for a requirement already written go through `vds write <path> --base <rev>` (MCP: `vds_write`).
25
+ Done when the check reports no problem for this requirement. Its "step(s) not modelled yet" lines are expected: vds-slice-blocks turns them into blocks, in this session or a later one.
26
+
27
+ ## The file
28
+
29
+ One `.feature` file per requirement, named by the requirement's id. The check enforces:
30
+
31
+ - Line 1 tags the capability and the requirement: `@CAP-AUTH @REQ-AUTH-0030`.
32
+ - `Feature:` carries the requirement's title, word for word.
33
+ - Each scenario has its own tag `@SCN-<code>-<nnnn>-<nn>`, numbered 01, 02, ... under that requirement.
34
+ - Save a state_change's success scenario with or before its failures: the check refuses a state_change none of whose scenarios names an event in a Then.
35
+ - Every scenario has a Then. Leave Given out when nothing had to happen first (Dilger p206). A state_view has no When (Dilger p63); automation and nfr scenarios may leave When out (p207). A state_change and a translation always name their command in When.
36
+ - An analytics scenario: Given the screen is open, When the action `on` names in plain words, Then `<sends> is sent` with the exact `sends` name, and an And line for anything it must never carry (`Then investor.auth.mobile_entry.submitted is sent` / `And it carries no mobile number`).
37
+
38
+ With the person, word each line plainly and show no id. The saved lines name each command, event and read model by id, as in the example, and the check holds every type but nfr to it: a state_change with no event in a Then, or a state_view with no event in a Given, is refused. Name a block that has no file yet by its id in the person's words (`CMD-AUTH--submit-code`, an event in the past tense); the check lists it as not modelled yet, and vds-slice-blocks writes its file.
39
+
40
+ - A scenario that tests a limit names it in braces and adds the tag of the nfr requirement it obeys: `@SCN-AUTH-0004-02 @REQ-AUTH-0028`.
41
+ - Given names events by id (`EVT-AUTH--code-sent with channel mobile`), `no EVT-...` for an event that has not happened (the start scenario must hold on an empty history: its Given names no event that happened, only `no EVT-...`, a plain fact, or nothing; the check says `the start does not hold on an empty history`), a counted event with a named limit (`Given {lockAfterWrong} EVT-AUTH--code-wrong`; a bare number before an EVT is refused), or a plain fact (`a code was sent {resendAfterSeconds} seconds ago`).
42
+ - Ids in saved lines are names, taken from the person's words in the language (`CMD-NOM--remove-nominee` for "remove a nominee"); vds-slice-blocks writes the files they name. A `shows` or `with` field name is the person's word for it in camelCase.
43
+ - When names one command by id (`CMD-AUTH--submit-code with channel mobile, code wrong`), or nothing for an nfr or automation scenario that needs no action.
44
+ - After `with` come comma-separated pairs: the first word is one of the command's attributes, the rest is its value (`code wrong`, `newMpin same as old`). The check refuses a first word that is not an attribute (`has no field new`). Two examples with the same Given differ in a value here, never in an invented Given.
45
+ - Then names events, a read model (`RM-AUTH--signup-progress shows emailVerified`), or a plain outcome (`the code is not accepted`). Never a screen opening (`Set MPIN opens`): where the user goes next lives only in the requirement's exits.
46
+
47
+ ## Exits and start
48
+
49
+ Both name scenario ids, so this skill words them with the scenarios; they land with the step.
50
+
51
+ - `start: <SCN id>` sits on exactly one requirement per capability: the one for line 1 of the walk. It needs a screen, unless line 1 is an automation or translation set off by an outside event or by time (Brandolini p185, Dilger p41).
52
+ - A tap that only opens another screen ("Add" on the list) is no command: write it as a scenario of the view, with an exit from that scenario to the screen.
53
+ - `exits` holds one `{ scn: <SCN id>, to: <SCR id> }` per scenario after which another screen opens; the exit is the only place that says so. Only a state_change or state_view with a screen has exits. Exits to more than one screen make it a state_view: back to vds-requirements.
54
+ - A flow ends on an exit `{ scn: <SCN id>, to: none }`: write it on the scenario that reaches the end the person named in the walk.
55
+ - An exit to a screen with no file yet is listed as not modelled yet (`exit to unknown SCR-...`); save the screen file (id and title) with it. The check still refuses `no flow reaches exit` once the story from that screen does not reach a `to: none` exit. Its Then names only the outcome (`Then EVT-AUTH--code-sent`); the exit carries the screen.
56
+
57
+ ## A step saved before its model
58
+
59
+ A draft may hold a step whose command, events, read model, or the command that says who acts on a screen, are not written. `vds check` then prints "valid as a draft" and lists them as "step(s) not modelled yet" (`unknown command CMD-...`, `unknown event EVT-...`, `a state_view needs a read model`, `an automation needs a trigger`, `a screen needs an actor, found none`). Writes accept them; publish refuses the capability until vds-slice-blocks has modelled every one.
60
+
61
+ - Never write a block file, or an id the person's words do not carry, to clear a not-modelled line. vds-slice-blocks writes the blocks.
62
+ - The start requirement is saved first: once a capability holds any requirement, exactly one must carry `start` (`exactly one REQ must have start, found 0` is a problem). An nfr with plain lines is saved after it.
63
+ - A step that cannot be saved (a limit value nobody gave, an unanswered question) is written as a hot spot that names the step in its text, through vds-ask-or-park. While the start step is held, no later step of that capability can be saved; each is parked the same way. Nothing stays only in the conversation at the end of a session.
64
+
65
+ ## Rules
66
+
67
+ - **One rejection per value rule.** Each rule on a value object a person's command carries gets its own scenario: When the command with a value that breaks it, Then `it is rejected: <the rule's text>`, and the screen stays open saying so. This is the backend refusing, which a screen check never replaces (Dilger p207, p209). The check asks `no scenario rejects <field>.<part> that breaks "<rule>"` until it exists.
68
+
69
+ - **One rule per scenario.** A test then fails on the one rule that broke (Dilger p169: slices tested as black boxes at their edges).
70
+ - **Given is what already happened.** Dilger: "a set of events that brings the system into a specific state" (p206). Never an action in Given.
71
+ - **When is one action.** "When always defines a command" (Dilger p207). Two actions are two scenarios.
72
+ - **Then is the outcome.** Events that result, or an error when the system was put in an invalid state (Dilger p207).
73
+ - **A failure is an outcome and gets its own scenario.** Dilger's max-three-items rule is its own GWT ending in an error (p209-210); Vernon's service scenarios list success, bogus tenant, wrong username and wrong password apart (p281-283).
74
+ - **Write a limit by its name.** `{codeExpiryMinutes}`, never `5`: the real value may come from the environment or the database.
75
+ - **Use the business's words.** Plain Then lines say what the person said: "a 6-digit code is sent to the mobile by SMS". Dilger: scenarios are rules "anyone in the company will understand easily" (p214).
76
+ - **Do not save on scenarios.** A state change may have "up to 10 or more" (Dilger p63); "don't save on them" (p211).
77
+
78
+ - **Where the methods disagree** (research finding 6). Wynne: writing Gherkin in the session is "generally a bad idea"; map examples live, write afterwards. Dilger (modeling) writes GWTs in the workshop with business stakeholders (p63, p204-206, p211). This skill takes both: plain examples with the person (step 2), Gherkin by the agent in the same session (step 3), a plain read-back (step 4).
79
+
80
+ ## Right and wrong
81
+
82
+ Wrong, two rules in one scenario:
83
+
84
+ ```gherkin
85
+ @SCN-AUTH-0030-03
86
+ Scenario: An old or foreign code
87
+ Given a code was sent more than 5 minutes ago for another purpose
88
+ When CMD-AUTH--submit-code with channel mobile
89
+ Then the code is not accepted
90
+ ```
91
+
92
+ Right, one rule each, the limit by name:
93
+
94
+ ```gherkin
95
+ @SCN-AUTH-0030-03
96
+ Scenario: A code older than {codeExpiryMinutes} minutes
97
+ Given a code was sent more than {codeExpiryMinutes} minutes ago
98
+ When CMD-AUTH--submit-code with channel mobile
99
+ Then the code is not accepted
100
+
101
+ @SCN-AUTH-0030-04
102
+ Scenario: A code from another purpose
103
+ Given EVT-AUTH--code-sent with channel email, purpose VerifyEmail
104
+ When CMD-AUTH--submit-code with channel mobile
105
+ Then the code is not accepted
106
+ ```
107
+
108
+ Wrong is one scenario with `Given the investor taps Resend` and `Then EVT-AUTH--code-resent or HTTP 429 if too early`: an action in Given, the failure folded into the success, a technical Then. Right, success and failure apart:
109
+
110
+ ```gherkin
111
+ @SCN-AUTH-0004-01 @REQ-AUTH-0028
112
+ Scenario: Resend after {resendAfterSeconds} seconds
113
+ Given a code was sent {resendAfterSeconds} seconds ago
114
+ When CMD-AUTH--resend-code with channel mobile
115
+ Then EVT-AUTH--code-resent with channel mobile
116
+
117
+ @SCN-AUTH-0004-02 @REQ-AUTH-0028
118
+ Scenario: No resend before {resendAfterSeconds} seconds
119
+ Given a code was sent fewer than {resendAfterSeconds} seconds ago
120
+ When CMD-AUTH--resend-code with channel mobile
121
+ Then a new code cannot be requested yet
122
+ ```
123
+
124
+ ## Symptoms
125
+
126
+ | What you see or hear | Do |
127
+ |---|---|
128
+ | `no flow reaches exit` and every exit looks right | an event's values differ between the Then that makes it and the Given that reads it (`status success` against `status paid`); use the same words |
129
+ | "and", "or", "unless" inside one Given, When or Then | split into one scenario per rule |
130
+ | a requirement has only the scenario that works | ask "what if it goes wrong?" and add each failure |
131
+ | a number where a limit is declared | write `{name}` and add the limit's requirement tag |
132
+ | Then says a status code, table or field name | rewrite in the words the person used |
133
+ | the person says "it depends" | ask for one concrete case; if nobody knows, vds-ask-or-park |
134
+ | a rule appears that the statement lacks | stop; vds-requirements adds it first |
135
+
136
+ Never put two rules in one scenario.
137
+
138
+ ## Not covered
139
+
140
+ - Scenario Outline, Examples tables and Background: no example file uses them and the notes are silent.
141
+ - Whether a limit scenario must carry the nfr requirement's tag: the check does not require it. An nfr that no scenario tags shows as the open question "<REQ>: no SCN obeys it".
142
+ - Running scenarios as tests and recording evidence: the build phase.
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: vds-slice-blocks
3
+ description: "Command, domain event and read model of one VDS requirement, plus an automation's wiring and a translation's fields. Use when `vds check` lists steps not modelled yet, when a read model attribute or event attribute has no source, when an automation is refused for missing wiring, or when a command lacks who issues it. Which aggregate owns an event is vds-aggregates; typing with value objects is vds-entities-and-values; ports are vds-ports-and-adapters."
4
+ ---
5
+
6
+ # Slice blocks
7
+
8
+ Every field in a slice has a source: a read model attribute comes from an event, an event attribute from a command field, a command field from the screen.
9
+
10
+ Use it on one step at a time, once vds-requirements and vds-scenarios have saved the requirement and its scenarios with the person; that is tactical modeling, by the agent and a developer, in the same session or a later one. The person decides only the requirement and scenarios in plain words and is shown no id; the blocks are the agent's derivation, judged later by vds-model-review and a developer. This skill turns the check's "not modelled yet" lines into blocks. The three slices are Dilger's (modeling): state change, state view, automation (p163); translation is his fourth pattern (p56-59).
11
+ Siblings own the neighbours. A missing or wrong scenario is vds-scenarios. A wrong statement is vds-requirements. A field nobody can source is vds-ask-or-park. Placing an event under an aggregate is vds-aggregates. A new value object is vds-entities-and-values. Judging the whole model is vds-model-review.
12
+
13
+ When you write a file whose whole shape no skill shows, read `../vds-which-skill/FILE-SHAPES.md`.
14
+ ## Method
15
+
16
+ 1. **Take the step.** Run `vds check` (MCP: `vds_check`) and take one step from its "step(s) not modelled yet" list, in the order of the walk. Read its requirement and scenario file.
17
+ Done when there is at least one scenario; with none, stop and hand the step to vds-scenarios.
18
+ 2. **List what the scenarios need.** From each Given, When and Then: what already happened (an event), the one action (a command), what is shown (a read model), with the values the line gives. An id already written counts as exists.
19
+ Done when each is on the list once, marked exists or missing.
20
+ 3. **Work backward from the screen** (Dilger p189-193). List the elements of the requirement's screen from what the person said in the requirement and scenarios. Each element a person sees becomes a read model attribute. Each element a person types or presses becomes a command field.
21
+ Done when every element the person named is an attribute, a field, or a gap.
22
+ 4. **Write the blocks for the requirement's type**, from the table below. A new event is filed in the capability's events until vds-aggregates places it. Type each attribute `string`, `date`, `integer`, `boolean` or `list`, or with a value object that already exists; vds-entities-and-values types the rest later.
23
+ Done when every missing id from step 2 has a file or a wiring field.
24
+ 5. **Run the information completeness check** (Dilger p59-60, p198-200). Trace each read model attribute to the event attribute in its `of`. Trace each event attribute to a command field of the same name. Trace each command field to the screen or to a read model. A field with no source is a gap: hand it to vds-ask-or-park, one question at a time.
25
+ Done when every field has a source or an open hot spot.
26
+ 6. **Say who issues each command and where it goes.** `by:` names the people file of the person who issues it. `to:` names the receiving contexts. A command to another context may add `via: sync` or `via: async` when known, and `reaches:` when that context reaches a person. That context must exist (vds-contexts) and the pair must be on the context map: vds-context-map writes the relation, and it lands in the same change as the command. A missing people file is written by vds-language.
27
+ Done when every command a screen offers has a `by:` naming who the person said acts there.
28
+ 7. **Write the blocks.** Give each block file the id its scenario line already names; a line that names a block in plain words gets its id (format: vds-scenarios, "The file"). Write the blocks with the requirement's wiring in one change: `vds apply --base <rev>` (MCP: `vds_apply`). Then `vds check` (MCP: `vds_check`).
29
+ Done when the check reports no problem and no "not modelled yet" line for this step. A field nobody can source is a hot spot (vds-ask-or-park). Then go back to step 1 for the next step; the skill is done when the check lists no step not modelled yet for this capability, since publish refuses it until then.
30
+
31
+ | Type | Write |
32
+ |---|---|
33
+ | state_change | one command with `does:` (one line in the person's words; the check refuses a command without it); `produces:` lists every event its scenarios' Then lines name. The scenario's When line is the link; the requirement carries no command key |
34
+ | state_view | `read_model:` on the requirement; each attribute a Then `shows` gets `type`, `kind` and `of` |
35
+ | automation | `trigger:` (events in a Given), `read_model:`, `sees:` (attributes it reads), `command:` (named in every When that produces an event) |
36
+ | translation | `external:` (an event with `source: system`), `command:` (ours, `to` our own context) and `event:` (one of ours, no `source`, produced by that command); Given the external event, When the command, Then our event (Dilger p244: a processor sends a command). Later steps name only our event, never the external one. A command sent to an external context also produces an event of ours that says it was sent ("Profile Requested"; Dilger p49) |
37
+ | nfr | no blocks; vds-scenarios saves it |
38
+ | analytics | no blocks; `on:` is already written from the person's words, and its not-modelled line clears when the step that writes that command or event is modelled |
39
+
40
+ ## Rules
41
+
42
+ - **Model only what a screen or a scenario needs.** The check refuses a read model attribute that no state_view Then shows and no automation sees ("nothing shows or sees it").
43
+ - **Every read model value comes from an event.** "The only data you can query is data from previously stored events" (Dilger p53). `kind` is `copy`, `count`, `exists` or `computed`. `copy` reads exactly one `EVT-...attribute`. `computed` needs a `rule` in plain words, limits by `{name}`.
44
+ - **Every event attribute is supplied by the command.** "Commands generally have to provide all data necessary to persist an event" (Dilger p60, p193). The check accepts a command field of the same name, `computed_from: <field>`, `occurredOn`, or, for an event filed under an aggregate, an attribute that aggregate holds: its root's identity or an attribute of an entity in its folder (Vernon p290-291).
45
+ - **Name an event in the past tense** ("Code Sent"; Vernon p289). The check asks about a name that is not.
46
+ - **A list says what it holds** when it holds values: `type: list` with `of: VO-...` or a basic type (Vernon p256).
47
+ - **A command is an intent that produces events.** Every stored event results from a processed command (Dilger p188). Vernon: commands go one way to the command model; queries read the query model, also called read model (p139-140).
48
+ - **An automation's command carries only what it sees.** The processor takes everything from its read model (Dilger p234; p220: every attribute has a clear data path). The check refuses a command field the automation's `sees:` does not list. A value the rule sets itself (a reason, a purpose, a channel, a level) is a read model attribute of kind `computed`, its `rule` saying how it is set and `of` naming the events it reads. A read model that serves one automation is named for the work, Dilger's to-do list (p493): "codes to issue".
49
+ - **A person's command records what the person did.** The system's decision that follows (issue a code, send it) is an automation triggered by that fact (Brandolini p200, Dilger p55). Never let a person's command also produce the system's next fact.
50
+ - **An automation is a state view plus a state change** (Dilger p56). Its trigger is an event, a timer or a user action (Dilger p55). A timer is a domain event with `source: time`. Vernon's nearest word is the event subscriber (p140).
51
+ - **A command with no `by:` is the system's.** The check accepts it; a person's command must also be named by a scenario.
52
+ - **Name blocks in the person's words.** `Submit Code`, `Code Sent`, `Attempt Status`.
53
+
54
+ ## Right and wrong
55
+
56
+ Wrong, a read model attribute with no source event:
57
+
58
+ ```yaml
59
+ attributes:
60
+ - name: email
61
+ type: VO-AUTH--email
62
+ kind: copy
63
+ ```
64
+
65
+ Right, traced to the event attribute that fills it:
66
+
67
+ ```yaml
68
+ attributes:
69
+ - name: email
70
+ type: VO-AUTH--email
71
+ optional: true
72
+ kind: copy
73
+ of: [EVT-AUTH--profile-fetched.email]
74
+ ```
75
+
76
+ Wrong, the event carries `mobile` and the command supplies `phone` ("Mobile Submitted.mobile: no command supplies it"):
77
+
78
+ ```yaml
79
+ id: CMD-AUTH--submit-mobile
80
+ by: PPL-AUTH--investor
81
+ attributes:
82
+ - name: phone
83
+ type: VO-AUTH--mobile
84
+ produces: [EVT-AUTH--mobile-submitted]
85
+ ```
86
+
87
+ Right, an automation's wiring on the requirement:
88
+
89
+ ```yaml
90
+ - id: REQ-AUTH-0002
91
+ type: automation
92
+ read_model: [RM-AUTH--codes-to-send]
93
+ sees: [channel, address, code]
94
+ trigger: [EVT-AUTH--code-sent]
95
+ command: CMD-AUTH--send-code
96
+ ```
97
+
98
+ Send Code carries `channel`, `address` and `code`, and every one is in `sees`. A value the rule sets itself is computed in the read model, as in `RM-AUTH--codes-to-issue`:
99
+
100
+ ```yaml
101
+ - name: purpose
102
+ type: VO-AUTH--purpose
103
+ kind: computed
104
+ of: [EVT-AUTH--mobile-submitted, EVT-AUTH--email-submitted]
105
+ rule: SignIn after Mobile Submitted; VerifyEmail after Email Submitted
106
+ ```
107
+
108
+ ## Symptoms
109
+
110
+ | What you see or hear | Do |
111
+ |---|---|
112
+ | The step has no saved scenarios | stop; vds-scenarios first |
113
+ | "Show the balance too", and no event holds a balance | gap; vds-ask-or-park |
114
+ | An attribute added "in case we need it" | remove it; nothing shows or sees it |
115
+ | "an automation must say what it sees" | add `sees:` from the read model attribute it decides on |
116
+ | `<command> carries <field>, which it does not see` | add the field to the automation's read model (`copy` from an event, or `computed` with the rule) and to `sees:` |
117
+ | "no command supplies it" | add the field to the command, or ask where the value comes from |
118
+ | A command on a screen with no `by:` | ask who presses it; never guess |
119
+ | The scenario names a block wrongly | vds-scenarios changes the scenario |
120
+
121
+ Never model a step whose scenarios are not saved.
122
+
123
+ ## Not covered
124
+
125
+ - `kind: count`: the check accepts it; no example uses it and the notes give no rule for it.
126
+ - Dilger's translation variant that shows an external event directly as a read model (p58): the check requires our own event in a Then.
127
+ - How a person marks screen elements in VDS: spec 0.1 screens hold an id and a title only (Dilger marks them green and blue, p190, p195).
@@ -0,0 +1,128 @@
1
+ ---
2
+ name: vds-story-walk
3
+ description: "Story of a VDS capability: walk it end to end with a person, one line per step, screens named, steps with no screen included. Use when a person starts a new capability, says \"this is what we want, walk it with us\", when a draft has deep steps but no end, or when steps run in the background or on time. Typing one step belongs to vds-requirements; a question nobody can answer to vds-ask-or-park; terms to vds-language."
4
+ ---
5
+
6
+ # Story walk
7
+
8
+ Walk the whole story once, end to end, one line per step, before any step gets deeper; a story seen whole shows its gaps, a deep first step hides them.
9
+
10
+ Use this skill at the start of requirement discovery for one capability, and again when a person adds a new story.
11
+ A working context must exist first. On day 1 vds-contexts opens it; this skill never does.
12
+ Once the walk is read back, each step goes, in order and one at a time, through vds-requirements (the requirement) and vds-scenarios (its scenarios, `exits`, `start`), which saves it as soon as the person agrees. vds-slice-blocks models the saved steps, in this session or a later one.
13
+ When a person cannot answer, or a discussion gets hot, use vds-ask-or-park.
14
+ When a new word or a clash of words appears, use vds-language.
15
+
16
+ When you write a file whose whole shape no skill shows, read `../vds-which-skill/FILE-SHAPES.md`.
17
+ ## Method
18
+
19
+ 1. **Find the home.** Run `vds index` (MCP: `vds_index`). Find the bounded context of kind `ours` this story belongs to.
20
+ If there is none, say: "A working context must exist first." Stop; vds-contexts opens it.
21
+ If one exists, ask: "Today we have <context>, which covers <its capabilities>. Is <this story> part of that, or another part of the business?" Another part: vds-contexts opens a second working context with its day-1 steps 2 and 3. Not sure: keep the existing one and park the question.
22
+ Done when one context is named as the home, and the person agrees.
23
+ 2. **Name who and what for.** Ask who starts the story, then what they have at the end. One question at a time. Write no step yet (Cockburn p17: who acts and what for come first). vds-language records the name of who acts: it asks what the word means, and the people file lands with the first command that names it.
24
+ Done when the person gave one name for who acts and one sentence for the end.
25
+ 3. **Open the capability.** Write the capability with an id, a title in the person's words, and no requirements. Write through `vds write <path> --base <rev>` (MCP: `vds_write`), then run `vds check` (MCP: `vds_check`).
26
+ Done when the check reports no problem for the new capability.
27
+ 4. **Walk forward.** Ask "what happens next?" until the end from step 2 is reached. Write each answer as one line: number, who or what starts it, what happens in the person's words, the screen or "no screen".
28
+ Done when the last line is the end the person named, and no line holds more than one thing that happened.
29
+ 5. **Walk backward.** Start at the last line. For each line ask "what had to happen before this?" Add the step that was missing (Brandolini p96-98: "no magic gaps").
30
+ Done when every line follows from an earlier line or from a fact the person stated.
31
+ 6. **Name the screens.** For each line with a screen, give an id (`SCR-<CODE>-nn`) and a short title in the person's words.
32
+ Done when every screen line has one id and one title, and every other line says "no screen" and why: background, time, or another system.
33
+ 7. **Read the walk back.** Say the whole story in plain words, no ids. Ask "is anything missing or out of order?"
34
+ Done when the person says yes to the whole walk, or each open point went to vds-ask-or-park.
35
+ 8. **Hand it on.** Give vds-requirements the capability id, the home context and every line in order: number, who or what starts it, the person's sentence, the screen id and title or the "no screen" reason. Write no screen file: vds-scenarios saves it with the first requirement on it.
36
+ Done when vds-requirements has every line and the person knows the next step is one line at a time.
37
+
38
+ ## Rules
39
+
40
+ - **Breadth first.** Reach the end before any step gets rules, limits or failures. Cockburn: "Draft this list completely before working out how the system must handle them" (p17). Research finding 1: every method read does this.
41
+ - **One line is one thing that happened.** "Registration" is too coarse; storming (Brandolini) names the right level as domain events, since phase names "filter out too many details" (p78).
42
+ - **The walk starts where the story starts.** A story may start with no person: an outside system's reply or a set time (a nightly job). Then line 1 says "no screen" and why. Otherwise it starts on our first screen. A tap on another capability's screen (Login's Forgot MPIN) is the Given of the start scenario, never a line. A last screen that belongs to another capability (home) is the end: the last line's Then names it, and its exit is `to: none`.
43
+ - **Steps with no screen are steps.** Modeling (Dilger): a step is started by a person, by an event in the system, or by time; some need a UI, others run in the background or reach other systems (p41-42).
44
+ - **A screen is an id and a title.** Detail "should be minimal", the focus is the data (Dilger p50, modeling). The check refuses any other field but `type`, which only an inbox has: `sms_inbox` or `email_inbox`, where a message the person reads arrives. A message sent by SMS and by email is two screens, one per inbox.
45
+ - **Draw the screen when words fail.** Two people in a heated debate meant different things; the screen mockups resolved it "very quickly" (Dilger p43, modeling).
46
+ - **Hot discussions do not stop the walk.** A discussion that does not conclude is parked and the walk moves on (Brandolini p95-96, storming). How to park belongs to vds-ask-or-park.
47
+ - **Narrate aloud.** Speaking the story exposes what is missing; bumpy storytelling "is a good sign" (Brandolini p94, storming). The backward pass usually finds "around 30-40%" more (p98).
48
+ - **Under time pressure, keep the end.** Brandolini sacrifices the depth of the walk to finish it (p98). Never sacrifice reaching the end.
49
+
50
+ ## When the methods disagree
51
+
52
+ Research finding 3. Storming's Big Picture (Brandolini) uses no screens. Modeling (Dilger) uses screens as the best probe with business people (p43, p50).
53
+ This skill names screens, because the person is a product team member and screens are what they point at. The timeline stays the spine: a screen hangs on a step, and a step needs no screen.
54
+
55
+ ## Right and wrong
56
+
57
+ Wrong, the walk deepens step 2 before the story has an end:
58
+
59
+ ```text
60
+ 1. Investor enters the mobile. SCR-AUTH-01 Enter mobile.
61
+ 2. A code is sent. Six digits, valid five minutes, three resends, captcha after two wrong codes...
62
+ ```
63
+
64
+ Right, one line each, steps with no screen included:
65
+
66
+ ```text
67
+ 1. Investor enters the mobile. SCR-AUTH-01 Enter mobile
68
+ 2. A code is sent to the mobile. no screen: background, after 1
69
+ 3. Investor types the code. SCR-AUTH-02 Verify mobile
70
+ 4. Investor gives data consent. SCR-AUTH-04 Data consent
71
+ 5. The profile is fetched. no screen: another system answers
72
+ 6. Investor confirms the email. SCR-AUTH-05 Your email
73
+ 7. A locked mobile opens again. no screen: time, after a set wait
74
+ ```
75
+
76
+ Wrong, requirements written into the capability during the walk:
77
+
78
+ ```yaml
79
+ id: CAP-AUTH
80
+ title: Investor auth
81
+ requirements:
82
+ - id: REQ-AUTH-0001
83
+ title: Accept a mobile number
84
+ ```
85
+
86
+ Right, the capability opened with no requirements:
87
+
88
+ ```yaml
89
+ id: CAP-AUTH
90
+ title: Investor auth
91
+ requirements: []
92
+ ```
93
+
94
+ Wrong, a screen carrying detail (the check refuses it):
95
+
96
+ ```yaml
97
+ id: SCR-AUTH-01
98
+ title: Enter mobile
99
+ fields: [mobile, country code]
100
+ ```
101
+
102
+ Right, id and title only:
103
+
104
+ ```yaml
105
+ id: SCR-AUTH-01
106
+ title: Enter mobile
107
+ ```
108
+
109
+ ## Symptoms
110
+
111
+ | What you hear or see | Do |
112
+ |---|---|
113
+ | "and then it checks the limits, and if..." on one step | write one line; note "rules later"; ask what happens next |
114
+ | the walk stops at a screen with no next step | ask "what does the person have now?"; compare with the end from step 2 |
115
+ | no line says "no screen" | ask what happens in the background, on time, or from another system |
116
+ | "it just happens" between two lines | walk backward from the later line |
117
+ | two people describe one step differently | name the screen and ask each to point at it |
118
+ | `a screen needs an actor, found none` in the steps not modelled yet | expected: who acts on the screen comes from the `by` of its first command; vds-slice-blocks writes it |
119
+ | `vds index` shows no context of kind ours | stop; vds-contexts opens one first |
120
+
121
+ Never deepen one step before the story reaches its end.
122
+
123
+ ## Not covered
124
+
125
+ - Where the walk is stored. Spec 0.1 has no material for an ordered list of steps; the walk lives in the conversation during the session. By the end of the session each line is a saved requirement or a hot spot that names the step in its text (vds-ask-or-park); nothing stays only in the conversation. A saved step whose model is not written needs no hot spot: the check lists it.
126
+ - Which line starts the flow. The check wants exactly one requirement marked `start`; vds-scenarios words it on the requirement of line 1, with `exits`.
127
+ - Branches and failures. They come per step, after the walk (vds-requirements, vds-scenarios).
128
+ - A story that crosses contexts. It is joined by commands or events; the notes give no walk method for it.