dflow-sdd-ddd 0.14.0 → 0.16.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 (100) hide show
  1. package/CHANGELOG.md +915 -0
  2. package/CONTRIBUTING.md +11 -1
  3. package/README.en.md +160 -212
  4. package/README.md +93 -147
  5. package/TEMPLATE-COVERAGE.md +13 -6
  6. package/TEMPLATE-LANGUAGE-GLOSSARY.md +15 -1
  7. package/bin/dflow.js +90 -4
  8. package/docs/closeout-check.en.md +204 -0
  9. package/docs/closeout-check.md +204 -0
  10. package/docs/commands.en.md +112 -0
  11. package/docs/commands.md +103 -0
  12. package/docs/doctor-uncertainty.en.md +212 -0
  13. package/docs/doctor-uncertainty.md +212 -0
  14. package/docs/evaluating-dflow.en.md +29 -11
  15. package/docs/evaluating-dflow.md +8 -6
  16. package/docs/release-versioning-policy.md +6 -0
  17. package/docs/upgrading.en.md +196 -0
  18. package/docs/upgrading.md +197 -0
  19. package/docs/using-with-claude-code.en.md +13 -4
  20. package/docs/using-with-claude-code.md +13 -4
  21. package/docs/using-with-codex.en.md +13 -4
  22. package/docs/using-with-codex.md +13 -4
  23. package/docs/using-with-github-copilot.en.md +13 -4
  24. package/docs/using-with-github-copilot.md +13 -4
  25. package/lib/closeout-check.js +690 -0
  26. package/lib/doc-shapes.json +1195 -0
  27. package/lib/doctor-checks.js +2500 -24
  28. package/lib/init.js +2861 -143
  29. package/lib/render-diagrams.js +1474 -0
  30. package/lib/render.js +865 -49
  31. package/package.json +2 -2
  32. package/templates/brownfield/references/drift-verification.md +4 -0
  33. package/templates/brownfield/references/finish-feature-flow.md +648 -98
  34. package/templates/brownfield/references/finish-feature-follow-up.md +60 -0
  35. package/templates/brownfield/references/finish-feature-minimal-host.md +427 -0
  36. package/templates/brownfield/references/finish-feature-post-hoc-hotfix.md +95 -0
  37. package/templates/brownfield/references/finish-feature-record-correction.md +45 -0
  38. package/templates/brownfield/references/git-integration.md +205 -26
  39. package/templates/brownfield/references/init-project-flow.md +23 -3
  40. package/templates/brownfield/references/modify-existing-flow.md +439 -88
  41. package/templates/brownfield/references/modify-existing-follow-up.md +122 -0
  42. package/templates/brownfield/references/modify-existing-post-hoc-hotfix.md +200 -0
  43. package/templates/brownfield/references/new-feature-flow.md +110 -37
  44. package/templates/brownfield/references/new-phase-flow.md +59 -9
  45. package/templates/brownfield/references/pr-review-checklist.md +328 -10
  46. package/templates/brownfield/scaffolding/AI-AGENT-GUIDE.md +151 -34
  47. package/templates/brownfield/scaffolding/CLAUDE-md-snippet.md +1 -1
  48. package/templates/brownfield/scaffolding/Git-principles-gitflow.md +85 -8
  49. package/templates/brownfield/scaffolding/Git-principles-trunk.md +88 -10
  50. package/templates/brownfield/scaffolding/_conventions.md +50 -28
  51. package/templates/brownfield/scaffolding/_overview.md +1 -0
  52. package/templates/brownfield/templates/_index.md +158 -10
  53. package/templates/brownfield/templates/analysis.md +79 -0
  54. package/templates/brownfield/templates/behavior.md +1 -0
  55. package/templates/brownfield/templates/context-definition.md +1 -0
  56. package/templates/brownfield/templates/context-map.md +2 -1
  57. package/templates/brownfield/templates/glossary.md +1 -0
  58. package/templates/brownfield/templates/lightweight-spec.md +154 -11
  59. package/templates/brownfield/templates/models.md +1 -0
  60. package/templates/brownfield/templates/phase-spec.md +9 -1
  61. package/templates/brownfield/templates/rules.md +1 -0
  62. package/templates/brownfield/templates/tech-debt.md +1 -0
  63. package/templates/common/references/ddd-modeling-guide.md +33 -16
  64. package/templates/{greenfield → common}/references/dflow-feedback-flow.md +2 -1
  65. package/templates/common/references/flow-rationale-registry.md +146 -0
  66. package/templates/common/skill/SKILL.md +13 -11
  67. package/templates/greenfield/references/drift-verification.md +4 -0
  68. package/templates/greenfield/references/finish-feature-flow.md +639 -100
  69. package/templates/greenfield/references/finish-feature-follow-up.md +60 -0
  70. package/templates/greenfield/references/finish-feature-minimal-host.md +383 -0
  71. package/templates/greenfield/references/finish-feature-post-hoc-hotfix.md +95 -0
  72. package/templates/greenfield/references/finish-feature-record-correction.md +45 -0
  73. package/templates/greenfield/references/git-integration.md +193 -26
  74. package/templates/greenfield/references/init-project-flow.md +23 -3
  75. package/templates/greenfield/references/modify-existing-flow.md +395 -87
  76. package/templates/greenfield/references/modify-existing-follow-up.md +104 -0
  77. package/templates/greenfield/references/modify-existing-post-hoc-hotfix.md +200 -0
  78. package/templates/greenfield/references/new-feature-flow.md +116 -35
  79. package/templates/greenfield/references/new-phase-flow.md +58 -9
  80. package/templates/greenfield/references/pr-review-checklist.md +311 -8
  81. package/templates/greenfield/scaffolding/AI-AGENT-GUIDE.md +146 -32
  82. package/templates/greenfield/scaffolding/CLAUDE-md-snippet.md +5 -2
  83. package/templates/greenfield/scaffolding/Git-principles-gitflow.md +84 -8
  84. package/templates/greenfield/scaffolding/Git-principles-trunk.md +94 -14
  85. package/templates/greenfield/scaffolding/_conventions.md +50 -28
  86. package/templates/greenfield/scaffolding/_overview.md +6 -2
  87. package/templates/greenfield/templates/_index.md +145 -10
  88. package/templates/greenfield/templates/aggregate-design.md +1 -0
  89. package/templates/greenfield/templates/analysis.md +79 -0
  90. package/templates/greenfield/templates/behavior.md +1 -0
  91. package/templates/greenfield/templates/context-definition.md +1 -0
  92. package/templates/greenfield/templates/context-map.md +2 -1
  93. package/templates/greenfield/templates/events.md +4 -1
  94. package/templates/greenfield/templates/glossary.md +1 -0
  95. package/templates/greenfield/templates/lightweight-spec.md +154 -11
  96. package/templates/greenfield/templates/models.md +1 -0
  97. package/templates/greenfield/templates/phase-spec.md +9 -1
  98. package/templates/greenfield/templates/rules.md +1 -0
  99. package/templates/greenfield/templates/tech-debt.md +1 -0
  100. package/templates/brownfield/references/dflow-feedback-flow.md +0 -251
