BugRoger · rohan-tessl · Mar 31, 2026
diff --git a/skills/design/SKILL.md b/skills/design/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: design
-description: Create PRDs through structured decision-tree interviews — designing, speccing, scoping. Walks every branch of the design tree, sweeps for gray areas, writes a PRD.
+description: "Create product requirements documents through structured decision-tree interviews — explores design branches, identifies gray areas, and produces a complete PRD. Use when the user wants to spec out a feature, write a product requirements document, scope a new initiative, or gather requirements before planning."
 ---
 
 # /design
 
-Create PRDs through structured decision-tree interviews and collaborative dialogue.
+Create PRDs through structured decision-tree interviews and collaborative dialogue. Walks every branch of the design space, surfaces gray areas, and produces a PRD ready for `/plan`.
 
 <HARD-GATE>
 Execute @_shared/task-runner.md now.
@@ -15,11 +15,17 @@ Do not output anything else first.
 Do not skip this for "simple" tasks.
 
 No implementation until PRD is approved. [→ Why](references/constraints.md)
+
+Example TodoWrite structure:
+- [ ] Phase 0: Prime — load context and prior decisions
+- [ ] Phase 1: Execute — decision-tree interview, gray-area sweep
+- [ ] Phase 2: Validate — PRD completeness check, user approval
+- [ ] Phase 3: Checkpoint — save PRD, update status
 </HARD-GATE>
 
 ## Phases
 
 0. [Prime](phases/0-prime.md) — Load context, check prior decisions
 1. [Execute](phases/1-execute.md) — Decision tree walk, gray areas
-2. [Validate](phases/2-validate.md) — PRD completeness check, user approval
+2. [Validate](phases/2-validate.md) — PRD completeness check, user approval. If incomplete → return to Phase 1 to address gaps
 3. [Checkpoint](phases/3-checkpoint.md) — Save PRD, update status, suggest /plan
diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: implement
-description: Execute implementation plans — implementing, coding, building. Use after plan. Dispatches subagent per task with wave ordering, deviation handling, and spec checks.
+description: "Execute implementation plans by dispatching subagents per task — writes code files, creates modules, runs spec checks, and handles deviations with wave-ordered execution. Use when the user wants to execute a plan, start building, implement features, carry out tasks, or code the designed solution."
 ---
 
 # /implement
 
-Load plan, dispatch subagents per task in wave order, verify completion.
+Load the plan, dispatch subagents per task in wave order, verify completion against specs.
 
 <HARD-GATE>
 Execute @_shared/task-runner.md now.
@@ -15,11 +15,17 @@ Do not output anything else first.
 Do not skip this for "simple" tasks.
 
 No EnterPlanMode or ExitPlanMode. [→ Why](references/constraints.md)
+
+Example TodoWrite structure:
+- [ ] Phase 0: Prime — load plan, parse waves
+- [ ] Phase 1: Execute — dispatch agents, spec check, wave checkpoints
+- [ ] Phase 2: Validate — run tests, deviation summary, fix loop
+- [ ] Phase 3: Checkpoint — save deviations, suggest /validate
 </HARD-GATE>
 
 ## Phases
 
 0. [Prime](phases/0-prime.md) — Load plan, parse waves
 1. [Execute](phases/1-execute.md) — Dispatch agents, spec check, wave checkpoints
-2. [Validate](phases/2-validate.md) — Run tests, deviation summary, fix loop
+2. [Validate](phases/2-validate.md) — Run tests, deviation summary. If failures → fix and re-run before proceeding
 3. [Checkpoint](phases/3-checkpoint.md) — Save deviations, suggest /validate
diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: plan
-description: Decompose PRDs into independent features — scoping, slicing, architectural decisions. Use after design. Creates feature plans from a PRD.
+description: "Decompose PRDs into independent feature plans — identifies scope boundaries, determines implementation order, and documents architectural decisions for each vertical slice. Use when the user wants to break down requirements, create a task breakdown, plan feature implementation, or split a PRD into buildable pieces."
 ---
 
 # /plan
 
-Decompose a PRD into independent feature plans. Each feature is a vertical slice that can be implemented separately via /implement.
+Decompose a PRD into independent feature plans. Each feature is a vertical slice that can be implemented separately via `/implement`.
 
 <HARD-GATE>
 Execute @_shared/task-runner.md now.
@@ -15,11 +15,17 @@ Do not output anything else first.
 Do not skip this for "simple" tasks.
 
 No EnterPlanMode or ExitPlanMode — this skill manages its own flow. [→ Why](references/constraints.md)
