@seanyao/roll 3.614.2 → 3.614.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "3.614.2",
+  "version": "3.614.4",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {

package/skills/roll-design/SKILL.md

@@ -27,20 +27,23 @@ Load when the user wants to discuss approaches, design a solution, model domains
 
 1. Clarify only when intent or boundaries are unclear.
 2. Model domain depth proportional to risk and novelty.
-3. Split into INVEST stories with acceptance criteria and dependencies.
-4. Write specs through roll story new and update backlog.
-5. Self-score the design quality.
+3. Detailed design before decomposition — for any non-trivial work, produce a concrete, implementable design artifact and get owner sign-off: (a) data/contract schema, (b) AT LEAST ONE complete worked sample of the intended output/behavior, (c) key interface signatures, (d) mapping/normalization rules, (e) edge cases & failure modes. Depth scales with risk/novelty; trivial work may be light.
+4. Split into INVEST stories — each a slice of the agreed detailed design.
+5. Write specs through roll story new and update backlog.
+6. Self-score the design quality.
 
 ## Hard Gates
 
 - Do not start implementation from this skill.
 - Backlog rows and spec files must stay consistent.
 - Peer review gates apply only when explicitly available/requested.
+- No story decomposition until a detailed design exists and the owner has signed off (proportional to risk). Decomposition slices an agreed design — it is NOT a substitute for designing. If you cannot show at least one complete worked sample of the intended output/behavior, the design is NOT done.
 
 ## Gotchas
 
 - Design writes backlog/spec artifacts; it must not quietly start code implementation.
 - Use roll story new for story directories; do not hand-create backlog rows without matching dossier structure.
+- Jumping from idea straight to INVEST stories (skipping detailed design) produces shallow specs and improvised, inconsistent implementation. Decomposition must slice a concrete, owner-agreed detailed design — schema + at least one complete worked sample + interfaces + mapping rules + edge cases.
 
 ## Maintenance
 

package/skills/roll-design/references/engineering-checklist.md

@@ -200,12 +200,28 @@ it('should handle concurrent writes', async () => {
 
 ---
 
+## 9. Detailed Design Completeness 📐
+
+**Definition:** Before decomposing work into stories, the detailed design must be concrete and implementable — not a sketch.
+
+**Must include (proportional to risk/novelty):**
+- [ ] Data/contract **schema**
+- [ ] **At least one complete worked sample** of the intended output/behavior
+- [ ] Key **interface signatures**
+- [ ] **Mapping/normalization rules**
+- [ ] **Edge cases & failure modes**
+
+**Rule:** If you cannot show at least one complete worked sample, the design is NOT done. Decomposition slices an agreed design — it is not a substitute for designing.
+
+---
+
 ## Mandatory Check Process
 
 During the **Test Design Review** phase of each Story, the following must be answered:
 
 ```markdown
 ### Engineering Common Sense Checklist
+- [ ] **Detailed design completeness**: Does the detailed design include at least one complete worked sample plus schema, interface signatures, mapping rules, and edge cases?
 - [ ] **Idempotency**: Can it be run repeatedly? Are there tests?
 - [ ] **Cross-module contract**: Are IDs/formats/algorithms consistent?
 - [ ] **Data flow**: Is the producer → consumer pipeline complete?

package/skills/roll-design/references/full-contract.md

@@ -176,7 +176,7 @@ Expected AC:
 Input: IDEA-NNN identifier from .roll/backlog.md
 
 Execution path:
-  [Read .roll/backlog.md IDEA-NNN row] → [Analyze] → [DDD Slice] → [Split Stories]
+  [Read .roll/backlog.md IDEA-NNN row] → [Analyze] → [DDD Slice] → [Solution Design] → [Split Stories]
       → [Write BACKLOG 📋 Todo] → [Annotate IDEA row: → US-XXX] → Done
 
 IDEA annotation: append `→ US-XXX` to the IDEA row's Description column.
@@ -289,10 +289,22 @@ User Input
                                          │
                                          ▼
               ┌─────────────────────────────────────────┐
-              │ 3. Solution Design                       │
-              │    - Architecture design                 │
-              │    - Module decomposition                │
+              │ 3. Detailed (Solution) Design  ★MANDATORY│
+              │    Before ANY decomposition, for         │
+              │    non-trivial work produce a concrete,  │
+              │    implementable artifact (depth scales  │
+              │    with risk/novelty):                   │
+              │    - Architecture / module decomposition │
               │    - Dependency analysis                 │
+              │    Required artifacts (all of):          │
+              │      (a) data/contract schema            │
+              │      (b) ≥1 COMPLETE worked sample of    │
+              │          the intended output/behavior    │
+              │      (c) key interface signatures        │
+              │      (d) mapping/normalization rules     │
+              │      (e) edge cases & failure modes      │
+              │    Rule: if you cannot show a complete   │
+              │    worked sample, the design is NOT done.│
               │    [Greenfield] Tactical Model per Context:
               │      - Aggregate Root + Entities + VOs  │
               │      - Invariants (业务不变式)           │
@@ -312,6 +324,15 @@ User Input
                                  │ AGREE / skipped
                                  ▼
               ┌─────────────────────────────────────────┐
+              │ [gate] Owner Sign-off on Detailed Design │  ← REQUIRED before decomposition
+              │    Decomposition slices an AGREED design;│
+              │    it does NOT replace designing. Get    │
+              │    owner sign-off (proportional to risk) │
+              │    before splitting into stories.        │
+              └──────────────────┬──────────────────────┘
+                                 │ Signed off
+                                 ▼
+              ┌─────────────────────────────────────────┐
               │ 4. Split into Stories                    │
               │    - INVEST principles                   │
               │    - Bounded Context → US domain prefix  │