@@ -2,10 +2,13 @@
2
2
  id: BUG-{NUMBER} # bug-type T2 only; a non-bug T2 (lightweight-{date}-{slug}.md) carries no id — the filename identifies it
3
3
  title: {簡述問題}
4
4
  status: in-progress # in-progress | completed
5
- bounded-context: {ContextName}
5
+ bounded-context: {ContextName} # or `none` when the host has no meaningful bounded context
6
6
  created: {YYYY-MM-DD}
7
- branch: bugfix/BUG-{NUMBER}-{slug}
7
+ branch: bugfix/BUG-{NUMBER}-{slug} # must equal the host _index.md `branch:` value (that field is authoritative) — a non-bug T2 therefore carries the host's feature/{SPEC-ID}-{slug} branch
8
+ # hotfix-branch: hotfix/{name} # ADD (uncomment) only for a post-hoc T2 — references/modify-existing-flow.md Step 1.8. The already-merged emergency fix's own branch, kept even after that branch was deleted.
9
+ # hotfix-identity: {PR / incident / tracker reference} # ADD only for a post-hoc T2 — the source the asserted `reconciled ({merged-hotfix-hash})` identity rests on; an uncited hash blocks closeout. Keep it adjacent to hotfix-branch.
8
10
  ---
11
+ <!-- dflow-shape: greenfield/lightweight-spec.md 1 — keep this line: dflow doctor reads it -->
9
12
 
