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.
- package/CHANGELOG.md +915 -0
- package/CONTRIBUTING.md +11 -1
- package/README.en.md +160 -212
- package/README.md +93 -147
- package/TEMPLATE-COVERAGE.md +13 -6
- package/TEMPLATE-LANGUAGE-GLOSSARY.md +15 -1
- package/bin/dflow.js +90 -4
- package/docs/closeout-check.en.md +204 -0
- package/docs/closeout-check.md +204 -0
- package/docs/commands.en.md +112 -0
- package/docs/commands.md +103 -0
- package/docs/doctor-uncertainty.en.md +212 -0
- package/docs/doctor-uncertainty.md +212 -0
- package/docs/evaluating-dflow.en.md +29 -11
- package/docs/evaluating-dflow.md +8 -6
- package/docs/release-versioning-policy.md +6 -0
- package/docs/upgrading.en.md +196 -0
- package/docs/upgrading.md +197 -0
- package/docs/using-with-claude-code.en.md +13 -4
- package/docs/using-with-claude-code.md +13 -4
- package/docs/using-with-codex.en.md +13 -4
- package/docs/using-with-codex.md +13 -4
- package/docs/using-with-github-copilot.en.md +13 -4
- package/docs/using-with-github-copilot.md +13 -4
- package/lib/closeout-check.js +690 -0
- package/lib/doc-shapes.json +1195 -0
- package/lib/doctor-checks.js +2500 -24
- package/lib/init.js +2861 -143
- package/lib/render-diagrams.js +1474 -0
- package/lib/render.js +865 -49
- package/package.json +2 -2
- package/templates/brownfield/references/drift-verification.md +4 -0
- package/templates/brownfield/references/finish-feature-flow.md +648 -98
- package/templates/brownfield/references/finish-feature-follow-up.md +60 -0
- package/templates/brownfield/references/finish-feature-minimal-host.md +427 -0
- package/templates/brownfield/references/finish-feature-post-hoc-hotfix.md +95 -0
- package/templates/brownfield/references/finish-feature-record-correction.md +45 -0
- package/templates/brownfield/references/git-integration.md +205 -26
- package/templates/brownfield/references/init-project-flow.md +23 -3
- package/templates/brownfield/references/modify-existing-flow.md +439 -88
- package/templates/brownfield/references/modify-existing-follow-up.md +122 -0
- package/templates/brownfield/references/modify-existing-post-hoc-hotfix.md +200 -0
- package/templates/brownfield/references/new-feature-flow.md +110 -37
- package/templates/brownfield/references/new-phase-flow.md +59 -9
- package/templates/brownfield/references/pr-review-checklist.md +328 -10
- package/templates/brownfield/scaffolding/AI-AGENT-GUIDE.md +151 -34
- package/templates/brownfield/scaffolding/CLAUDE-md-snippet.md +1 -1
- package/templates/brownfield/scaffolding/Git-principles-gitflow.md +85 -8
- package/templates/brownfield/scaffolding/Git-principles-trunk.md +88 -10
- package/templates/brownfield/scaffolding/_conventions.md +50 -28
- package/templates/brownfield/scaffolding/_overview.md +1 -0
- package/templates/brownfield/templates/_index.md +158 -10
- package/templates/brownfield/templates/analysis.md +79 -0
- package/templates/brownfield/templates/behavior.md +1 -0
- package/templates/brownfield/templates/context-definition.md +1 -0
- package/templates/brownfield/templates/context-map.md +2 -1
- package/templates/brownfield/templates/glossary.md +1 -0
- package/templates/brownfield/templates/lightweight-spec.md +154 -11
- package/templates/brownfield/templates/models.md +1 -0
- package/templates/brownfield/templates/phase-spec.md +9 -1
- package/templates/brownfield/templates/rules.md +1 -0
- package/templates/brownfield/templates/tech-debt.md +1 -0
- package/templates/common/references/ddd-modeling-guide.md +33 -16
- package/templates/{greenfield → common}/references/dflow-feedback-flow.md +2 -1
- package/templates/common/references/flow-rationale-registry.md +146 -0
- package/templates/common/skill/SKILL.md +13 -11
- package/templates/greenfield/references/drift-verification.md +4 -0
- package/templates/greenfield/references/finish-feature-flow.md +639 -100
- package/templates/greenfield/references/finish-feature-follow-up.md +60 -0
- package/templates/greenfield/references/finish-feature-minimal-host.md +383 -0
- package/templates/greenfield/references/finish-feature-post-hoc-hotfix.md +95 -0
- package/templates/greenfield/references/finish-feature-record-correction.md +45 -0
- package/templates/greenfield/references/git-integration.md +193 -26
- package/templates/greenfield/references/init-project-flow.md +23 -3
- package/templates/greenfield/references/modify-existing-flow.md +395 -87
- package/templates/greenfield/references/modify-existing-follow-up.md +104 -0
- package/templates/greenfield/references/modify-existing-post-hoc-hotfix.md +200 -0
- package/templates/greenfield/references/new-feature-flow.md +116 -35
- package/templates/greenfield/references/new-phase-flow.md +58 -9
- package/templates/greenfield/references/pr-review-checklist.md +311 -8
- package/templates/greenfield/scaffolding/AI-AGENT-GUIDE.md +146 -32
- package/templates/greenfield/scaffolding/CLAUDE-md-snippet.md +5 -2
- package/templates/greenfield/scaffolding/Git-principles-gitflow.md +84 -8
- package/templates/greenfield/scaffolding/Git-principles-trunk.md +94 -14
- package/templates/greenfield/scaffolding/_conventions.md +50 -28
- package/templates/greenfield/scaffolding/_overview.md +6 -2
- package/templates/greenfield/templates/_index.md +145 -10
- package/templates/greenfield/templates/aggregate-design.md +1 -0
- package/templates/greenfield/templates/analysis.md +79 -0
- package/templates/greenfield/templates/behavior.md +1 -0
- package/templates/greenfield/templates/context-definition.md +1 -0
- package/templates/greenfield/templates/context-map.md +2 -1
- package/templates/greenfield/templates/events.md +4 -1
- package/templates/greenfield/templates/glossary.md +1 -0
- package/templates/greenfield/templates/lightweight-spec.md +154 -11
- package/templates/greenfield/templates/models.md +1 -0
- package/templates/greenfield/templates/phase-spec.md +9 -1
- package/templates/greenfield/templates/rules.md +1 -0
- package/templates/greenfield/templates/tech-debt.md +1 -0
- 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] / [
|
|
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
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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).
|
|
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.
|