+
+Example TodoWrite structure:
+- [ ] Phase 0: Prime — load context, read design doc
+- [ ] Phase 1: Execute — identify architectural decisions, decompose into features
+- [ ] Phase 2: Validate — coverage check, feature set approval
+- [ ] Phase 3: Checkpoint — save feature plans
 </HARD-GATE>
 
 ## Phases
 
 0. [Prime](phases/0-prime.md) — Load context, read design doc
 1. [Execute](phases/1-execute.md) — Identify architectural decisions, decompose into features
-2. [Validate](phases/2-validate.md) — Coverage check, feature set approval
+2. [Validate](phases/2-validate.md) — Coverage check: verify every PRD requirement maps to at least one feature. If gaps → return to Phase 1
 3. [Checkpoint](phases/3-checkpoint.md) — Save feature plans, suggest /implement
diff --git a/skills/release/SKILL.md b/skills/release/SKILL.md
@@ -1,23 +1,29 @@
 ---
 name: release
-description: Create changelogs and release notes — releasing, documenting, shipping. Use after validate. Detects version, categorizes commits, generates changelog, commits, merges or creates PR.
+description: "Prepare releases with automated changelog generation — detects next semver version, categorizes commits by type, generates CHANGELOG.md entries, commits, and merges or creates a PR. Use when the user wants to cut a release, bump the version, generate a changelog, write release notes, or ship a new version."
 ---
 
 # /release
 
-Detect version, categorize commits, generate changelog, commit, merge or PR, tag.
+Detect next version via semver, categorize commits, generate changelog, commit, merge or PR, and tag the release.
 
 <HARD-GATE>
 Execute @_shared/task-runner.md now.
 
 Your FIRST tool call MUST be TodoWrite with parsed phases from below.
 Do not output anything else first.
 Do not skip this for "simple" tasks.
+
+Example TodoWrite structure:
+- [ ] Phase 0: Prime — load artifacts, determine version
+- [ ] Phase 1: Execute — categorize commits, generate changelog, commit, merge/PR, tag
+- [ ] Phase 2: Validate — verify release completeness
+- [ ] Phase 3: Checkpoint — retro, status update
 </HARD-GATE>
 
 ## Phases
 
 0. [Prime](phases/0-prime.md) — Load artifacts, determine version
-1. [Execute](phases/1-execute.md) — Categorize, changelog, commit, merge/PR, tag
-2. [Validate](phases/2-validate.md) — Verify release completeness
+1. [Execute](phases/1-execute.md) — Categorize commits, generate changelog, commit, merge/PR, tag
+2. [Validate](phases/2-validate.md) — Verify release completeness. If issues found → fix before proceeding
 3. [Checkpoint](phases/3-checkpoint.md) — Retro, status update
diff --git a/skills/validate/SKILL.md b/skills/validate/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: validate
-description: Quality gate — testing, linting, validating. Use after implement. Runs tests and checks quality gates.
+description: "Run quality gates before release — executes unit and integration tests, runs linters, checks type correctness, and verifies code formatting. Use when the user wants to run tests, check code quality, validate changes, lint the codebase, or verify implementation correctness after coding."
 ---
 
 # /validate
 
-Verify code changes meet quality standards before release.
+Verify code changes meet quality standards before release. Runs tests, linters, type checks, and formatting validators against configured quality gates.
 
 <HARD-GATE>
 Execute @_shared/task-runner.md now.
@@ -15,11 +15,17 @@ Do not output anything else first.
 Do not skip this for "simple" tasks.
 
 No release without passing validation. [→ Why](references/quality-gates.md)
+
+Example TodoWrite structure:
+- [ ] Phase 0: Prime — load context, identify required checks
+- [ ] Phase 1: Execute — run tests and quality checks
+- [ ] Phase 2: Validate — analyze results against gates
+- [ ] Phase 3: Checkpoint — save report, suggest next step
 </HARD-GATE>
 
 ## Phases
 
 0. [Prime](phases/0-prime.md) — Load context, identify checks
 1. [Execute](phases/1-execute.md) — Run tests and quality checks
-2. [Validate](phases/2-validate.md) — Analyze results against gates
+2. [Validate](phases/2-validate.md) — Analyze results against gates. If failures → fix and re-run before proceeding
 3. [Checkpoint](phases/3-checkpoint.md) — Save report, suggest /release or fix