kingmadoc 0.3.0.dev15__tar.gz → 0.3.0.dev17__tar.gz

{kingmadoc-0.3.0.dev15 → kingmadoc-0.3.0.dev17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kingmadoc
-Version: 0.3.0.dev15
+Version: 0.3.0.dev17
 Summary: Feature docs for AI coding agents: a plan with C4 diagrams before the code, a verification doc after.
 Project-URL: Homepage, https://github.com/ATkingma/KingmaDoc
 Project-URL: Issues, https://github.com/ATkingma/KingmaDoc/issues

{kingmadoc-0.3.0.dev15 → kingmadoc-0.3.0.dev17}/examples/verify-mode-plan.md

@@ -11,7 +11,7 @@ files_expected: ["src/kingmadoc/cli.py", "src/kingmadoc/verify"]
 |---|---|
 | **Project** | KingmaDoc |
 | **Status** | Draft |
-| **Generated** | 2026-09-28T10:44+00:00 by KingmaDoc 0.1.0.dev50 |
+| **Generated** | 2026-09-28T12:54+00:00 by KingmaDoc 0.1.0.dev50 |
 
 > Generated before implementation. Fill in every _TODO_ and review everything marked
 > _(inferred)_: it comes from the codebase analysis and is a starting point, not the truth.
@@ -97,6 +97,18 @@ _Disabled in `.featuredoc.yml` (`diagrams`)._
 
 _Disabled in `.featuredoc.yml` (`diagrams`)._
 
+## Data flow diagram (Mermaid)
+
+Where the feature's data comes from, what transforms it and where it is stored.
+
+_Disabled in `.featuredoc.yml` (`diagrams`)._
+
+## State diagram (Mermaid)
+
+The states of the object whose lifecycle the feature changes.
+
+_Disabled in `.featuredoc.yml` (`diagrams`)._
+
 ## Open questions
 
 - [ ] _TODO: anything else that must be decided before implementation._
@@ -121,12 +133,12 @@ _Disabled in `.featuredoc.yml` (`diagrams`)._
 | python | 113 |
 | markdown | 28 |
 | jinja | 6 |
+| json | 4 |
 | yaml | 3 |
-| json | 2 |
 | toml | 1 |
 
 <details>
-<summary>File tree (230 files)</summary>
+<summary>File tree (236 files)</summary>
 
 ```text
 KingmaDoc/
@@ -149,6 +161,7 @@ KingmaDoc/
 │   │   ├── 0b0dfdcede5596e1
 │   │   ├── 1b81a71a7607fbf6
 │   │   ├── 2003bed8cb6acdf2
+│   │   ├── 27972aa85104d731
 │   │   ├── 2e00d1a2bca2c453
 │   │   ├── 390efa9697d4e1bf
 │   │   ├── 429e7d227d43fa43
@@ -189,6 +202,7 @@ KingmaDoc/
 │   │   ├── c7c62939844fec2e
 │   │   ├── cc4dfad2dc9d75e2
 │   │   ├── cd82d38bc12deabd
+│   │   ├── d1d54a4302c7359c
 │   │   ├── d6e5d66b09a82b49
 │   │   ├── da39a3ee5e6b4b0d
 │   │   ├── e36626a891f1bf04
@@ -200,6 +214,11 @@ KingmaDoc/
 │   │   └── 14.0.0/
 │   │       └── …
 │   └── .gitignore
+├── .import_linter_cache/
+│   ├── .gitignore
+│   ├── 3516dc116b537972f63cac11b7ceb5fffe116986.data.json
+│   ├── CACHEDIR.TAG
+│   └── kingmadoc.meta.json
 ├── docs/
 │   ├── conventions.md
 │   ├── index.md

{kingmadoc-0.3.0.dev15 → kingmadoc-0.3.0.dev17}/skill/SKILL.md

@@ -52,8 +52,8 @@ brackets); ignore the file if it is absent:
 - `analyzer.exclude_dirs` [`.git`, `node_modules`, `.venv`, `venv`, `__pycache__`,
   `dist`, `build`, `*.egg-info`, tool caches], `analyzer.max_files` [`5000`],
   `analyzer.tree_depth` [`3`].
-- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`]: which sections get
-  a diagram.
+- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`, `data_flow`, `state`]:
+  which sections get a diagram.
 - `diagrams_png` [`embed`]: `embed`, `file` or `off`; see
   [Rendering](reference/diagram-rules.md#rendering).
 - `language` [`en`]: language of fixed sentences, notes and captions (headings stay English).
@@ -145,7 +145,8 @@ the diagrams, but never beyond what the user said or the code shows.
   vague REQ or invented ones. Under each: `Verified by: <test, test case or command>`
   (or `_TODO_`).
 - **Planned changes**: per `files_expected` path what changes and why (the "how" of
-  answer 4), one to three lines, no code blocks. Risks and assumptions may add code
+  answer 4), one to three lines, no code blocks; where a code snippet would help
+  (a new method, a changed signature), draw a small `classDiagram` with just those members. Risks and assumptions may add code
   findings marked _(inferred)_.
 - **Generated**: the real system time (`date -Iminutes`).
 - External systems: those from answer 3, plus systems the code demonstrably uses

{kingmadoc-0.3.0.dev15 → kingmadoc-0.3.0.dev17}/skill/codex.md

@@ -52,8 +52,8 @@ brackets); ignore the file if it is absent:
 - `analyzer.exclude_dirs` [`.git`, `node_modules`, `.venv`, `venv`, `__pycache__`,
   `dist`, `build`, `*.egg-info`, tool caches], `analyzer.max_files` [`5000`],
   `analyzer.tree_depth` [`3`].
-- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`]: which sections get
-  a diagram.
+- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`, `data_flow`, `state`]:
+  which sections get a diagram.
 - `diagrams_png` [`embed`]: `embed`, `file` or `off`; see
   [Rendering](#rendering).
 - `language` [`en`]: language of fixed sentences, notes and captions (headings stay English).
@@ -145,7 +145,8 @@ the diagrams, but never beyond what the user said or the code shows.
   vague REQ or invented ones. Under each: `Verified by: <test, test case or command>`
   (or `_TODO_`).
 - **Planned changes**: per `files_expected` path what changes and why (the "how" of
-  answer 4), one to three lines, no code blocks. Risks and assumptions may add code
+  answer 4), one to three lines, no code blocks; where a code snippet would help
+  (a new method, a changed signature), draw a small `classDiagram` with just those members. Risks and assumptions may add code
   findings marked _(inferred)_.
 - **Generated**: the real system time (`date -Iminutes`).
 - External systems: those from answer 3, plus systems the code demonstrably uses
@@ -238,7 +239,7 @@ Show the user the path, the number of deviations, and any failing check.
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
-  - `classDiagram`, `erDiagram` and `flowchart` have no `title` line; put frontmatter
+  - `classDiagram`, `erDiagram`, `flowchart` and `stateDiagram-v2` have no `title` line; put frontmatter
     before the diagram type instead: `---`, `title: "<text>"`, `---` (quote the
     title: an unquoted `:` breaks the YAML and the render);
   - every element has a quoted label: `Person(alias, "Label", "Description")`,
@@ -284,10 +285,73 @@ C4Context
     Rel(shop, sendgrid, "Sends email via")
 ```
 
