feat: extracted shared clear context handoff to shared reference (#156)

RuiMiguel · web-flow · commit 44e4246593f5 · 2026-04-15T14:02:14.000+02:00
diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md
@@ -177,23 +177,13 @@ Use **AskUserQuestion tool** to consider next steps:
 3. **Review and refine approach:** improve the document using structured review
 4. **Done for now**: brainstorm complete. To start planning later: `/plan`
 
-**If the user selects "Clear context and plan"** → output the following (substituting the actual brainstorm doc path) and then stop:
-
-```md
-To continue with a fresh context, run:
-
-/clear
-
-Then start planning with:
-
-/plan docs/brainstorm/<actual-brainstorm-filename>.md
-```
+**If the user selects "Clear context and plan"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/plan` with the actual brainstorm doc path. Then stop.
 
 **If the user selects "Review and refine approach"** then apply the @refine-approach skill to the document.
 
 When `refine-approach` is complete, present these options:
 
-1. **Clear context and plan**: clear context for a fresh start, then plan
+1. **Clear context and plan**: follow the [clear context handoff](references/clear-context-handoff.md) for `/plan`
 2. **Move to planning**: run the `/plan` skill to create a detailed implementation plan
 3. **Done for now**: ideation complete. To start planning later: `/plan`
 
diff --git a/skills/brainstorm/references/clear-context-handoff.md b/skills/brainstorm/references/clear-context-handoff.md
@@ -0,0 +1 @@
+../../shared/references/clear-context-handoff.md
diff --git a/skills/plan-technical-review/SKILL.md b/skills/plan-technical-review/SKILL.md
@@ -43,16 +43,6 @@ If the plan-splitting-agent reports no split needed: include the scope summary i
 3. **Refine the plan**: improve the plan based on review findings
 4. **Done for now**: review complete
 
-**If the user selects "Clear context and build"** → output the following (substituting the actual plan file path) and then stop:
-
-```md
-To continue with a fresh context, run:
-
-/clear
-
-Then start building with:
-
-/build docs/plan/<actual-plan-filename>.md
-```
+**If the user selects "Clear context and build"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/build` with the actual plan file path. Then stop.
 
 **When invoked by another skill** (e.g., from `/plan`), return control to the caller after the review completes — do not present handoff options.
diff --git a/skills/plan-technical-review/references/clear-context-handoff.md b/skills/plan-technical-review/references/clear-context-handoff.md
@@ -0,0 +1 @@
+../../shared/references/clear-context-handoff.md
diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md
@@ -265,18 +265,7 @@ After writing the plan file, use the **AskUserQuestion tool** and present the fo
 
 Based on selection:
 
-- **Clear context and build** → Output the following (substituting the actual plan file path) and then stop:
-
-  ```md
-  To continue with a fresh context, run:
-
-  /clear
-
-  Then start building with:
-
-  /build docs/plan/<actual-plan-filename>.md
-  ```
-
+- **Clear context and build** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/build` with the actual plan file path. Then stop.
 - **Start building** → Call the `/build` skill with the plan file path
 - **Open plan in editor** → Run `open docs/plan/<plan_filename>.md` to open the file in the user's default editor
 - **`/plan-technical-review`** → Call the `/plan-technical-review` skill with the plan file path
diff --git a/skills/plan/references/clear-context-handoff.md b/skills/plan/references/clear-context-handoff.md
@@ -0,0 +1 @@
+../../shared/references/clear-context-handoff.md
diff --git a/skills/refine-approach/SKILL.md b/skills/refine-approach/SKILL.md
@@ -91,29 +91,9 @@ After changes are complete, ask:
 2. **Refine again** — another review pass
 3. **Done for now** — document is ready
 
-**If the user selects "Clear context and plan"** → output the following (substituting the actual brainstorm doc path) and then stop:
+**If the user selects "Clear context and plan"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/plan` with the actual brainstorm doc path. Then stop.
 
-```md
-To continue with a fresh context, run:
-
-/clear
-
-Then start planning with:
-
-/plan docs/brainstorm/<actual-brainstorm-filename>.md
-```
-
-**If the user selects "Clear context and build"** → output the following (substituting the actual plan file path) and then stop:
-
-```md
-To continue with a fresh context, run:
-
-/clear
-
-Then start building with:
-
-/build docs/plan/<actual-plan-filename>.md
-```
+**If the user selects "Clear context and build"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/build` with the actual plan file path. Then stop.
 
 **When invoked by another skill** (e.g., from `/brainstorm` or `/plan`), only offer "Refine again" and "Review complete", then return control to the caller.
 
diff --git a/skills/refine-approach/references/clear-context-handoff.md b/skills/refine-approach/references/clear-context-handoff.md
@@ -0,0 +1 @@
+../../shared/references/clear-context-handoff.md
diff --git a/skills/shared/references/clear-context-handoff.md b/skills/shared/references/clear-context-handoff.md
@@ -0,0 +1,18 @@
+# Clear Context Handoff
+
+When a "Clear context and [next step]" option is selected, output the following block (substituting the actual skill and document path) and then **stop**:
+
+```md
+To continue with a fresh context, run:
+
+/clear
+
+Then start <NEXT_ACTION> with:
+
+/<NEXT_SKILL> <DOC_PATH>
+```
+
+Where:
+- `<NEXT_ACTION>` — the verb for the next phase (e.g., "planning", "building")
+- `<NEXT_SKILL>` — the skill to invoke (e.g., `plan`, `build`)
+- `<DOC_PATH>` — the full path to the document produced in the current phase

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../shared/references/clear-context-handoff.md`