speccrew 0.7.25 → 0.7.26
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.
|
@@ -35,10 +35,37 @@ Applies ISA-95 Stage 1 (Domain Description) for clarification:
|
|
|
35
35
|
|
|
36
36
|
## Templates Used
|
|
37
37
|
|
|
38
|
-
| Template | Path | Purpose |
|
|
39
|
-
|
|
40
|
-
| Clarification Questions | `templates/CLARIFICATION-QUESTIONS-TEMPLATE.md` | Round-based questionnaire for user clarification |
|
|
41
|
-
| Clarification Summary | `templates/CLARIFICATION-SUMMARY-TEMPLATE.md` | Final summary document with all Q&A and decisions |
|
|
38
|
+
| Template | Path | When to Load | Purpose |
|
|
39
|
+
|----------|------|-------------|----------|
|
|
40
|
+
| Clarification Questions | `templates/CLARIFICATION-QUESTIONS-TEMPLATE.md` | **Inside Loop L1** (each round) | Round-based questionnaire for user clarification |
|
|
41
|
+
| Clarification Summary | `templates/CLARIFICATION-SUMMARY-TEMPLATE.md` | **After G3 guard passes** (sufficiency_checks_passed == true) | Final summary document with all Q&A and decisions |
|
|
42
|
+
|
|
43
|
+
> **CRITICAL**: These two templates are used in **separate phases**. NEVER load both templates at the same time.
|
|
44
|
+
> - During the clarification loop: ONLY load `CLARIFICATION-QUESTIONS-TEMPLATE.md`
|
|
45
|
+
> - After ALL sufficiency checks pass: ONLY then load `CLARIFICATION-SUMMARY-TEMPLATE.md`
|
|
46
|
+
|
|
47
|
+
## Execution Flow (MANDATORY sequence)
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
Step 1: Read requirement document
|
|
51
|
+
Step 2: Read system knowledge (if exists)
|
|
52
|
+
Step 3: Determine complexity mode (simple/complex/auto-detect)
|
|
53
|
+
Step 4: Initialize loop variables
|
|
54
|
+
Step 5: Clarification Loop (both simple and complex modes):
|
|
55
|
+
5a. Load CLARIFICATION-QUESTIONS-TEMPLATE.md (ONLY this template)
|
|
56
|
+
5b. Generate .clarification-questions-round-{N}.md from template
|
|
57
|
+
5c. *** HARD STOP *** Wait for user to answer questions (user-confirm event)
|
|
58
|
+
5d. Read user's answered questions file
|
|
59
|
+
5e. Perform sufficiency checks (MUST have real user answers)
|
|
60
|
+
5f. If checks fail and rounds remain → back to 5a
|
|
61
|
+
5g. If checks pass → exit loop
|
|
62
|
+
Step 6: Guard Gateway G3 (sufficiency_checks_passed == true required)
|
|
63
|
+
6a. Load CLARIFICATION-SUMMARY-TEMPLATE.md (ONLY now)
|
|
64
|
+
6b. Generate .clarification-summary.md from template
|
|
65
|
+
6c. Checkpoint: clarification complete
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
> **FORBIDDEN**: Skipping Step 5c (user-confirm), loading summary template during Step 5, or generating summary without user answers.
|
|
42
69
|
|
|
43
70
|
---
|
|
44
71
|
|
|
@@ -86,19 +86,58 @@
|
|
|
86
86
|
<!-- Step 5: Execute Clarification -->
|
|
87
87
|
<block type="gateway" id="G2" mode="exclusive" desc="Execute clarification based on mode">
|
|
88
88
|
<branch test="${complexity} == 'simple'" name="Simple Mode Clarification">
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
89
|
+
<!-- Simple mode: 1 round of key clarification questions -->
|
|
90
|
+
<block type="rule" id="R-SIMPLE-TEMPLATE" level="mandatory" desc="Simple mode also uses template">
|
|
91
|
+
<field name="text">MANDATORY: Even in simple mode, clarification questions MUST be generated from CLARIFICATION-QUESTIONS-TEMPLATE.md template.</field>
|
|
92
|
+
<field name="text">Simple mode generates 1-3 key questions focusing on: scope, acceptance criteria, and business reason.</field>
|
|
93
|
+
</block>
|
|
94
|
+
|
|
95
|
+
<block type="task" id="B6-load-template" action="read-file" desc="Load clarification questions template for simple mode">
|
|
96
|
+
<field name="path" value="${skill_path}/templates/CLARIFICATION-QUESTIONS-TEMPLATE.md"/>
|
|
97
|
+
<field name="output" var="questions_template"/>
|
|
98
|
+
</block>
|
|
99
|
+
|
|
100
|
+
<block type="task" id="B6" action="generate" desc="Simple mode: generate 1-3 key clarification questions from template">
|
|
101
|
+
<field name="template" value="${questions_template}"/>
|
|
102
|
+
<field name="output_path" value="${iteration_path}/01.product-requirement/.clarification-questions-round-1.md"/>
|
|
103
|
+
<field name="vars">
|
|
104
|
+
- round_number: 1
|
|
105
|
+
- iteration_name: ${iteration_name}
|
|
106
|
+
- date: ${current_date}
|
|
107
|
+
- complexity_level: simple
|
|
108
|
+
- requirement_summary: ${requirement_summary}
|
|
95
109
|
</field>
|
|
96
|
-
<field name="
|
|
110
|
+
<field name="guidance">Simple mode: generate only 1-3 key questions focusing on scope boundaries, acceptance criteria, and business reason. Remove unused category sections from template.</field>
|
|
111
|
+
<field name="output" var="questions_file"/>
|
|
112
|
+
</block>
|
|
113
|
+
|
|
114
|
+
<block type="rule" id="R-SIMPLE-CONFIRM" level="mandatory" desc="User must answer even in simple mode">
|
|
115
|
+
<field name="text">MANDATORY: User-confirm event below is a HARD STOP. Worker MUST pause and wait for user response.</field>
|
|
116
|
+
</block>
|
|
117
|
+
|
|
118
|
+
<block type="event" id="E-SIMPLE-CONFIRM" action="user-confirm" desc="Wait for user to answer simple clarification questions">
|
|
119
|
+
<field name="prompt">📋 澄清问题已生成 (简单模式): ${questions_file}
|
|
120
|
+
|
|
121
|
+
请：
|
|
122
|
+
1. 查看澄清问题文件
|
|
123
|
+
2. 在文件中填写您的答案
|
|
124
|
+
3. 填写完成后确认继续</field>
|
|
125
|
+
<field name="skippable" value="false"/>
|
|
126
|
+
</block>
|
|
127
|
+
|
|
128
|
+
<block type="task" id="B6-read-answers" action="read-file" desc="Read user answers for simple mode">
|
|
129
|
+
<field name="path" value="${questions_file}"/>
|
|
130
|
+
<field name="output" var="answered_questions"/>
|
|
131
|
+
</block>
|
|
132
|
+
|
|
133
|
+
<block type="task" id="B6-mark-complete" action="set-var" desc="Mark simple mode clarification as complete">
|
|
134
|
+
<field name="sufficiency_checks_passed" value="true"/>
|
|
97
135
|
</block>
|
|
98
136
|
</branch>
|
|
99
137
|
<branch test="${complexity} == 'complex'" name="Complex Mode Clarification">
|
|
100
138
|
<!-- Clarification Loop -->
|
|
101
139
|
<block type="loop" id="L1" condition="sufficiency_checks_passed == false AND round_number <= max_rounds" desc="Clarification rounds until sufficiency">
|
|
140
|
+
<!-- ========== PHASE A: Generate Questions (ONLY questions template loaded here) ========== -->
|
|
102
141
|
<!-- MANDATORY: Template-based generation rule -->
|
|
103
142
|
<block type="rule" id="R-TEMPLATE-GENERATION" level="mandatory" desc="Template-based generation is MANDATORY">
|
|
104
143
|
<field name="text">MANDATORY: Clarification questions MUST be generated by loading the template file and performing variable substitution.</field>
|
|
@@ -125,6 +164,7 @@
|
|
|
125
164
|
<field name="output" var="questions_file"/>
|
|
126
165
|
</block>
|
|
127
166
|
|
|
167
|
+
<!-- ========== PHASE B: HARD STOP - Wait for User Answers ========== -->
|
|
128
168
|
<!-- MANDATORY: User confirmation cannot be bypassed -->
|
|
129
169
|
<block type="rule" id="R-USER-CONFIRM-MANDATORY" level="mandatory" desc="User-confirm events MUST pause Worker execution">
|
|
130
170
|
<field name="text">MANDATORY: The following user-confirm event is a HARD STOP. Worker MUST pause and present the prompt to user.</field>
|
|
@@ -143,6 +183,7 @@
|
|
|
143
183
|
<field name="skippable" value="false"/>
|
|
144
184
|
</block>
|
|
145
185
|
|
|
186
|
+
<!-- ========== PHASE C: Read Answers and Check Sufficiency ========== -->
|
|
146
187
|
<block type="task" id="B8" action="read-file" desc="Read answered questions">
|
|
147
188
|
<field name="path" value="${questions_file}"/>
|
|
148
189
|
<field name="output" var="answered_questions"/>
|
|
@@ -178,6 +219,16 @@
|
|
|
178
219
|
<block type="task" id="B9-increment" action="set-var" desc="Increment round counter">
|
|
179
220
|
<field name="round_number" value="${round_number + 1}"/>
|
|
180
221
|
</block>
|
|
222
|
+
<!-- ========== END OF LOOP ITERATION - Summary template is NOT loaded here ========== -->
|
|
223
|
+
</block>
|
|
224
|
+
</branch>
|
|
225
|
+
<branch default="true" name="ERROR: Unknown Complexity">
|
|
226
|
+
<block type="task" id="B-COMPLEXITY-ERROR" action="set-variable" desc="Handle unknown complexity value">
|
|
227
|
+
<field name="error_type">UNKNOWN_COMPLEXITY</field>
|
|
228
|
+
<field name="error_message">Complexity mode could not be determined. Value: ${complexity}. Expected 'simple' or 'complex'.</field>
|
|
229
|
+
</block>
|
|
230
|
+
<block type="event" id="E-COMPLEXITY-ABORT" action="abort" desc="Abort: unknown complexity">
|
|
231
|
+
<field name="message">Cannot proceed: complexity mode is '${complexity}', expected 'simple' or 'complex'.</field>
|
|
181
232
|
</block>
|
|
182
233
|
</branch>
|
|
183
234
|
</block>
|
|
@@ -194,6 +245,8 @@
|
|
|
194
245
|
<!-- Step 6: Generate .clarification-summary.md (Guarded by G3) -->
|
|
195
246
|
<block type="gateway" id="G3" mode="exclusive" desc="Guard: Only generate summary if sufficiency checks passed">
|
|
196
247
|
<branch test="${sufficiency_checks_passed} == true" name="Sufficiency Passed - Generate Summary">
|
|
248
|
+
<!-- ========== SUMMARY GENERATION (Only reached when ALL sufficiency checks passed) ========== -->
|
|
249
|
+
<!-- NOTE: Summary template is loaded HERE, not in the loop above. This is intentional. -->
|
|
197
250
|
<block type="task" id="B10-load-template" action="read-file" desc="Load summary template">
|
|
198
251
|
<field name="path" value="${skill_path}/templates/CLARIFICATION-SUMMARY-TEMPLATE.md"/>
|
|
199
252
|
<field name="output" var="summary_template"/>
|
|
@@ -223,10 +276,15 @@
|
|
|
223
276
|
<field name="verify" value="file_exists(${summary_path})"/>
|
|
224
277
|
</block>
|
|
225
278
|
</branch>
|
|
226
|
-
<branch default="true" name="Sufficiency Failed -
|
|
227
|
-
<block type="
|
|
228
|
-
<field name="
|
|
229
|
-
<field name="
|
|
279
|
+
<branch default="true" name="Sufficiency Failed - Abort Workflow">
|
|
280
|
+
<block type="rule" id="R-ABORT-RULE" level="mandatory" desc="Abort when sufficiency failed">
|
|
281
|
+
<field name="text">MANDATORY: sufficiency_checks_passed is false. Worker MUST abort workflow immediately.</field>
|
|
282
|
+
<field name="text">DO NOT attempt to generate .clarification-summary.md.</field>
|
|
283
|
+
<field name="text">Return control to PM Agent with error status.</field>
|
|
284
|
+
</block>
|
|
285
|
+
<block type="event" id="E-INSUFFICIENCY-ABORT" action="abort" desc="Abort: sufficiency checks failed after all rounds">
|
|
286
|
+
<field name="message">Requirement clarification did not achieve sufficient clarity after ${round_number - 1} round(s). Returning control to PM Agent for user intervention.</field>
|
|
287
|
+
<field name="error_code">CLARIFICATION_INSUFFICIENT</field>
|
|
230
288
|
</block>
|
|
231
289
|
</branch>
|
|
232
290
|
</block>
|