-`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`]
+`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`,
+`data_flow`, `state`]
 selects the diagrams. If one is disabled, keep its section and replace the diagram with
 this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
+## Data flow diagram
+
+Yourdon/DeMarco style (Gane-Sarson draws the same with other shapes) as a `flowchart LR`:
+
+- **External entity** (person or system outside the scope): rectangle `user[User]`.
+- **Process** (transforms data): circle with a number and a verb phrase,
+  `p1((1. Validate order))`.
+- **Data store** (data at rest): `d1[("D1 Orders")]`, named with a noun, numbered `D1`.
+- **Data flow**: an arrow labelled with the **data** (a noun: `order`, `invoice`), never an
+  action; every arrow has a label.
+- Rules: every flow starts or ends at a process (never entity → entity, entity → store
+  or store → store); every process has at least one input and one output (no black
+  holes, no miracles) and its output can be made from its input (no grey holes); a
+  store is both written and read somewhere, or it is outside the feature; no control
+  flow, loops or decisions (that is the sequence or state diagram).
+- **Levels**: the Context diagram is level 0; this is level 1 for the feature. The flows
+  in and out must balance with the Context diagram (same external systems, same data).
+- Mark new or changed processes and flows _(inferred)_ or from the answers, as usual.
+
+```mermaid
+---
+title: "Data flow: place order"
+---
+flowchart LR
+    user[Customer] -- order --> p1((1. Validate order))
+    p1 -- valid order --> p2((2. Store order))
+    p2 -- order --> d1[("D1 Orders")]
+    p2 -- confirmation --> user
+```
+
+## State diagram
+
+UML 2 state machine as `stateDiagram-v2`, for the one object whose lifecycle the feature
+changes (an order, a job, a document):
+
+- **States** are conditions, named with an adjective or past participle (`Draft`,
+  `Paid`, `Cancelled`), never an action (`Pay`).
+- One initial `[*] --> <state>` (unlabelled); final `<state> --> [*]` only where the
+  object's life really ends.
+- **Transitions**: `A --> B : event [guard] / action`; event, guard and action are each
+  optional, but every transition has at least the event. Guards leaving the same state
+  on the same event must not overlap; use `state check <<choice>>` for a decision.
+- Every state is reachable from the initial state, and every non-final state has a way
+  out (no dead ends unless intended).
+- Composite states (`state Active { … }`) only when they remove repeated transitions;
+  keep it to about ten states.
+- New states and transitions from the answers or "Planned changes"; existing ones from
+  the code are _(inferred)_.
+
+```mermaid
+---
+title: "States: Order"
+---
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Placed : submit [cart not empty]
+    Placed --> Paid : payment received / send receipt
+    Placed --> Cancelled : cancel
+    Paid --> [*]
+    Cancelled --> [*]
+```
+
 ## Rendering
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
@@ -305,7 +369,8 @@ or `off` (no image; the ` ```mermaid ` block stays in the document).
   `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
 1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
-   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`,
+   `data-flow`, `state`) and run:
    `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed
@@ -373,7 +438,8 @@ files_expected: [<existing files or folders the user said will change>]
 ## Planned changes
 
 - `<path from files_expected>`: <what changes and why, one to three lines, no code
-  blocks; the "how" from answer 4, or> _TODO: what changes here and why._
+  blocks (a small classDiagram with the changed members instead of a snippet); the "how"
+  from answer 4, or> _TODO: what changes here and why._
 
 ## Requirements
 
@@ -421,6 +487,18 @@ The classes this feature touches and their direct collaborators.
 
 <sequenceDiagram of the flow after the change>
 
+## Data flow diagram (Mermaid)
+
+Where the feature's data comes from, what transforms it and where it is stored.
+
+<flowchart DFD, or _Not applicable: <reason>._>
+
+## State diagram (Mermaid)
+
+The states of <the object whose lifecycle the feature changes>.
+
+<stateDiagram-v2, or _Not applicable: <reason>._>
+
 ## Open questions
 
 - [ ] <each unanswered clarifying question>
@@ -468,6 +546,9 @@ Omit "**Answered while planning**" when nothing was answered.
   result, with real classes as participants and real method names as messages;
   `activate`/`deactivate` for nested calls, `alt`/`opt` for branches. In **Current**,
   a `Note` marks where it goes wrong.
+- **Data flow diagram** and **State diagram**: rules in
+  [diagram-rules.md](diagram-rules.md#data-flow-diagram); _Not applicable: <reason>._ when
+  the feature moves no data between parts, or has no object with a lifecycle.
 - **Open changes**: when an uncommitted change or stash touches the feature, also list
   it under Open questions.
 - `language` in `.featuredoc.yml` [`en`]: headings stay English (the CLI's), but fixed

{kingmadoc-0.3.0.dev15 → kingmadoc-0.3.0.dev17}/skill/copilot.md

@@ -52,8 +52,8 @@ brackets); ignore the file if it is absent:
 - `analyzer.exclude_dirs` [`.git`, `node_modules`, `.venv`, `venv`, `__pycache__`,
   `dist`, `build`, `*.egg-info`, tool caches], `analyzer.max_files` [`5000`],
   `analyzer.tree_depth` [`3`].
-- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`]: which sections get
-  a diagram.
+- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`, `data_flow`, `state`]:
+  which sections get a diagram.
 - `diagrams_png` [`embed`]: `embed`, `file` or `off`; see
   [Rendering](#rendering).
 - `language` [`en`]: language of fixed sentences, notes and captions (headings stay English).
@@ -145,7 +145,8 @@ the diagrams, but never beyond what the user said or the code shows.
   vague REQ or invented ones. Under each: `Verified by: <test, test case or command>`
   (or `_TODO_`).
 - **Planned changes**: per `files_expected` path what changes and why (the "how" of
-  answer 4), one to three lines, no code blocks. Risks and assumptions may add code
+  answer 4), one to three lines, no code blocks; where a code snippet would help
+  (a new method, a changed signature), draw a small `classDiagram` with just those members. Risks and assumptions may add code
   findings marked _(inferred)_.
 - **Generated**: the real system time (`date -Iminutes`).
 - External systems: those from answer 3, plus systems the code demonstrably uses
@@ -238,7 +239,7 @@ Show the user the path, the number of deviations, and any failing check.
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
-  - `classDiagram`, `erDiagram` and `flowchart` have no `title` line; put frontmatter
+  - `classDiagram`, `erDiagram`, `flowchart` and `stateDiagram-v2` have no `title` line; put frontmatter
     before the diagram type instead: `---`, `title: "<text>"`, `---` (quote the
     title: an unquoted `:` breaks the YAML and the render);
   - every element has a quoted label: `Person(alias, "Label", "Description")`,
@@ -284,10 +285,73 @@ C4Context
     Rel(shop, sendgrid, "Sends email via")
 ```
 
-`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`]
+`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`,
+`data_flow`, `state`]
 selects the diagrams. If one is disabled, keep its section and replace the diagram with
 this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
+## Data flow diagram
+
+Yourdon/DeMarco style (Gane-Sarson draws the same with other shapes) as a `flowchart LR`:
+
+- **External entity** (person or system outside the scope): rectangle `user[User]`.
+- **Process** (transforms data): circle with a number and a verb phrase,
+  `p1((1. Validate order))`.
+- **Data store** (data at rest): `d1[("D1 Orders")]`, named with a noun, numbered `D1`.
+- **Data flow**: an arrow labelled with the **data** (a noun: `order`, `invoice`), never an
+  action; every arrow has a label.
+- Rules: every flow starts or ends at a process (never entity → entity, entity → store
+  or store → store); every process has at least one input and one output (no black
+  holes, no miracles) and its output can be made from its input (no grey holes); a
+  store is both written and read somewhere, or it is outside the feature; no control
+  flow, loops or decisions (that is the sequence or state diagram).
+- **Levels**: the Context diagram is level 0; this is level 1 for the feature. The flows
+  in and out must balance with the Context diagram (same external systems, same data).
+- Mark new or changed processes and flows _(inferred)_ or from the answers, as usual.
+
+```mermaid
+---
+title: "Data flow: place order"
+---
+flowchart LR
+    user[Customer] -- order --> p1((1. Validate order))
+    p1 -- valid order --> p2((2. Store order))
+    p2 -- order --> d1[("D1 Orders")]
+    p2 -- confirmation --> user
+```
+
+## State diagram
+
+UML 2 state machine as `stateDiagram-v2`, for the one object whose lifecycle the feature
+changes (an order, a job, a document):
+
+- **States** are conditions, named with an adjective or past participle (`Draft`,
+  `Paid`, `Cancelled`), never an action (`Pay`).
+- One initial `[*] --> <state>` (unlabelled); final `<state> --> [*]` only where the
+  object's life really ends.
+- **Transitions**: `A --> B : event [guard] / action`; event, guard and action are each
+  optional, but every transition has at least the event. Guards leaving the same state
+  on the same event must not overlap; use `state check <<choice>>` for a decision.
+- Every state is reachable from the initial state, and every non-final state has a way
+  out (no dead ends unless intended).
+- Composite states (`state Active { … }`) only when they remove repeated transitions;
+  keep it to about ten states.
+- New states and transitions from the answers or "Planned changes"; existing ones from
+  the code are _(inferred)_.
+
+```mermaid
+---
+title: "States: Order"
+---
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Placed : submit [cart not empty]
+    Placed --> Paid : payment received / send receipt
+    Placed --> Cancelled : cancel
+    Paid --> [*]
+    Cancelled --> [*]
+```
+
 ## Rendering
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
@@ -305,7 +369,8 @@ or `off` (no image; the ` ```mermaid ` block stays in the document).
   `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
 1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
-   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`,
+   `data-flow`, `state`) and run:
    `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed
@@ -373,7 +438,8 @@ files_expected: [<existing files or folders the user said will change>]
 ## Planned changes
 
 - `<path from files_expected>`: <what changes and why, one to three lines, no code
-  blocks; the "how" from answer 4, or> _TODO: what changes here and why._
+  blocks (a small classDiagram with the changed members instead of a snippet); the "how"
+  from answer 4, or> _TODO: what changes here and why._
 
 ## Requirements
 
@@ -421,6 +487,18 @@ The classes this feature touches and their direct collaborators.
 
 <sequenceDiagram of the flow after the change>
 
+## Data flow diagram (Mermaid)
+
+Where the feature's data comes from, what transforms it and where it is stored.
+
+<flowchart DFD, or _Not applicable: <reason>._>
+
+## State diagram (Mermaid)
+
+The states of <the object whose lifecycle the feature changes>.
+
+<stateDiagram-v2, or _Not applicable: <reason>._>
+
 ## Open questions
 
 - [ ] <each unanswered clarifying question>
@@ -468,6 +546,9 @@ Omit "**Answered while planning**" when nothing was answered.
   result, with real classes as participants and real method names as messages;
   `activate`/`deactivate` for nested calls, `alt`/`opt` for branches. In **Current**,
   a `Note` marks where it goes wrong.
+- **Data flow diagram** and **State diagram**: rules in
+  [diagram-rules.md](diagram-rules.md#data-flow-diagram); _Not applicable: <reason>._ when
+  the feature moves no data between parts, or has no object with a lifecycle.
 - **Open changes**: when an uncommitted change or stash touches the feature, also list
   it under Open questions.
 - `language` in `.featuredoc.yml` [`en`]: headings stay English (the CLI's), but fixed

{kingmadoc-0.3.0.dev15 → kingmadoc-0.3.0.dev17}/skill/cursor.md

@@ -53,8 +53,8 @@ brackets); ignore the file if it is absent:
 - `analyzer.exclude_dirs` [`.git`, `node_modules`, `.venv`, `venv`, `__pycache__`,
   `dist`, `build`, `*.egg-info`, tool caches], `analyzer.max_files` [`5000`],
   `analyzer.tree_depth` [`3`].
-- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`]: which sections get
-  a diagram.
+- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`, `data_flow`, `state`]:
+  which sections get a diagram.
 - `diagrams_png` [`embed`]: `embed`, `file` or `off`; see
   [Rendering](#rendering).
 - `language` [`en`]: language of fixed sentences, notes and captions (headings stay English).
@@ -146,7 +146,8 @@ the diagrams, but never beyond what the user said or the code shows.
   vague REQ or invented ones. Under each: `Verified by: <test, test case or command>`
   (or `_TODO_`).
 - **Planned changes**: per `files_expected` path what changes and why (the "how" of
-  answer 4), one to three lines, no code blocks. Risks and assumptions may add code
+  answer 4), one to three lines, no code blocks; where a code snippet would help
+  (a new method, a changed signature), draw a small `classDiagram` with just those members. Risks and assumptions may add code
   findings marked _(inferred)_.
 - **Generated**: the real system time (`date -Iminutes`).
 - External systems: those from answer 3, plus systems the code demonstrably uses
@@ -239,7 +240,7 @@ Show the user the path, the number of deviations, and any failing check.
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
-  - `classDiagram`, `erDiagram` and `flowchart` have no `title` line; put frontmatter
+  - `classDiagram`, `erDiagram`, `flowchart` and `stateDiagram-v2` have no `title` line; put frontmatter
     before the diagram type instead: `---`, `title: "<text>"`, `---` (quote the
     title: an unquoted `:` breaks the YAML and the render);
   - every element has a quoted label: `Person(alias, "Label", "Description")`,
@@ -285,10 +286,73 @@ C4Context
     Rel(shop, sendgrid, "Sends email via")
 ```
 