10
13
  <!--
11
14
  Template note (for AI):
@@ -16,7 +19,7 @@ Template note (for AI):
16
19
  - T1 Heavy → use templates/phase-spec.md instead
17
20
  - T2 Light → THIS template; produces an independent file
18
21
  - T3 Trivial → no independent file; just one inline row in _index.md
19
- Lightweight Changes with a tag like [cosmetic] / [text] / [format]
22
+ Lightweight Changes with a tag like [cosmetic] / [text] / [appearance]
20
23
 
21
24
  Instance file location and naming:
22
25
  Place the instantiated file inside the corresponding feature directory:
@@ -24,17 +27,136 @@ Template note (for AI):
24
27
  or, when the lightweight change is a tracked bug:
25
28
  dflow/specs/features/active/{SPEC-ID}-{slug}/BUG-{NUMBER}-{slug}.md
26
29
 
27
- If the change is a standalone bug not yet attached to any existing
28
- feature, /dflow:bug-fix must first create a feature directory (with a
29
- minimal _index.md) before placing the lightweight-spec instance inside.
30
- This keeps the structure invariant: every spec file lives under some
31
- feature directory.
32
-
33
- After finalizing this lightweight-spec, AI must:
30
+ A standalone change not yet attached to any existing feature needs a
31
+ minimal host feature directory (with a minimal _index.md) to hold this
32
+ instance — the structure invariant is that every spec file lives under
33
+ some feature directory. That minimal host has a defined create / record /
34
+ close-out lifecycle: references/modify-existing-flow.md Step 1.7 for a
35
+ standalone change, or its Step 1.6 minimal variant when the change is a
36
+ follow-up on a completed feature; a post-hoc hotfix reaches the same
37
+ lifecycle through Step 1.8, which resolves its linkage to one of those two.
38
+ Follow that lifecycle rather than
39
+ improvising one, and do not leave an empty host behind.
40
+
41
+ No-BR variants (a T2 that carries no BR delta at all):
42
+ The default shape below is the classic BR-delta form (Behavior Delta with
43
+ BR-NN entries + Root Cause). It stays valid and is the right shape whenever
44
+ the change does have a BR delta.
45
+ A change can reach T2 carrying no BR delta at all. These families describe
46
+ how to write a spec the cascade has ALREADY placed at T2; none of them
47
+ makes a change T2, and none of them overrides an earlier cascade step. Do
48
+ NOT invent a BR-NN and do NOT write a fake root cause. Pick the matching
49
+ family, put its BR line under `## Behavior Delta` in place of the
50
+ ADDED / MODIFIED / REMOVED / RENAMED subsections, and replace `## Root Cause`
51
+ with that family's evidence section:
52
+
53
+ (a) presentation — any copy / appearance change T3 would not take: a sweep
54
+ beyond the local unit, a whole-screen rewrite, a local edit to
55
+ high-consequence content (a security warning, a password hint,
56
+ consent text, a payment or legal notice), or one that changes what the output *means* (an
57
+ instruction reversed from "company email only" to "any email", a
58
+ danger / status colour flipped)
59
+ BR line: `BR: none — presentation`
60
+ Evidence: `## Output Footprint` — which screens / outputs the change
61
+ actually reaches, and **what it now says or signals** whenever the
62
+ meaning moved or the content is high-consequence
63
+ (b) contract change — non-breaking structured-log / export / API / event
64
+ field or semantics change
65
+ BR line: `BR: none — contract change`
66
+ Evidence: `## Contract Delta`, including a `**Downstream consumers**:`
67
+ line naming who reads it
68
+ (c) operational — CVE / security dependency bump, or a behavior-preserving
69
+ refactor on an auth / payment / resilience / compliance path
70
+ BR line: `BR: none — operational`
71
+ Evidence: `## Operational Rationale`, including a `**Trace**:` line
72
+ (advisory / ticket / audit reference; a self-initiated case with nothing
73
+ to cite records `**Trace**: none — self-initiated` — the line is never
74
+ omitted)
75
+ (d) performance — a runtime performance / resource / SLA change, including
76
+ one no audience perceives
77
+ BR line: `BR: none — performance`
78
+ Evidence: `## Performance Delta`, including an
79
+ `**SLA / resource context**:` line
80
+ (e) implementation defect — the rule is unchanged; the implementation was
81
+ wrong
82
+ BR lines: `BR Delta: none — implementation defect` AND
83
+ `Governing BR-IDs: {BR-NN, BR-NN | none}`
84
+ Evidence: keep `## Problem` / `## Root Cause` / `## Fix Approach`, plus a
85
+ regression task
86
+ (f) intentional change — a planned, non-normative functional or interaction
87
+ change with no rule in the catalogue (default tab, redirect target,
88
+ ordering, a presentation / interaction control)
89
+ BR line: `BR: none — intentional change`
90
+ Evidence: `## Change Rationale`, including `**Before**` / `**After**`
91
+ behavior lines and a `**Regression**:` line
92
+
93
+ More than one family can fit — a behaviour-preserving payment-retry refactor
94
+ that also shifts runtime SLA is both (c) and (d). Do not pick one and drop
95
+ the other's evidence: write the BR line of the family with the higher
96
+ consequence (order: (e) → (c) → (b) → (d) → (f) → (a)) and include **every**
97
+ matching family's evidence section. A reviewer needs the operational trace
98
+ and the SLA context, not whichever one the author chose first.
99
+
100
+ Family (e) keeps two fields on purpose: "no BR delta" is not "no governing
101
+ rule". `Governing BR-IDs:` lists the rules the defect sits under, so the rule
102
+ the fix answers to stays traceable; a genuinely uncatalogued defect records
103
+ `none`. Never collapse the pair into a single `BR: none`.
104
+ Family (f) is non-normative only. A new normative constraint (permission /
105
+ eligibility / threshold / approval / required outcome) is a new BR — take it
106
+ back to the cascade rather than filing it here, even when the catalogue has
107
+ no BR-ID for it yet.
108
+
109
+ Legacy shapes are accepted, never migrated. Readers and gates take both the
110
+ classic BR-delta form and the older single `BR:` line bug form (written
111
+ before the `BR Delta:` / `Governing BR-IDs:` split) as they are; leave
112
+ existing specs alone and use the shapes above for new ones.
113
+
114
+ After drafting this lightweight-spec, AI must:
34
115
  1. Add an outbound-link row to the feature's _index.md Lightweight Changes table
