@comfanion/workflow 4.39.2 → 4.39.3

package/src/opencode/skills/story-writing/SKILL.md

@@ -16,58 +16,105 @@ metadata:
 
 ```xml
 <story_rules>
-  <before_writing critical="MANDATORY">
-    <action>Read template file first</action>
-    <path>./template.md</path>
-    <focus>Lines 103-158 for task Approach examples</focus>
-  </before_writing>
-  
   <definition>Story = Smallest working increment (one layer/feature)</definition>
   
   <sizes>
-    <XS tasks="1-2" use="Rarely (trivial changes)"/>
-    <S tasks="2-4" use="TOY, SMALL projects"/>
-    <M tasks="4-8" use="Preferred for all" target="true"/>
-    <L tasks="8-12" use="Consider splitting"/>
-    <XL tasks="12+" use="Must split" forbidden="true"/>
+    <XS tasks="1-2" use="Trivial additions"/>
+    <S tasks="2-3" use="TOY, SMALL projects (PREFERRED)" target="true"/>
+    <M tasks="3-5" use="MEDIUM projects (PREFERRED)" target="true"/>
+    <L tasks="5-8" use="LARGE - only if feature is complex"/>
+    <XL tasks="8+" use="FORBIDDEN - must split into multiple stories" forbidden="true"/>
   </sizes>
   
-  <estimation>
-    <t_shirt for="TOY,SMALL,MEDIUM,LARGE">XS, S, M, L (no XL!)</t_shirt>
-    <t_shirt_plus_points for="ENTERPRISE">
-      <mapping XS="1" S="3" M="5" L="8" XL="13"/>
-    </t_shirt_plus_points>
-  </estimation>
+  <feature_driven>
+    <definition>Story = ONE working feature end-to-end (thin vertical slice)</definition>
+    <principle>Each story delivers value users can see/test</principle>
+    <approach>
+      <step>1. Study existing code (MANDATORY - find patterns)</step>
+      <step>2. Write test for core functionality</step>
+      <step>3. Implement MINIMAL code (domain + repo + API if needed)</step>
+      <step>4. Verify it works end-to-end</step>
+    </approach>
+    <examples>
+      <good>"User can create simple order" → Order entity + CreateOrder API + test</good>
+      <good>"Order validates required fields" → Add validation logic + tests</good>
+      <good>"Order checks inventory" → Integration with inventory service + tests</good>
+      <bad>"Create domain layer" → No working feature, just entities</bad>
+      <bad>"Implement repository layer" → Can't test without use case</bad>
+      <bad>"All CRUD operations" → Too big, split into Create/Read/Update/Delete stories</bad>
+    </examples>
+    <result>After story: feature WORKS, is TESTED, can be DEMOED</result>
+  </feature_driven>
+  
+  <task_composition>
+    <task n="1" type="study">Study existing code, design interfaces (if parallel planned)</task>
+    <task n="2" type="test">Write test for core functionality</task>
+    <task n="3" type="implement">Minimal implementation (domain + repo + API)</task>
+    <task n="4" type="verify">Integration test (if needed)</task>
+    <note>Most stories: 2-4 tasks. Prefer smaller stories over larger ones.</note>
+  </task_composition>
   
-  <vertical_slice>
-    <principle>Stories build layers, Epic completes full stack</principle>
-    <story_order>
-      <step>1. Domain (entities, value objects)</step>
-      <step>2. Repository interfaces</step>
-      <step>3. Use cases</step>
-      <step>4. Repository implementations</step>
-      <step>5. API (HTTP handlers)</step>
-      <step>6. UI (forms, views)</step>
-      <step>7. Integration tests</step>
-    </story_order>
-    <result>Each story = increment, Epic = working module</result>
-  </vertical_slice>
+  <task_approach_section critical="MANDATORY">
+    <rule>Each task MUST have "Approach" section with HIGH-LEVEL steps</rule>
+    <format>Numbered list of WHAT to do, NOT HOW (no code)</format>
+    <good_example>
+      1. Create Order struct with fields from Unit doc
+      2. Add NewOrder() constructor with validation
+      3. Add Validate() method
+      4. Write tests: valid order, empty fields, invalid status
+    </good_example>
+    <bad_example>
+      1. type Order struct { ID string; CustomerID string }
+      2. func NewOrder(id, customerID string) (*Order, error) { ... }
+      ❌ This is CODE, not approach!
+    </bad_example>
+    <remember>Approach = WHAT steps to take. @dev transforms this to HOW (technical details) for @coder.</remember>
+  </task_approach_section>
   
-  <task_approach critical="MANDATORY">
-    <rule>Every task MUST have Approach section</rule>
-    <format>Numbered list of high-level steps (WHAT to do)</format>
-    <forbidden>
-      <code_blocks>No code in Approach section</code_blocks>
-      <implementation>No detailed implementation</implementation>
-      <ready_solutions>No copy-paste code</ready_solutions>
-    </forbidden>
-    <example_good>
-      1. Create struct with fields from Unit doc
-      2. Add constructor with validation
-      3. Write tests: happy path + errors
-    </example_good>
-    <example_bad>Define struct: type Foo struct { ... }</example_bad>
-  </task_approach>
+  <test_strategy critical="MANDATORY">
+    <principle>Test CORE functionality first, expand coverage incrementally. No tests for sake of tests.</principle>
+    
+    <priority>
+      <p1>Business logic (validation, calculations, decisions)</p1>
+      <p2>Integration points (API calls, database, external services)</p2>
+      <p3>Error handling (edge cases, failures)</p3>
+      <p4>Happy path (normal flow)</p4>
+    </priority>
+    
+    <do_test>
+      <what>Business rules (validation, calculations)</what>
+      <what>State changes (create, update, delete)</what>
+      <what>Error conditions (invalid input, failures)</what>
+      <what>Integration with other services</what>
+    </do_test>
+    
+    <dont_test>
+      <skip>Simple getters/setters (no logic)</skip>
+      <skip>Trivial constructors (just assign fields)</skip>
+      <skip>Third-party library internals</skip>
+      <skip>Database framework internals</skip>
+    </dont_test>
+    
+    <incremental_approach>
+      <story n="1">Core functionality only (happy path + critical validation)</story>
+      <story n="2">Add edge cases as you discover them</story>
+      <story n="3">Integration tests when connecting systems</story>
+      <avoid>Writing 100% coverage in first story - wasteful, most tests never catch bugs</avoid>
+    </incremental_approach>
+    
+    <examples>
+      <good>Story: CreateOrder → Test: valid order, missing customer (2 tests, covers 80% of real issues)</good>
+      <good>Story: InventoryCheck → Test: success, out-of-stock, service down (3 tests, critical paths)</good>
+      <bad>Story: CreateOrder → 15 tests for all field combinations (overkill, testing framework not logic)</bad>
+      <bad>Test OrderID() getter → returns field (trivial, no value)</bad>
+    </examples>
+    
+    <metrics>
+      <wrong>Coverage % target (80%, 90%) - encourages testing trivial code</wrong>
+      <right>Core business paths tested (are critical flows covered?)</right>
+      <right>Critical errors handled (can system fail gracefully?)</right>
+    </metrics>
+  </test_strategy>
   
   <status_values>
     <draft>Being written</draft>
@@ -81,52 +128,69 @@ metadata:
 
 ---
 
-## Template & Format
+## Example: MEDIUM Project Story
 
-**BEFORE writing any story:** Read the template file:
+```yaml
+id: ORD-S01-01
+epic: ORD-E01
+status: ready
+size: M
+```
 
-→ `./template.md`
+# Story: Order Domain Layer
 
-**Key sections in template:**
-- Lines 103-158: Full task example with **Approach** section
-- Lines 119-122: Shows correct Approach format (high-level steps)
+## Goal
 
----
+Implement domain entities and value objects for Order Management.
 
-## Task Structure (MANDATORY)
+**Context:** Part of Epic 01 (Order Management). Focuses on domain layer.
 
-Each task MUST include these sections:
+## Units Affected
 
-1. **Goal** - what this task achieves
-2. **Read First** - table with documentation links
-3. **Output Files** - what files to create
-4. **Approach** - high-level steps (MANDATORY)
-5. **Done when** - completion criteria
+| Unit | Action | Description |
+|------|--------|-------------|
+| → Unit: `Order` | Create | New entity |
 
-### Approach Section Rules
+## Required Reading
 
-**CRITICAL:** Every task MUST have **Approach** section.
+| Document | Section | Why |
+|----------|---------|-----|
+| → `CLAUDE.md` | All | Project patterns |
+| → `docs/coding-standards/` | All | **MANDATORY** |
+| → Unit: `Order` | Data Model | Field definitions |
 
-**Approach = High-level steps (WHAT to do), NOT code (HOW to implement).**
+## Acceptance Criteria
 
-✅ **CORRECT:**
-```markdown
-**Approach:**
-1. Create Order struct with fields from Unit doc
-2. Add NewOrder() constructor with validation
-3. Add Validate() method for business rules
-4. Write tests: valid order, validation errors
-```
+- [ ] Order entity created with all fields
+- [ ] Validation logic implemented
+- [ ] Tests pass (>80% coverage)
+- [ ] Follows coding-standards
 
-❌ **WRONG (has code):**
-```markdown
-**Approach:**
-1. Define struct:
-   ```go
-   type Order struct { ID string }
-   ```
-```
+## Tasks
+
+| ID | Task | Deps | Status |
+|----|------|------|--------|
+| T1 | Order entity | - | ⬜ |
+| T2 | Value objects | - | ⬜ |
+| T3 | Unit tests | T1, T2 | ⬜ |
+
+### T1: Order Entity
+
+**Goal:** Create Order entity with business rules
+
+**Read First:**
+| Document | Section | What to Look For |
+|----------|---------|------------------|
+| → `docs/coding-standards/` | Domain Layer | Entity patterns |
+| → Unit: `Order` | Data Model | All fields |
+
+**Output Files:**
+- `internal/order/domain/order.go`
+- `internal/order/domain/order_test.go`
 
-**Golden Rule:** If you see code blocks in Approach → STOP, remove them.
+**Done when:**
+- [ ] Entity created
+- [ ] Follows coding-standards
+- [ ] Tests pass
 
-Point to patterns, don't write implementation.
+See `template.md` for full format.