@ranger1/dx 0.1.114 → 0.1.115
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/package.json
CHANGED
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: delivering-design-handoff
|
|
3
|
+
description: Use when a design is already approved and the user asks to create a design/spec doc, implementation plan, adversarial review, GitHub issue, issue branch, handoff document, commit, push, or copyable assignment text.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Delivering Design Handoff
|
|
7
|
+
|
|
8
|
+
## Overview
|
|
9
|
+
|
|
10
|
+
Turn an approved design into a ready-to-assign engineering package with one closed loop: spec, spec review and fixes, implementation plan, plan review and fixes, handoff doc, issue, branch, commit, push, issue assignment comment, and copyable assignment text.
|
|
11
|
+
|
|
12
|
+
**Core principle:** after the design is approved, the user should not have to restate the delivery choreography. Each review gate must be completed and fixed before the next artifact is written.
|
|
13
|
+
|
|
14
|
+
## When To Use
|
|
15
|
+
|
|
16
|
+
Use this only after the solution direction is already approved. If the design is still being explored, first use `brainstorming`.
|
|
17
|
+
|
|
18
|
+
Typical user asks:
|
|
19
|
+
|
|
20
|
+
- “把这个方案写成设计文档并提 issue”
|
|
21
|
+
- “写计划和交接文档，提交到 issue 分支”
|
|
22
|
+
- “后续不想重复输入，从设计文档到 issue/分支/提交都自动做”
|
|
23
|
+
- “给我一段可以直接复制给工程师的任务分配文字”
|
|
24
|
+
|
|
25
|
+
## Required Output Contract
|
|
26
|
+
|
|
27
|
+
By the end, produce all of these or clearly state the blocker:
|
|
28
|
+
|
|
29
|
+
| Item | Required shape |
|
|
30
|
+
| --- | --- |
|
|
31
|
+
| Design spec | `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, created using the design-doc discipline from `brainstorming` |
|
|
32
|
+
| Spec adversarial review | Reviewer subagent completed before the plan exists; valid findings applied to the spec, or explicit rejected findings with reasons |
|
|
33
|
+
| Implementation plan | `docs/superpowers/plans/YYYY-MM-DD-<topic>.md`, created by using `writing-plans` |
|
|
34
|
+
| Plan adversarial review | Reviewer subagent findings applied to the plan, or explicit rejected findings with reasons |
|
|
35
|
+
| Handoff doc | `docs/superpowers/handoffs/YYYY-MM-DD-<topic>-handoff.md` |
|
|
36
|
+
| GitHub issue | Structured issue with background, goals, plan, acceptance criteria, and doc paths |
|
|
37
|
+
| Issue branch | `codex/docs/<issue-id>-<slug>` for docs-only handoff, or matching repo convention |
|
|
38
|
+
| Commit | Conventional commit ending with `Refs: #<issue-id>` |
|
|
39
|
+
| Push | Branch pushed with upstream |
|
|
40
|
+
| Pull request | PR created or updated with the repo PR template, non-empty body, linked issue, doc paths, verification evidence, and read-back validation |
|
|
41
|
+
| Issue comment | Comment linking branch, commit, spec, plan, and handoff, plus the same project-manager-style assignment block from the final answer |
|
|
42
|
+
| Final answer | Short status plus a copyable project-manager-style assignment block |
|
|
43
|
+
|
|
44
|
+
## Workflow
|
|
45
|
+
|
|
46
|
+
### 1. Confirm starting state
|
|
47
|
+
|
|
48
|
+
- Read project instructions: `AGENTS.md`, referenced ruler docs, and git workflow docs.
|
|
49
|
+
- Check branch and worktree:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
rtk git status --short --branch
|
|
53
|
+
rtk git remote -v
|
|
54
|
+
rtk gh auth status
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- If there are unrelated dirty changes, do not overwrite them. If the handoff docs are the only dirty files, continue.
|
|
58
|
+
|
|
59
|
+
### 2. Write the design spec
|
|
60
|
+
|
|
61
|
+
Use `brainstorming` for the design-document phase. If the conversation already contains an approved design, do not restart exploratory questioning; treat that approved discussion as the input and apply `brainstorming`'s write-design-doc and self-review standards.
|
|
62
|
+
|
|
63
|
+
Create `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`.
|
|
64
|
+
|
|
65
|
+
Spec sections:
|
|
66
|
+
|
|
67
|
+
- Background
|
|
68
|
+
- Goals
|
|
69
|
+
- Non-goals
|
|
70
|
+
- Chosen approach and rejected alternatives
|
|
71
|
+
- Backend/frontend/data/API design as applicable
|
|
72
|
+
- Error handling
|
|
73
|
+
- Testing and verification
|
|
74
|
+
- Compatibility and risks
|
|
75
|
+
- Acceptance criteria
|
|
76
|
+
|
|
77
|
+
Run a self-review:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
rtk rg -n "TBD|TODO|待定|占位|\\.\\.\\." <spec-path>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Fix every hit that is a placeholder. A literal example such as `new BasePaginationResponseDto(total, page, limit, items)` is allowed; vague ellipses are not.
|
|
84
|
+
|
|
85
|
+
### 3. Dispatch adversarial review
|
|
86
|
+
|
|
87
|
+
Spawn one reviewer subagent. The prompt must include:
|
|
88
|
+
|
|
89
|
+
- spec path
|
|
90
|
+
- repo root
|
|
91
|
+
- current approved design context
|
|
92
|
+
- review axes: correctness, missing edge cases, repo convention violations, testability, and handoff ambiguity
|
|
93
|
+
- “read-only, do not modify files”
|
|
94
|
+
|
|
95
|
+
Apply all valid findings to the spec. If rejecting a finding, record the reason in the handoff doc's review notes and mention it briefly in the final answer only if material.
|
|
96
|
+
|
|
97
|
+
**Gate before planning:** do not create the implementation plan until the reviewer subagent has returned, every valid spec finding has been fixed, every rejected finding has a recorded reason, and the spec placeholder scan has passed again. If the reviewer subagent is still running, timed out, or failed, this gate is not complete. If the user asks to save time by writing the plan while review or fixes are pending, decline that shortcut and finish this gate first.
|
|
98
|
+
|
|
99
|
+
### 4. Create the implementation plan
|
|
100
|
+
|
|
101
|
+
Announce and use `writing-plans`:
|
|
102
|
+
|
|
103
|
+
> I'm using the writing-plans skill to create the implementation plan.
|
|
104
|
+
|
|
105
|
+
Start this step only after Step 3 is complete.
|
|
106
|
+
|
|
107
|
+
Create `docs/superpowers/plans/YYYY-MM-DD-<topic>.md` using the `writing-plans` required structure:
|
|
108
|
+
|
|
109
|
+
- header with goal, architecture, tech stack, and global constraints
|
|
110
|
+
- file map before tasks
|
|
111
|
+
- bite-sized tasks with exact files, interfaces, steps, commands, and expected results
|
|
112
|
+
- self-review for spec coverage, placeholders, and type consistency
|
|
113
|
+
|
|
114
|
+
Run placeholder scan:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
rtk rg -n "TBD|TODO|待定|占位|\\.\\.\\." <plan-path>
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Fix every true placeholder. Do not proceed to handoff until the plan can guide an engineer without asking back.
|
|
121
|
+
|
|
122
|
+
### 5. Dispatch plan adversarial review
|
|
123
|
+
|
|
124
|
+
Spawn one reviewer subagent for the plan. The prompt must include:
|
|
125
|
+
|
|
126
|
+
- spec path
|
|
127
|
+
- plan path
|
|
128
|
+
- repo root
|
|
129
|
+
- review axes: spec coverage, task order, file ownership, testability, missing code/commands, placeholders, type/interface consistency, and repo convention violations
|
|
130
|
+
- “read-only, do not modify files”
|
|
131
|
+
|
|
132
|
+
Apply all valid findings to the plan. If a finding reveals a spec defect, fix the spec too and re-check plan consistency.
|
|
133
|
+
|
|
134
|
+
### 6. Write the handoff document
|
|
135
|
+
|
|
136
|
+
Create `docs/superpowers/handoffs/YYYY-MM-DD-<topic>-handoff.md`.
|
|
137
|
+
|
|
138
|
+
This is separate from the implementation plan. It is the short assignment packet for a human engineer:
|
|
139
|
+
|
|
140
|
+
- Issue title and eventual issue id placeholder until issue exists
|
|
141
|
+
- branch name placeholder until branch exists
|
|
142
|
+
- links/paths to spec and plan
|
|
143
|
+
- why the work matters
|
|
144
|
+
- implementation order summary
|
|
145
|
+
- top risks and invariants
|
|
146
|
+
- required verification commands
|
|
147
|
+
- PR expectations and acceptance checklist pointer
|
|
148
|
+
|
|
149
|
+
Run placeholder scan over all docs. Placeholders that must be filled before commit, such as issue id after creation, must not remain.
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
rtk rg -n "TBD|TODO|待定|占位|\\.\\.\\." <spec-path> <plan-path> <handoff-path>
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### 7. Create the GitHub issue
|
|
156
|
+
|
|
157
|
+
Use heredoc, never `-m` or literal `\n`.
|
|
158
|
+
|
|
159
|
+
Issue body must include:
|
|
160
|
+
|
|
161
|
+
- Background
|
|
162
|
+
- Goals
|
|
163
|
+
- Plan
|
|
164
|
+
- Acceptance criteria with objective checkboxes
|
|
165
|
+
- Links or paths to the spec, implementation plan, and handoff doc
|
|
166
|
+
|
|
167
|
+
Labels should match repo conventions. Prefer labels for backend/frontend/admin/database/api/docs when they exist.
|
|
168
|
+
|
|
169
|
+
After issue creation, fill the concrete issue id and URL into the handoff doc if it used placeholders.
|
|
170
|
+
|
|
171
|
+
### 8. Create the issue branch
|
|
172
|
+
|
|
173
|
+
Fetch the base and create a clean issue branch:
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
rtk git fetch origin main --prune
|
|
177
|
+
rtk git switch -c codex/docs/<issue-id>-<slug> origin/main
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
If the spec was created before switching, remember that untracked files usually follow the checkout but tracked edits may not. Verify both docs are present after the switch. If content disappears, recover it intentionally with `git show`, `git stash`, or re-apply the patch; never use destructive checkout/reset.
|
|
181
|
+
|
|
182
|
+
After branch creation, fill the concrete branch name into the handoff doc if needed. Run final placeholder scan:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
rtk rg -n "TBD|TODO|待定|占位|\\.\\.\\." <spec-path> <plan-path> <handoff-path>
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### 9. Commit and push
|
|
189
|
+
|
|
190
|
+
Stage only the intended docs:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
rtk git add <spec-path> <plan-path> <handoff-path>
|
|
194
|
+
rtk git diff --cached --stat
|
|
195
|
+
rtk git diff --cached --check
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Commit:
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
rtk git commit -F - <<'MSG'
|
|
202
|
+
docs: add <topic> handoff
|
|
203
|
+
|
|
204
|
+
变更说明：
|
|
205
|
+
- 新增设计文档，固化已确认方案、风险、测试和验收标准。
|
|
206
|
+
- 新增实施计划和交接文档，拆分实现任务、文件范围和验证命令。
|
|
207
|
+
|
|
208
|
+
Refs: #<issue-id>
|
|
209
|
+
MSG
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Push:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
rtk git push -u origin <branch>
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Comment on the issue with branch, commit, spec path, plan path, handoff path, and the copyable project-manager-style assignment block from the final answer. This issue comment is mandatory; do not finish with only a local final answer.
|
|
219
|
+
|
|
220
|
+
### 10. Create or update the pull request
|
|
221
|
+
|
|
222
|
+
If the user asks for a PR, or repo convention expects a PR for the handoff branch, create or update it before the final answer.
|
|
223
|
+
|
|
224
|
+
PR body must be written to a temporary markdown file and passed with `--body-file "$pr_body_file"`. Never use `gh pr create --body-file -`, `gh pr edit --body-file -`, or `--body "multi-line text"` for PR content. Do not trust `ok` or a returned URL as proof that the body was saved; only trust a read-back from `gh pr view --json body`.
|
|
225
|
+
|
|
226
|
+
Use the repository PR template. When this repo's template is the standard git workflow template, the body must include all of these headings exactly:
|
|
227
|
+
|
|
228
|
+
- `## 变更目的`
|
|
229
|
+
- `## 主要改动和解决的问题`
|
|
230
|
+
- `## 遗留的问题`
|
|
231
|
+
- `## 已做的验证`
|
|
232
|
+
- `## PR 遗留未做的`
|
|
233
|
+
- `## 关联`
|
|
234
|
+
|
|
235
|
+
The body must also include:
|
|
236
|
+
|
|
237
|
+
- `Closes: #<issue-id>`
|
|
238
|
+
- branch name
|
|
239
|
+
- commit sha or subject
|
|
240
|
+
- spec path
|
|
241
|
+
- plan path
|
|
242
|
+
- handoff path
|
|
243
|
+
- verification commands and results, or an explicit docs-only note
|
|
244
|
+
|
|
245
|
+
Example shape:
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
pr_body_file="$(mktemp "${TMPDIR:-/tmp}/handoff-pr-body.XXXXXX.md")"
|
|
249
|
+
cat > "$pr_body_file" <<'MSG'
|
|
250
|
+
## 变更目的
|
|
251
|
+
<why this handoff exists and which approved design it packages>
|
|
252
|
+
|
|
253
|
+
## 主要改动和解决的问题
|
|
254
|
+
- 新增设计文档：`<spec-path>`
|
|
255
|
+
- 新增实施计划：`<plan-path>`
|
|
256
|
+
- 新增交接文档：`<handoff-path>`
|
|
257
|
+
- 分支：`<branch>`
|
|
258
|
+
- 提交：`<sha> <subject>`
|
|
259
|
+
|
|
260
|
+
## 遗留的问题
|
|
261
|
+
- 无，或列出明确遗留风险和处理建议。
|
|
262
|
+
|
|
263
|
+
## 已做的验证
|
|
264
|
+
- `rtk git diff --cached --check`：通过
|
|
265
|
+
- `rtk rg -n "TBD|TODO|待定|占位|\\.\\.\\." <spec-path> <plan-path> <handoff-path>`：无真实占位
|
|
266
|
+
- 文档交付，无需运行构建或测试。
|
|
267
|
+
|
|
268
|
+
## PR 遗留未做的
|
|
269
|
+
- 无，或列出需要后续实现 PR 完成的事项。
|
|
270
|
+
|
|
271
|
+
## 关联
|
|
272
|
+
Closes: #<issue-id>
|
|
273
|
+
MSG
|
|
274
|
+
|
|
275
|
+
pr_url="$(rtk gh pr create --base main --title 'docs: add <topic> handoff' --body-file "$pr_body_file")"
|
|
276
|
+
pr_number="$(rtk gh pr view "$pr_url" --json number --jq '.number')"
|
|
277
|
+
pr_body="$(rtk gh pr view "$pr_number" --json body --jq '.body')"
|
|
278
|
+
test -n "$pr_body"
|
|
279
|
+
for heading in \
|
|
280
|
+
"## 变更目的" \
|
|
281
|
+
"## 主要改动和解决的问题" \
|
|
282
|
+
"## 遗留的问题" \
|
|
283
|
+
"## 已做的验证" \
|
|
284
|
+
"## PR 遗留未做的" \
|
|
285
|
+
"## 关联"; do
|
|
286
|
+
printf '%s\n' "$pr_body" | grep -F "$heading" >/dev/null
|
|
287
|
+
done
|
|
288
|
+
printf '%s\n' "$pr_body" | grep -F "Closes: #<issue-id>" >/dev/null
|
|
289
|
+
printf '%s\n' "$pr_body" | grep -F "<branch>" >/dev/null
|
|
290
|
+
printf '%s\n' "$pr_body" | grep -F "<sha>" >/dev/null
|
|
291
|
+
printf '%s\n' "$pr_body" | grep -F "<spec-path>" >/dev/null
|
|
292
|
+
printf '%s\n' "$pr_body" | grep -F "<plan-path>" >/dev/null
|
|
293
|
+
printf '%s\n' "$pr_body" | grep -F "<handoff-path>" >/dev/null
|
|
294
|
+
rm -f "$pr_body_file"
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
If a PR already exists, use the same temp-file path with `rtk gh pr edit <pr-number> --body-file "$pr_body_file"`, then run the same read-back validation. If any heading, issue link, doc path, branch, commit, or verification evidence is missing, fix the temp body file, edit again, and read back again before continuing.
|
|
298
|
+
|
|
299
|
+
### 11. Final verification
|
|
300
|
+
|
|
301
|
+
Before claiming completion, run:
|
|
302
|
+
|
|
303
|
+
```bash
|
|
304
|
+
rtk git status --short --branch
|
|
305
|
+
rtk git log -1 --oneline
|
|
306
|
+
rtk git rev-parse --abbrev-ref --symbolic-full-name @{u}
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Report actual state. If no tests/builds were run because this is docs-only, say that.
|
|
310
|
+
|
|
311
|
+
If a PR was created or updated, read back the PR body and verify it is non-empty, follows the repo template headings, includes `Closes: #<issue-id>`, and contains the branch, commit, spec path, plan path, handoff path, and verification evidence. If `gh pr create` or `gh pr edit` reported success but read-back is empty or incomplete, repair the PR with a temp body file and read it back again before claiming completion.
|
|
312
|
+
|
|
313
|
+
Read back the issue comments and verify that the latest handoff comment contains the branch, commit, spec path, plan path, handoff path, and the same assignment block shown in the final answer. If `gh issue comment` failed, the comment is missing, or the readback does not match the final assignment block, fix that before claiming completion.
|
|
314
|
+
|
|
315
|
+
## Final Answer Template
|
|
316
|
+
|
|
317
|
+
Keep it short, then include this copyable block:
|
|
318
|
+
|
|
319
|
+
```markdown
|
|
320
|
+
已准备好交接资料：
|
|
321
|
+
|
|
322
|
+
- Issue：#<issue-id> <issue-url>
|
|
323
|
+
- PR：#<pr-id> <pr-url>
|
|
324
|
+
- 分支：`<branch>`
|
|
325
|
+
- 提交：`<sha> <subject>`
|
|
326
|
+
- 设计文档：`<spec-path>`
|
|
327
|
+
- 实施计划：`<plan-path>`
|
|
328
|
+
- 交接文档：`<handoff-path>`
|
|
329
|
+
|
|
330
|
+
以下交接评论已同步写入 Issue，可直接派发给开发工程师：
|
|
331
|
+
|
|
332
|
+
请基于 `<branch>` 接手实现 Issue #<issue-id>：<issue-title>。
|
|
333
|
+
|
|
334
|
+
先阅读：
|
|
335
|
+
1. `<spec-path>`
|
|
336
|
+
2. `<plan-path>`
|
|
337
|
+
3. `<handoff-path>`
|
|
338
|
+
|
|
339
|
+
实现时请按实施计划的 Task 顺序推进，并重点守住以下约束：
|
|
340
|
+
- <top-risk-or-constraint-1>
|
|
341
|
+
- <top-risk-or-constraint-2>
|
|
342
|
+
- <top-risk-or-constraint-3>
|
|
343
|
+
|
|
344
|
+
完成后请至少运行：
|
|
345
|
+
- `<verification-command-1>`
|
|
346
|
+
- `<verification-command-2>`
|
|
347
|
+
- `<verification-command-3>`
|
|
348
|
+
|
|
349
|
+
验收标准以 Issue #<issue-id> 的 checklist 为准。提 PR 时请逐条对应验收标准，并贴出验证命令结果；如遇到与设计文档冲突的实现细节，先在 Issue 中同步风险和建议处理方式。
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
In Codex app, after successful git actions, also emit the app directives for branch creation, staging, commit, and push.
|
|
353
|
+
|
|
354
|
+
## Common Mistakes
|
|
355
|
+
|
|
356
|
+
- Writing the issue before the spec is stable and then forgetting to update links.
|
|
357
|
+
- Writing the implementation plan before spec adversarial review has completed and valid findings have been fixed.
|
|
358
|
+
- Skipping adversarial review because the spec “looks obvious”.
|
|
359
|
+
- Treating the handoff doc as the implementation plan. The implementation plan must be produced with `writing-plans`, reviewed, and fixed before the handoff doc.
|
|
360
|
+
- Skipping adversarial review of the implementation plan.
|
|
361
|
+
- Creating the branch from the current stale feature branch instead of `origin/main`.
|
|
362
|
+
- Committing on an unrelated branch.
|
|
363
|
+
- Writing a handoff that says “add tests” without exact files, behaviors, and commands.
|
|
364
|
+
- Forgetting the issue comment, leaving the receiving engineer to hunt for branch and docs.
|
|
365
|
+
- Posting an issue comment with links only, but omitting the project-manager-style assignment block.
|
|
366
|
+
- Creating or editing a PR with `--body-file -` and assuming the body was saved.
|
|
367
|
+
- Trusting `gh pr create`, `gh pr edit`, or `ok` without reading back `gh pr view --json body`.
|
|
368
|
+
- Creating a PR whose body is empty, misses the repo template headings, omits `Closes: #<issue-id>`, or lacks doc paths and verification evidence.
|
|
369
|
+
- Final answer lists artifacts but omits the copyable project-manager-style assignment block.
|
|
@@ -163,32 +163,86 @@ git log origin/main..HEAD --oneline
|
|
|
163
163
|
git diff origin/main...HEAD --stat
|
|
164
164
|
```
|
|
165
165
|
|
|
166
|
-
3.
|
|
166
|
+
3. 生成 PR body 文件（默认 `--base main`）。**禁止** 用 `gh pr create --body-file -`、`gh pr edit --body-file -` 或 `--body "..."` 传多行正文；在 `rtk`/shell 包装下 stdin 可能被吞掉，命令返回成功但 GitHub PR body 为空。必须先写入临时 markdown 文件，再用 `--body-file <file>`。
|
|
167
167
|
|
|
168
168
|
```bash
|
|
169
|
-
|
|
170
|
-
|
|
169
|
+
pr_body_file="$(mktemp "${TMPDIR:-/tmp}/pr-body.XXXXXX.md")"
|
|
170
|
+
cat > "$pr_body_file" <<'MSG'
|
|
171
|
+
## 变更目的
|
|
171
172
|
|
|
172
|
-
-
|
|
173
|
+
- 对应 Issue 验收标准 [1]：<说明落点>
|
|
174
|
+
- 关键代码改动概述：<说明关键决策，不复述 diff>
|
|
173
175
|
|
|
174
|
-
##
|
|
176
|
+
## 主要改动和解决的问题
|
|
175
177
|
|
|
176
|
-
-
|
|
178
|
+
- 解决的问题：<对应 Issue 验收标准或新发现问题>
|
|
179
|
+
- 改动点：<文件/模块/功能>
|
|
180
|
+
- 改动原因：<为什么要改>
|
|
181
|
+
|
|
182
|
+
## 遗留的问题
|
|
183
|
+
|
|
184
|
+
- 无。/ <本 PR 未覆盖但属于 Issue 范围的项，必须挂后续 Issue/PR>
|
|
185
|
+
|
|
186
|
+
## 已做的验证
|
|
187
|
+
|
|
188
|
+
- 测试：<新增/修改的测试文件与用例名>
|
|
189
|
+
- 命令：<可复现命令和关键结果>
|
|
190
|
+
- 手测：<关键路径步骤与结果；没有则写“未额外执行浏览器手测，原因：...”>
|
|
191
|
+
|
|
192
|
+
## PR 遗留未做的
|
|
193
|
+
|
|
194
|
+
- 无。/ <仍欠动作，必须挂 owner 或后续 Issue/PR>
|
|
195
|
+
|
|
196
|
+
## 关联
|
|
177
197
|
|
|
178
198
|
Closes: #<issue-id>
|
|
179
|
-
|
|
199
|
+
MSG
|
|
180
200
|
```
|
|
181
201
|
|
|
182
|
-
4.
|
|
202
|
+
4. 创建 PR 并读回校验：
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
pr_url="$(gh pr create --base main --title '<type>: <概要>' --body-file "$pr_body_file")"
|
|
206
|
+
pr_number="$(gh pr view "$pr_url" --json number --jq '.number')"
|
|
207
|
+
pr_body="$(gh pr view "$pr_number" --json body --jq '.body')"
|
|
208
|
+
|
|
209
|
+
test -n "$pr_body"
|
|
210
|
+
for heading in \
|
|
211
|
+
"## 变更目的" \
|
|
212
|
+
"## 主要改动和解决的问题" \
|
|
213
|
+
"## 遗留的问题" \
|
|
214
|
+
"## 已做的验证" \
|
|
215
|
+
"## PR 遗留未做的" \
|
|
216
|
+
"## 关联"
|
|
217
|
+
do
|
|
218
|
+
printf '%s\n' "$pr_body" | grep -F "$heading" >/dev/null
|
|
219
|
+
done
|
|
220
|
+
printf '%s\n' "$pr_body" | grep -F "Closes: #<issue-id>" >/dev/null
|
|
221
|
+
rm -f "$pr_body_file"
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
5. 如果读回校验失败：不要声称 PR 创建完成。重新生成临时 body 文件，用 `gh pr edit <PR_NUMBER> --body-file "$pr_body_file"` 修复，再重复第 4 步读回校验。**不要**相信 `ok edited`，只相信 `gh pr view --json body` 的读回内容。
|
|
225
|
+
|
|
226
|
+
6. 成功后输出评审命令：`/pr-review-loop --pr <PR_NUMBER>`。
|
|
183
227
|
|
|
184
228
|
## 质量检查
|
|
185
229
|
|
|
186
230
|
- 标题简洁可读，语义明确。
|
|
187
231
|
- 描述包含背景、问题、目标、影响范围。
|
|
232
|
+
- PR body 必须读回非空，并包含 PR 模板六个必填章节与 `Closes: #<issue-id>`。
|
|
188
233
|
- 提交与 PR 文案可核对到 diff。
|
|
189
234
|
- 标签与提交类型匹配。
|
|
190
235
|
- 不泄露敏感信息。
|
|
191
236
|
|
|
237
|
+
## 红旗：PR body 可能为空
|
|
238
|
+
|
|
239
|
+
出现以下任一情况时，立即停止并读回校验，不要继续输出成功：
|
|
240
|
+
|
|
241
|
+
- 使用了 `gh pr create --body-file -` 或 `gh pr edit --body-file -`
|
|
242
|
+
- 使用了 `gh pr create --body "多行正文"` 或 `gh pr edit --body "多行正文"`
|
|
243
|
+
- `gh pr create/edit` 输出了 `ok`，但还没有执行 `gh pr view <PR> --json body --jq '.body'`
|
|
244
|
+
- PR body 未包含「变更目的 / 主要改动和解决的问题 / 遗留的问题 / 已做的验证 / PR 遗留未做的 / 关联」
|
|
245
|
+
|
|
192
246
|
## 失败与阻塞输出
|
|
193
247
|
|
|
194
248
|
输出以下四项：
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: stagewise-ui-debugging
|
|
3
|
+
description: Use when comparing the ai-monorepo Stagewise design system with the front app for UI alignment, visual QA, responsive layout checks, DOM inspection, or design draft debugging.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Stagewise UI 调试
|
|
7
|
+
|
|
8
|
+
## 概览
|
|
9
|
+
|
|
10
|
+
用于对齐 `design/ui_kits/app/` 设计稿和 `apps/front` 前端页面。核心原则：改 UI 前先在相同视口下，对比 Stagewise 包装后的设计站和前端站。
|
|
11
|
+
|
|
12
|
+
## 速查
|
|
13
|
+
|
|
14
|
+
| 目标 | 用户可能需要手动运行 | 访问地址 |
|
|
15
|
+
| --- | --- | --- |
|
|
16
|
+
| 设计稿 | `dx start stagewise-design-system` | `http://localhost:8766/ui_kits/app/` |
|
|
17
|
+
| 前端页面 | `dx start stack-front` | `http://localhost:3002` |
|
|
18
|
+
|
|
19
|
+
`stagewise-design-system` 会用 Stagewise 包装设计静态站，桥接 `8765 -> 8766`。`stack-front` 会启动 PM2 交互式服务栈和 `stagewise-front`，桥接 `3001 -> 3002`。
|
|
20
|
+
|
|
21
|
+
## 流程
|
|
22
|
+
|
|
23
|
+
1. 使用浏览器前，提醒用户这两个服务可能已经启动；如果没启动，可以手动运行：
|
|
24
|
+
```bash
|
|
25
|
+
dx start stagewise-design-system
|
|
26
|
+
dx start stack-front
|
|
27
|
+
```
|
|
28
|
+
2. 用浏览器工具访问两个 Stagewise 地址。若页面打不开、空白、或无法渲染，提示用户对应服务可能没启动或状态异常，让用户手动处理后再访问。
|
|
29
|
+
3. 在相同浏览器视口下对比设计稿和前端。桌面和移动端宽度都要看；视口不同会造成假的对齐差异。
|
|
30
|
+
4. 检查 DOM 时记住：两个页面都经过 Stagewise 包装。包装节点、桥接覆盖层、注入属性可能和裸应用 DOM 不同。优先做视觉对比和稳定的应用层选择器检查；编辑前先确认样式来自产品 UI，而不是 Stagewise 外壳。
|
|
31
|
+
5. 修改后端或前端页面后，页面会自动刷新到最新状态。需要确认时重新查看或刷新浏览器对比，不要先急着重启服务。
|
|
32
|
+
6. 如果任务涉及真实 UI 实现，以仓库设计规则为准：`design/readme.md`、`design/SKILL.md`、`ruler/design-system.md`。
|
|
33
|
+
|
|
34
|
+
## 触发示例
|
|
35
|
+
|
|
36
|
+
用户说：“调一下前端和设计稿的卡片间距。”
|
|
37
|
+
|
|
38
|
+
动作：加载本技能，提醒用户两个 `dx start` 命令，打开 `8766/ui_kits/app/` 和 `3002`，设置相同桌面和移动端视口，视觉对比后再按需要修改前端或设计源。
|
|
39
|
+
|
|
40
|
+
## 常见误区
|
|
41
|
+
|
|
42
|
+
| 常见问题 | 处理方式 |
|
|
43
|
+
| --- | --- |
|
|
44
|
+
| 用 `localhost:3001` 和设计稿对比，而不是 Stagewise 的 `3002` | 使用包装后的地址，让前端和设计稿处在同一种调试表面。 |
|
|
45
|
+
| 把空白页直接当成 UI bug | 先确认对应 `dx start ...` 服务正在运行且健康。 |
|
|
46
|
+
| 用不同视口宽度对比 | 设计稿和前端设置相同视口，并补充移动端检查。 |
|
|
47
|
+
| 根据 Stagewise 包装 DOM 直接改样式 | 确认选中的节点或样式属于产品 UI，不是 Stagewise 外壳。 |
|
|
48
|
+
| 每次页面改动后立刻手动重启 | 先看自动刷新或热更新后的浏览器结果，再决定是否需要重启。 |
|