35
- (Tier = T2; description includes the link to this file)
116
+ (Tier = T2; description includes the link to this file).
117
+ TIMING — do this BEFORE the implementation commit, not after. On a
118
+ minimal (zero-phase) host the row must already be inside checkpoint 1,
119
+ and closeout's allow-list admits only the row's `Commit` cell
120
+ afterwards, so a row added later blocks. "Drafting", not the Step 1.7
121
+ "Finalize + close" sub-step, which runs after that commit and only fills
122
+ the cell in.
36
123
  2. Refresh the feature's _index.md Current BR Snapshot table to reflect
37
124
  any BR ADDED / MODIFIED / REMOVED / RENAMED in this lightweight-spec
125
+ (a no-BR family has nothing to refresh — leave the snapshot as it is)
126
+
127
+ Implementation Paths:
128
+ The `## Implementation Paths` section below names the source paths this
129
+ change touches. Paths, not a diff — enough to compare a commit against.
130
+ REQUIRED on a minimal (zero-phase) host — standalone or follow-up:
131
+ `/dflow:finish-feature` asserts that checkpoint 1's diff touches them, so a
132
+ spec declaring none leaves that check nothing to compare and a missing
133
+ declaration BLOCKS closeout rather than passing vacuously
134
+ (references/finish-feature-flow.md Step 1; written at
135
+ references/modify-existing-flow.md Step 1.7, before the first commit).
136
+ On a HOSTED T2 — one recorded under a phase-bearing feature — closeout runs
137
+ no such check and nothing blocks on it, so the section is good practice
138
+ there, not a gate. Do not read the "blocks" above as applying to a hosted
139
+ spec; it does not.
140
+ Keep the paths OUT of `## Implementation Tasks`: the completion checklist
141
+ may collapse or remove that section once the tasks are done, and the paths
142
+ must still be readable at closeout.
143
+
144
+ Post-hoc hotfix fields — T2 only, references/modify-existing-flow.md Step 1.8:
145
+ `hotfix-branch:` records the already-merged emergency fix's own branch
146
+ (keep the value even when that branch has been deleted); `hotfix-identity:`
147
+ cites what the identity claim rests on — the PR, incident, or tracker
148
+ reference. Both live in the frontmatter, adjacent, so the trace and the
149
+ thing it rests on stay together. They ship COMMENTED OUT: an ordinary
150
+ (non-post-hoc) T2 leaves them commented and they are inert. Uncomment them
151
+ only in post-hoc mode — never fill them with `none`, and never leave them
152
+ live on an ordinary T2, which would claim a hotfix branch that never
153
+ existed on a record nothing else re-checks.
154
+ In post-hoc mode `## Implementation Paths` names the paths the MERGED
155
+ HOTFIX touched: closeout compares them against the `reconciled ({hash})`
156
+ commit, and blocks if this host's own documentation commit touches any of
157
+ them (that would be re-implementation, not reconciliation). Closeout tests
158
+ plausibility only and blocks on an uncited hash; the identity itself is
159
+ confirmed by references/pr-review-checklist.md.
38
160
  -->