-`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`]
+`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`,
+`data_flow`, `state`]
 selects the diagrams. If one is disabled, keep its section and replace the diagram with
 this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
+## Data flow diagram
+
+Yourdon/DeMarco style (Gane-Sarson draws the same with other shapes) as a `flowchart LR`:
+
+- **External entity** (person or system outside the scope): rectangle `user[User]`.
+- **Process** (transforms data): circle with a number and a verb phrase,
+  `p1((1. Validate order))`.
+- **Data store** (data at rest): `d1[("D1 Orders")]`, named with a noun, numbered `D1`.
+- **Data flow**: an arrow labelled with the **data** (a noun: `order`, `invoice`), never an
+  action; every arrow has a label.
+- Rules: every flow starts or ends at a process (never entity → entity, entity → store
+  or store → store); every process has at least one input and one output (no black
+  holes, no miracles) and its output can be made from its input (no grey holes); a
+  store is both written and read somewhere, or it is outside the feature; no control
+  flow, loops or decisions (that is the sequence or state diagram).
+- **Levels**: the Context diagram is level 0; this is level 1 for the feature. The flows
+  in and out must balance with the Context diagram (same external systems, same data).
+- Mark new or changed processes and flows _(inferred)_ or from the answers, as usual.
+
+```mermaid
+---
+title: "Data flow: place order"
+---
+flowchart LR
+    user[Customer] -- order --> p1((1. Validate order))
+    p1 -- valid order --> p2((2. Store order))
+    p2 -- order --> d1[("D1 Orders")]
+    p2 -- confirmation --> user
+```
+
+## State diagram
+
+UML 2 state machine as `stateDiagram-v2`, for the one object whose lifecycle the feature
+changes (an order, a job, a document):
+
+- **States** are conditions, named with an adjective or past participle (`Draft`,
+  `Paid`, `Cancelled`), never an action (`Pay`).
+- One initial `[*] --> <state>` (unlabelled); final `<state> --> [*]` only where the
+  object's life really ends.
+- **Transitions**: `A --> B : event [guard] / action`; event, guard and action are each
+  optional, but every transition has at least the event. Guards leaving the same state
+  on the same event must not overlap; use `state check <<choice>>` for a decision.
+- Every state is reachable from the initial state, and every non-final state has a way
+  out (no dead ends unless intended).
+- Composite states (`state Active { … }`) only when they remove repeated transitions;
+  keep it to about ten states.
+- New states and transitions from the answers or "Planned changes"; existing ones from
+  the code are _(inferred)_.
+
+```mermaid
+---
+title: "States: Order"
+---
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Placed : submit [cart not empty]
+    Placed --> Paid : payment received / send receipt
+    Placed --> Cancelled : cancel
+    Paid --> [*]
+    Cancelled --> [*]
+```
+
 ## Rendering
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
@@ -306,7 +370,8 @@ or `off` (no image; the ` ```mermaid ` block stays in the document).
   `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
 1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
-   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`,
+   `data-flow`, `state`) and run:
    `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed
@@ -374,7 +439,8 @@ files_expected: [<existing files or folders the user said will change>]
 ## Planned changes
 
 - `<path from files_expected>`: <what changes and why, one to three lines, no code
-  blocks; the "how" from answer 4, or> _TODO: what changes here and why._
+  blocks (a small classDiagram with the changed members instead of a snippet); the "how"
+  from answer 4, or> _TODO: what changes here and why._
 
 ## Requirements
 
@@ -422,6 +488,18 @@ The classes this feature touches and their direct collaborators.
 
 <sequenceDiagram of the flow after the change>
 
+## Data flow diagram (Mermaid)
+
+Where the feature's data comes from, what transforms it and where it is stored.
+
+<flowchart DFD, or _Not applicable: <reason>._>
+
+## State diagram (Mermaid)
+
+The states of <the object whose lifecycle the feature changes>.
+
+<stateDiagram-v2, or _Not applicable: <reason>._>
+
 ## Open questions
 
 - [ ] <each unanswered clarifying question>
@@ -469,6 +547,9 @@ Omit "**Answered while planning**" when nothing was answered.
   result, with real classes as participants and real method names as messages;
   `activate`/`deactivate` for nested calls, `alt`/`opt` for branches. In **Current**,
   a `Note` marks where it goes wrong.
+- **Data flow diagram** and **State diagram**: rules in
+  [diagram-rules.md](diagram-rules.md#data-flow-diagram); _Not applicable: <reason>._ when
+  the feature moves no data between parts, or has no object with a lifecycle.
 - **Open changes**: when an uncommitted change or stash touches the feature, also list
   it under Open questions.
 - `language` in `.featuredoc.yml` [`en`]: headings stay English (the CLI's), but fixed

{kingmadoc-0.3.0.dev15 → kingmadoc-0.3.0.dev17}/skill/explaining-code/SKILL.md

@@ -41,7 +41,8 @@ Rules:
   stops it; never a proposal.
 - **Picture, caption, table. No stories.** Every figure has a numbered caption
   (`**Figure 3.** …`, no gaps) and at most three sentences; a table decodes it. Never
-  describe a diagram in prose, never paste code as an image, no filler.
+  describe a diagram in prose, never paste code as an image, no filler. Where a code
+  snippet would explain a class or signature, draw a small UML class diagram instead.
 - **Zoom in step by step,** one small diagram per level (at most about fifteen elements).
 - **Every figure follows its model's notation** ([reference/c4-model.md](reference/c4-model.md),
   [reference/models.md](reference/models.md)) and passes its checklist: a title, a

{kingmadoc-0.3.0.dev15 → kingmadoc-0.3.0.dev17}/skill/reference/diagram-rules.md

@@ -8,7 +8,7 @@
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
-  - `classDiagram`, `erDiagram` and `flowchart` have no `title` line; put frontmatter
+  - `classDiagram`, `erDiagram`, `flowchart` and `stateDiagram-v2` have no `title` line; put frontmatter
     before the diagram type instead: `---`, `title: "<text>"`, `---` (quote the
     title: an unquoted `:` breaks the YAML and the render);
   - every element has a quoted label: `Person(alias, "Label", "Description")`,
@@ -54,10 +54,73 @@ C4Context
     Rel(shop, sendgrid, "Sends email via")
 ```
 
-`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`]
+`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`,
+`data_flow`, `state`]
 selects the diagrams. If one is disabled, keep its section and replace the diagram with
 this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
+## Data flow diagram
+
+Yourdon/DeMarco style (Gane-Sarson draws the same with other shapes) as a `flowchart LR`:
+
+- **External entity** (person or system outside the scope): rectangle `user[User]`.
+- **Process** (transforms data): circle with a number and a verb phrase,
+  `p1((1. Validate order))`.
+- **Data store** (data at rest): `d1[("D1 Orders")]`, named with a noun, numbered `D1`.
+- **Data flow**: an arrow labelled with the **data** (a noun: `order`, `invoice`), never an
+  action; every arrow has a label.
+- Rules: every flow starts or ends at a process (never entity → entity, entity → store
+  or store → store); every process has at least one input and one output (no black
+  holes, no miracles) and its output can be made from its input (no grey holes); a
+  store is both written and read somewhere, or it is outside the feature; no control
+  flow, loops or decisions (that is the sequence or state diagram).
+- **Levels**: the Context diagram is level 0; this is level 1 for the feature. The flows
+  in and out must balance with the Context diagram (same external systems, same data).
+- Mark new or changed processes and flows _(inferred)_ or from the answers, as usual.
+
+```mermaid
+---
+title: "Data flow: place order"
+---
+flowchart LR
+    user[Customer] -- order --> p1((1. Validate order))
+    p1 -- valid order --> p2((2. Store order))
+    p2 -- order --> d1[("D1 Orders")]
+    p2 -- confirmation --> user
+```
+
+## State diagram
+
+UML 2 state machine as `stateDiagram-v2`, for the one object whose lifecycle the feature
+changes (an order, a job, a document):
+
+- **States** are conditions, named with an adjective or past participle (`Draft`,
+  `Paid`, `Cancelled`), never an action (`Pay`).
+- One initial `[*] --> <state>` (unlabelled); final `<state> --> [*]` only where the
+  object's life really ends.
+- **Transitions**: `A --> B : event [guard] / action`; event, guard and action are each
+  optional, but every transition has at least the event. Guards leaving the same state
+  on the same event must not overlap; use `state check <<choice>>` for a decision.
+- Every state is reachable from the initial state, and every non-final state has a way
+  out (no dead ends unless intended).
+- Composite states (`state Active { … }`) only when they remove repeated transitions;
+  keep it to about ten states.
+- New states and transitions from the answers or "Planned changes"; existing ones from
+  the code are _(inferred)_.
+
+```mermaid
+---
+title: "States: Order"
+---
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Placed : submit [cart not empty]
+    Placed --> Paid : payment received / send receipt
+    Placed --> Cancelled : cancel
+    Paid --> [*]
+    Cancelled --> [*]
+```
+
 ## Rendering
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
@@ -75,7 +138,8 @@ or `off` (no image; the ` ```mermaid ` block stays in the document).
   `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
 1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
-   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`,
+   `data-flow`, `state`) and run:
    `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed