From ebedd2380799cffa84bfee5536b47c69b02453cc Mon Sep 17 00:00:00 2001
From: Hunter Bown <hmbown@gmail.com>
Date: Tue, 12 May 2026 01:36:57 -0500
Subject: [PATCH] feat(skills): add opt-in v4-best-practices bundled skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A single 50-line `SKILL.md` encoding three V4-specific workflow
rules for multi-step thinking-mode tasks. Each rule maps to a
concrete observable failure class the maintainer or contributors
have hit when running V4-flash / V4-pro on long agent loops; the
text is opinionated but discovered through the existing skill
mechanism rather than baked into the always-on system prompt.

Follows the existing bundled-skill convention
(`crates/tui/assets/skills/skill-creator/`) so the discovery
walker picks it up alongside the workspace's own skills. Not
enabled by default — users see it in `/skills` and opt in
explicitly, keeping the always-on prompt-prefix footprint
unchanged for everyone who doesn't want the directive.

Single new file; zero Rust changes, zero new dependencies, zero
config schema changes. Fully reversible by deleting the directory.

Harvested from PR #1448 by @SamhandsomeLee

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  8 +++
 .../assets/skills/v4-best-practices/SKILL.md  | 50 +++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 crates/tui/assets/skills/v4-best-practices/SKILL.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bbc1f33f..2784e012 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -153,6 +153,14 @@ real world uses."
 
 ### Added
 
+- **Opt-in `v4-best-practices` bundled skill** (harvested from
+  PR #1448 by **@SamhandsomeLee**). A single 50-line `SKILL.md`
+  encoding three V4-specific workflow rules for multi-step
+  thinking-mode tasks. Each rule maps to a concrete observable
+  failure class. Discovered through the existing
+  `crates/tui/assets/skills/...` mechanism alongside the
+  `skill-creator` skill — not enabled by default; users opt in
+  via the standard `/skills` UI.
 - **`image_analyze` tool — vision-model image understanding**
   (harvested from PR #1467 by **@MMMarcinho**). Sends an image
   file to an OpenAI-compatible vision endpoint and returns the
diff --git a/crates/tui/assets/skills/v4-best-practices/SKILL.md b/crates/tui/assets/skills/v4-best-practices/SKILL.md
new file mode 100644
index 00000000..2fb0fdfa
--- /dev/null
+++ b/crates/tui/assets/skills/v4-best-practices/SKILL.md
@@ -0,0 +1,50 @@
+---
+name: v4-best-practices
+description: Use when working with deepseek-v4-pro or deepseek-v4-flash in thinking mode on multi-step or plan-driven tasks. Provides rules to prevent stale references, unverified plan assumptions, and vague plan output.
+---
+
+# V4 Best Practices
+
+Rules for multi-step V4 thinking-mode workflows. Each rule prevents a
+specific, observable failure class.
+
+## 1. Verify references before writing
+
+Before referencing a file path, function, or type in code or plan output,
+call `grep_files` or `read_file` to confirm it exists in the workspace.
+
+```
+# Bad:  edit_file path="src/config/loader.rs" (assumed from memory)
+# Good: grep_files pattern="pub fn load_config" → confirms src/config/mod.rs:42
+#        then reference src/config/mod.rs:42
+```
+
+Failure avoided: `edit_file` errors on non-existent paths; LSP diagnostics
+on hallucinated symbols.
+
+## 2. Spawn a verifier sub-agent before multi-file execution
+
+Before executing a plan that touches 3+ files, spawn a `deepseek-v4-flash`
+sub-agent (thinking off) to read the target files and confirm path/symbol
+assumptions still hold.
+
+```
+agent_spawn role="verifier" model="deepseek-v4-flash" thinking="off"
+  prompt: "Read these files and confirm: [list assumptions]. Report mismatches."
+```
+
+Failure avoided: multi-step edits fail partway because file structure
+changed since the plan was drafted.
+
+## 3. Plan output must use confirmed path:line references
+
+In plan-mode output, replace vague location pointers with `path:line`
+references drawn from a prior `grep_files` result.
+
+```
+# Bad:  "Update the retry logic in the client module"
+# Good: "Update retry loop at crates/tui/src/client.rs:187"
+```
+
+Failure avoided: agent-mode execution cannot locate the intended edit
+target when plan directions are imprecise.