39
161
 
40
162
  # {問題簡述}
@@ -46,6 +168,8 @@ Template note (for AI):
46
168
  ## Behavior Delta
47
169
 
48
170
  > 精簡 delta 格式:bug fix 多數只需 MODIFIED;若確實是新增規則可改用 ADDED、移除用 REMOVED、改名用 RENAMED。多項變更時照類別列。
171
+ >
172
+ > 完全沒有 BR delta 時改用 no-BR 家族形(見檔首 Template note 的 No-BR variants):本段只留該家族的 BR 行(例如 `BR: none — presentation`;家族 (e) 是 `BR Delta:` + `Governing BR-IDs:` 兩行),不要為了填滿 delta 子段捏造 BR-NN。
49
173
 
50
174
  ### MODIFIED - behavior modified in this fix
51
175
  #### Rule: BR-NN {規則名稱}
@@ -58,12 +182,31 @@ Template note (for AI):
58
182
 
59
183
  ## Root Cause
60
184
 
185
+ > classic BR-delta 形與 no-BR 家族 (e) 保留本段;家族 (a)–(d)、(f) 以該家族的 evidence 段取代本段(見檔首 Template note 的 No-BR variants)。
186
+
61
187
  {為什麼會這樣?是邏輯錯誤?資料問題?還是需求理解有誤?}
62
188
 
63
189
  ## Fix Approach
64
190
 
65
191
  {怎麼修?有沒有抽到 Domain 層的機會?}
66
192
 
193
+ ## Implementation Paths
194
+
195
+ > The source paths this change touches — paths, not a diff, at a granularity a
196
+ > commit can be compared against. **Required on a minimal (zero-phase) host**:
197
+ > `/dflow:finish-feature` asserts checkpoint 1's diff touches them, and
198
+ > declaring none **blocks** closeout instead of passing. On a **hosted** T2 —
199
+ > recorded under a phase-bearing feature — closeout runs no such check, so this
200
+ > is good practice there rather than a gate. Do not move the list into
201
+ > `## Implementation Tasks`: that section may be collapsed once the tasks are
202
+ > done, and these paths must still be readable at closeout.
203
+ >
204
+ > **Post-hoc hotfix (Step 1.8)**: list what the **already-merged hotfix**
205
+ > touched. This host's own documentation commit must **not** touch any of them.
206
+
207
+ - `{src/path/touched}`
208
+ - `{src/another/path/touched}`
209
+
67
210
  <!-- dflow:section implementation-tasks -->
68
211
  ## Implementation Tasks
69
212
 
@@ -1,3 +1,4 @@
1
+ <!-- dflow-shape: greenfield/models.md 1 — keep this line: dflow doctor reads it -->
1
2
  <!-- Seeded by Dflow. -->
2
3
  <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ;/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
3
4
 
@@ -7,6 +7,7 @@ created: {YYYY-MM-DD}
7
7
  author: {developer-name}
8
8
  branch: feature/{SPEC-ID}-{slug}
9
9
  ---
10
+ <!-- dflow-shape: greenfield/phase-spec.md 1 — keep this line: dflow doctor reads it -->
10
11
 
11
12
  <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ;/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
12
13
 
@@ -17,7 +18,14 @@ Template note (for AI):
17
18
  This is the **phase-spec** template - one phase-spec captures one full
