From 8062a25e31670e1576d59dd30fb682f60a403ed7 Mon Sep 17 00:00:00 2001
From: alexsoyes <contact.alexsoyes@gmail.com>
Date: Tue, 25 Aug 2026 15:42:42 +0800
Subject: [PATCH] docs(readme): clarify the feature delivery flow

---
 README.md | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index b7ed1909..b286b462 100644
--- a/README.md
+++ b/README.md
@@ -197,18 +197,36 @@ flowchart TD
     end
 
     subgraph loop["② Per feature — repeat"]
-      direction LR
-      B["brainstorm"] --> P["plan"] --> I["implement"] --> R["review"] --> C["commit"] --> PR(["✅ PR"])
+      direction TB
+      subgraph frame["Frame"]
+        direction LR
+        N["functional need<br/>or User Story"] --> T["issue / ticket"] --> P["plan"]
+      end
+      subgraph deliver["Deliver"]
+        direction LR
+        I["implement"] --> V["validate"] --> R["review"]
+      end
+      subgraph ship["Ship"]
+        direction LR
+        PR["PR"] --> S(["✅ production"]) --> L["learn"]
+      end
+      P --> I
+      R --> PR
     end
 
-    Onboard --> Memory --> B
+    Onboard --> Memory --> N
+    L -. next need .-> N
 
     classDef hub fill:#D97757,stroke:#9c4f37,color:#fff;
     classDef done fill:#2ea043,stroke:#1a7f37,color:#fff;
     class Onboard hub;
-    class PR done;
+    class S done;
 ```
 
+Start with a functional need or User Story, then track it as an issue or ticket
+before planning. Shipping follows the project's own delivery process. Capture a
+learning only when it is durable enough to improve the next feature.
+
 > 🍳 **More flows** → bundled recipes: [start a project](plugins/aidd-context/skills/12-cook/assets/recipes/start-a-project.md), [ship a feature](plugins/aidd-context/skills/12-cook/assets/recipes/ship-a-feature.md), and more.
 
 ## 🧩 Plugins