18
19
  "Kickoff -> Domain -> Design -> Build -> Verify" cycle inside a feature directory.
19
20
  A feature can have 1..N phase-specs; the feature-level dashboard lives in
20
- the sibling `_index.md` (see templates/_index.md). The instance file name is
21
+ the sibling `_index.md` (see templates/_index.md).
22
+ Exception — a **minimal (zero-phase) host** has **0**: it records a small
23
+ standalone or follow-up change and is defined by carrying no phase-spec at
24
+ all (references/modify-existing-flow.md Step 1.7, or its Step 1.6 minimal
25
+ variant). Such a host never uses this template. If you are about to create a
26
+ phase-spec for one, stop: adding a phase makes it a phase-bearing feature,
27
+ and closeout will then check it as one.
28
+ The instance file name is
21
29
  `phase-spec-YYYY-MM-DD-{slug}.md` placed at
22
30
  `dflow/specs/features/active/{SPEC-ID}-{slug}/`.
23
31
 
@@ -1,3 +1,4 @@
1
+ <!-- dflow-shape: greenfield/rules.md 1 — keep this line: dflow doctor reads it -->
1
2
  <!-- Seeded by Dflow. -->
2
3
  <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ;/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
3
4
 
@@ -1,3 +1,4 @@
1
+ <!-- dflow-shape: greenfield/tech-debt.md 1 — keep this line: dflow doctor reads it -->
1
2
  <!-- Seeded by Dflow. -->
2
3
  <!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ;/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
3
4
 
@@ -1,251 +0,0 @@
1
- # Dflow Feedback Draft Flow
2
-
3
- `/dflow:report-dflow-feedback` helps the developer turn a Dflow problem or
4
- improvement observed during real project work into a high-quality upstream
5
- feedback draft. The draft is rendered **field by field to match the upstream
6
- GitHub issue form**, so the developer pastes each field with no reformatting.
7
-
8
- This flow is **not** a project feature workflow and does not change the
9
- application being built. It is a standalone governance/support flow for Dflow
10
- itself.
11
-
12
- ## Hard Boundaries
13
-
14
- - Do not submit anything to GitHub automatically.
15
- - Do not run `gh issue create`, `gh pr create`, `git push`, or any networked
16
- submission command from this flow.
17
- - Do not expose private project details, business rules, customer data,
18
- secrets, tokens, internal URLs, or proprietary source snippets.
19
- - Always show the draft to the developer before anything leaves the local
20
- machine.
21
- - If the developer later asks to submit through GitHub CLI, stop and treat that
22
- as a separate explicit task with fresh permission and environment checks.
23
-
24
- ## Trigger Conditions
25
-
26
- Enter this flow when:
27
-
28
- - The developer explicitly runs `/dflow:report-dflow-feedback`.
29
- - The developer says the Dflow process, template, generated file, or docs seem
30
- wrong or improvable.
31
- - The AI notices a clear contradiction or gap in Dflow guidance and asks:
32
- "This looks like a possible Dflow upstream issue. Should I draft feedback for
33
- you to review?"
34
-
35
- Do not interrupt normal development for minor preference differences. If the
36
- observation is speculative, ask before drafting.
37
-
38
- ## Output Location
39
-
40
- Write the draft to:
41
-
42
- ```text
43
- dflow/feedback/dflow-feedback-YYYY-MM-DD-{slug}.md
44
- ```
45
-
46
- Create `dflow/feedback/` if it does not exist. The file is local project
47
- working material; the developer decides whether to copy it into a GitHub issue,
48
- turn it into a PR, or discard it.
49
-
50
- ## Step 1: Classify the Feedback
51
-
52
- Classify the feedback as one of the following. Each maps to one upstream issue
53
- form (see "Upstream Issue Forms" below):
54
-
55
- | Classification | Upstream issue form | Title prefix |
56
- |---|---|---|
57
- | Bug report | Bug report | `[Bug]: ` |
58
- | Workflow change request | Workflow change request | `[Workflow]: ` |
59
- | Documentation feedback | Documentation feedback | `[Docs]: ` |
60
- | Question / unclear usage | Question | `[Question]: ` |
61
- | Maintainer release/process feedback | Workflow change request (closest form; the upstream repo disables blank issues) | `[Workflow]: ` |
62
-
63
- Capture:
64
-
65
- - Observed during which flow or command
66
- - Affected Dflow track: Greenfield, Brownfield, both, or unknown
67
- - Affected area: CLI, generated template, scaffolding, skill reference,
68
- tutorial, README/docs, release/governance
69
- - Whether the issue blocks current project work
70
-
71
- ## Step 2: Capture Evidence Safely
72
-
73
- Collect only the evidence needed to explain the Dflow issue.
74
-
75
- Allowed evidence:
76
-
77
- - Dflow command name
78
- - Dflow version if known
79
- - Template or reference file name
80
- - Generic project type, such as "existing brownfield app" or "legacy batch-processing system"
81
- - Minimal paraphrased symptom
82
- - Short sanitized snippets from Dflow-owned files
83
-
84
- Avoid:
85
-
86
- - Internal business rules
87
- - Customer or tenant names
88
- - Private repository names or URLs
89
- - Secrets, tokens, credentials, or auth headers
90
- - Long proprietary code snippets
91
- - Full logs containing private paths or environment data
92
-
93
- ## Step 3: Redaction Pass
94
-
95
- Before writing any field content, run a redaction check and use it as your own
96
- gate. Confirm there are:
97
-
98
- - No secrets, tokens, credentials, or auth headers
99
- - No customer, tenant, or private organization names
100
- - No proprietary business rules beyond a sanitized paraphrase
101
- - No private repository URLs or internal hostnames
102
- - No long proprietary source snippets
103
-
104
- The draft ends with a short submitter self-check (Step 5); leave its items
105
- unchecked unless the developer explicitly confirms them.
106
-
107
- ## Step 4: Resolve the Target Issue Form
108
-
109
- Submit upstream at: **https://github.com/weilung/dflow-sdd-ddd/issues/new/choose**
110
-
111
- Resolve the field schema for the chosen form using this priority chain (it
112
- avoids any network dependency at draft time):
113
-
114
- 1. **Live upstream schema** — if you can read the target repo's
115
- `.github/ISSUE_TEMPLATE/*.yml` (for example you are working inside a
116
- `dflow-sdd-ddd` checkout), use that file; it is authoritative.
117
- 2. **Bundled field map** — otherwise use the field map in "Upstream Issue
118
- Forms" below. It is a snapshot of the upstream forms shipped with Dflow.
119
- 3. **Generic fallback** — only if the feedback matches none of the forms, use
120
- Step 6.
121
-
122
- ## Step 5: Render the Draft Field by Field
123
-
124
- Write the draft as one block per upstream field, in the form's field order, so
125
- the developer copies each block straight into the matching field.
126
-
127
- Per field-type rules:
128
-
129
- | Field type | How to render |
130
- |---|---|
131
- | `input` | One short line inside a fenced block. |
132
- | `textarea` | Multi-line content inside a fenced block. If the field sets a non-empty `render:` attribute, do **not** add an extra fence (the form already code-blocks it). |
133
- | `dropdown` | State the **recommended option** plus a one-line reason. If `multiple: true`, list the chosen options. |
134
- | `checkboxes` | List every option as `- [x]` / `- [ ]`; mark any option whose schema sets `required: true`. |
135
- | `markdown` | Display-only text in the form — produce **no** field block for it. |
136
- | upload / attachment | Emit a manual step ("drag the relevant screenshot / log into the issue editor"); do not try to handle the file. |
137
-
138
- Always start with a **Title** block: the form's title prefix plus a concise
139
- one-line summary. GitHub pre-fills the prefix in the title box; the developer
140
- can paste the full line over it.
141
-
142
- Attribute handling: bring `value` / `default` in as starting content; surface
143
- `placeholder` as a hint; append "(required)" to the block heading when the
144
- field sets `required: true`.
145
-
146
- **Fence escaping (dynamic).** Wrap each field's content in a backtick fence
147
- whose length is *(longest backtick run in the content) + 1*, minimum 3. The
148
- fence is only a local wrapper so the content survives in the draft file — when
149
- pasting into the issue form, the developer copies the **inner** content, not
150
- the fence. State this in the draft.
151
-
152
- Draft skeleton:
153
-
154
- ````markdown
155
- # {Issue form name} — {short title}
156
-
157
- ## Where to submit
158
-
159
- https://github.com/weilung/dflow-sdd-ddd/issues/new/choose → choose
160
- **"{Issue form name}"**. (A GitHub account is all you need; the title is
161
- auto-prefixed with `{prefix}`.)
162
-
163
- ## Title
164
-
165
- ```
166
- {prefix}{concise one-line summary}
167
- ```
168
-
169
- ## {Field label} (required)
170
-
171
- ```
172
- {field content; copy the inner text only, not this fence}
173
- ```
174
-
175
- ... one block per field, in form order ...
176
-
177
- ## Before you submit (submitter self-check)
178
-
179
- - [ ] Any real file names / customer names / internal project code names to redact?
180
- - [ ] If you attach screenshots, do they show sensitive content (internal systems, tokens, passwords)?
181
- - [ ] Is opening a public issue within what your organization allows?
182
- ````
183
-
184
- Keep the draft **submitter-facing only**: no maintainer tracking notes, no
185
- internal references, no "for your friend / for yourself" audience switches.
186
-
187
- ## Upstream Issue Forms (bundled field map)
188
-
189
- > Snapshot of the `weilung/dflow-sdd-ddd` issue forms. If the live `.yml` is
190
- > reachable (Step 4 priority 1), prefer it. Resync this map when the upstream
191
- > forms change.
192
-
193
- ### Bug report — title `[Bug]: `
194
-
195
- | Field | Type | Required | Notes |
196
- |---|---|---|---|
197
- | Dflow version | input | yes | placeholder `0.2.0` |
198
- | Node.js version | input | yes | from `node --version` |
199
- | Project track | dropdown | yes | Greenfield / Brownfield / Not sure |
200
- | Command or workflow | textarea | yes | the command or `/dflow:*` workflow used |
201
- | Expected behavior | textarea | yes | |
202
- | Actual behavior | textarea | yes | include relevant output |
203
- | Reproduction steps | textarea | yes | smallest steps that reproduce |
204
- | Additional context | textarea | no | screenshots / snippets / environment |
205
-
206
- ### Workflow change request — title `[Workflow]: `
207
-
208
- | Field | Type | Required | Notes |
209
- |---|---|---|---|
210
- | Problem | textarea | yes | |
211
- | Proposed change | textarea | yes | |
212
- | Affected track | dropdown | yes | Greenfield / Brownfield / Both / Not sure |
213
- | Affected area | checkboxes | no | CLI command / Generated template / Generated scaffolding / Skill workflow guidance / Tutorial or examples / Documentation only |
214
- | Compatibility risk | textarea | yes | |
215
- | Alternatives considered | textarea | no | |
216
-
217
- ### Documentation feedback — title `[Docs]: `
218
-
219
- | Field | Type | Required | Notes |
220
- |---|---|---|---|
221
- | Affected page or file | input | yes | placeholder `README.md` |
222
- | Reader goal | textarea | yes | what you were trying to understand or do |
223
- | What was confusing? | textarea | yes | the missing, unclear, or misleading part |
224
- | Suggested improvement | textarea | no | optional wording or structure |
225
-
226
- ### Question — title `[Question]: `
227
-
228
- | Field | Type | Required | Notes |
229
- |---|---|---|---|
230
- | Project type | dropdown | yes | New project / Existing project / Not sure |
231
- | Dflow track you are considering | dropdown | yes | Greenfield / Brownfield / Not sure |
232
- | What are you trying to do? | textarea | yes | the workflow or decision you need help with |
233
- | Project context | textarea | no | framework, team workflow, AI agent, constraints |
234
-
235
- ## Step 6: Generic Fallback
236
-
237
- Use this only when the feedback matches none of the forms above. The upstream
238
- repo disables blank issues, so direct the developer to pick the closest form at
239
- `https://github.com/weilung/dflow-sdd-ddd/issues/new/choose` and adapt. Emit
240
- two paste-ready blocks — a `Title` and a `Body` — plus the URL. Do **not** fall
241
- back to a generic `## Problem` / `## Evidence` Markdown draft.
242
-
243
- ## Step 7: Present Submission Options
244
-
245
- After writing the draft, name the draft file path and whether any submitter
246
- self-check items remain unchecked, then summarize the options:
247
-
248
- - Open the chosen issue form and paste each field block.
249
- - Discard the draft if it was only a local observation.
250
-
251
- Do not submit anything automatically.