feat: improve skill review scores for 5 skills

skills/analyzing-test-effectiveness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analyzing-test-effectiveness
-description: Use to audit test quality with SRE scrutiny - identifies weak tests, missing cases, and creates task docs for improvements
+description: "Use when reviewing test quality, investigating test gaps, or when test coverage is high but bugs still escape - audits each test for tautologies, weak assertions, and mock-heavy patterns, classifies tests as strong/weak/misleading, identifies missing edge cases, and creates a task directory with a prioritized improvement backlog"
 ---
 
 <skill_overview>
@@ -12,39 +12,69 @@ MEDIUM FREEDOM - Follow the audit flow strictly, but adapt the exact categories
 </rigidity_level>
 
 <quick_reference>
-1. Inventory the tests
-2. Classify them as strong, weak, or misleading
-3. Identify missing edge cases
-4. Create or update a task directory for test-quality improvements
+| Step | Action | Output |
+|------|--------|--------|
+| 1 | Inventory the test suite | List of all test files and test count |
+| 2 | Classify each test | Strong / Weak / Misleading rating with reason |
+| 3 | Identify missing edge cases | Gap list mapped to production risk |
+| 4 | Create improvement backlog | Task directory with remove / strengthen / add items |
 </quick_reference>
 
 <when_to_use>
-- Coverage looks good but bugs still escape
-- A test suite feels noisy or low-signal
-- You want a quality-improvement backlog for tests
+- Test coverage looks good but bugs still escape to production
+- Test suite feels noisy, flaky, or low-signal
+- After a production incident to check if tests should have caught it
+- Before a major refactor to understand which tests actually protect behavior
+- When test run time is high and you need to identify low-value tests to cut
 </when_to_use>
 
 <the_process>
 ## 1. Audit the suite
 
-Look for:
-- tautological tests
-- mock-heavy tests that prove little
-- weak assertions
-- missing edge cases
+For each test file, classify tests by scanning for:
+- **Tautological tests** — assertions that can never fail (e.g. `assert_eq!(mock.value(), mock.value())`)
+- **Mock-heavy tests** — more mock setup than actual behavior verification
+- **Weak assertions** — checking existence instead of correctness (e.g. `assert!(result.is_some())` without checking the value)
+- **Missing edge cases** — no tests for error paths, boundary values, or concurrent access
 
 ## 2. Explain each finding
 
-For every weak area, say what real bug it would or would not catch.
+For every weak area, describe:
+- What real bug it would or would not catch
+- The production risk if left unaddressed
+- Severity: critical (false confidence) / moderate (partial coverage) / low (style)
 
 ## 3. Turn findings into tracked work
 
-Create or update a task directory that captures:
-- which tests to remove
-- which tests to strengthen
-- which missing scenarios to add
+Create or update a task directory at `plans/active/<slug>/` that captures:
+- Which tests to **remove** (misleading or tautological)
+- Which tests to **strengthen** (weak assertions or over-mocked)
+- Which missing scenarios to **add** (ordered by production risk)
 
 ## 4. Refine before execution
 
 Use `sre-task-refinement` to harden the improvement plan before implementation.
 </the_process>
+
+<examples>
+<example>
+<scenario>Test suite has 90% coverage but a critical bug shipped</scenario>
+
+<why_it_fails>
+- Coverage counted lines hit, not behavior validated
+- Most tests asserted on mock existence, not real output
+- The specific failure path had no test at all
+</why_it_fails>
+
+<correction>
+Audit each test: does this assertion prove the code works, or just that the test runs? Classify, then build a backlog prioritized by production risk.
+</correction>
+</example>
+</examples>
+
+<integration>
+Calls:
+- `sre-task-refinement` to harden the improvement plan
+- `test-driven-development` when writing replacement tests
+- `testing-anti-patterns` gate functions when evaluating mock usage
+</integration>

skills/executing-plans/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: executing-plans
-description: Use to execute an approved local markdown task directory iteratively - work the current Now slice, update docs, then stop
+description: "Use when implementing a task from a plans/active/ directory, resuming work after a break, or continuing an approved plan - loads plan.md/context.md/tasks.md, works only the current Now slice (1-2 items), updates docs with discoveries, and stops at a review checkpoint"
 ---
 
 <skill_overview>

skills/finishing-a-development-branch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finishing-a-development-branch
-description: Use when implementation is complete and verified - delete finished local task docs, present integration options, and clean up safely
+description: "Use when a task is done, a feature is complete, or you need to wrap up and clean up a branch - re-reads plan.md to verify acceptance checks have evidence, presents integration options (merge, PR, keep, or discard), and deletes the finished plans/active/ task directory"
 ---
 
 <skill_overview>
@@ -12,33 +12,72 @@ MEDIUM FREEDOM - Verify first, then present integration choices and execute the
 </rigidity_level>
 
 <quick_reference>
-1. Re-read `plan.md`, `context.md`, and `tasks.md`
-2. Confirm acceptance checks and verification evidence
-3. Present integration options: merge/PR, keep branch, discard branch
-4. Delete the local task directory under `plans/active/`
+| Step | Action | Output |
+|------|--------|--------|
+| 1 | Re-read `plan.md`, `context.md`, `tasks.md` | Completeness check |
+| 2 | Confirm acceptance checks have evidence | Pass/fail per check |
+| 3 | Present integration options | User chooses: merge/PR, keep, or discard |
+| 4 | Delete `plans/active/<slug>/` | Clean workspace |
 </quick_reference>
 
 <when_to_use>
-- Work is implemented and verified
-- The task directory is ready to close
-- The user needs a clean finish to the branch
+- All tasks are done and the user says "finished", "done", or "wrap up"
+- The task directory has no remaining `Now` items
+- The user wants to clean up a completed branch
+- After `verification-before-completion` confirms the work is ready
 </when_to_use>
 
 <the_process>
 ## 1. Confirm the work is actually complete
 
 - `tasks.md` should have no active `Now` items
-- acceptance checks in `plan.md` should have evidence
-- verification should be fresh
+- Acceptance checks in `plan.md` should have evidence
+- Verification should be fresh (not stale from an earlier iteration)
 
 ## 2. Present the integration choice
 
 Offer the user clear options:
-- merge or open PR
-- keep the branch for more work
-- discard the branch if the work should not land
+- **Merge or open PR** — land the work on the target branch
+- **Keep the branch** — more work is planned
+- **Discard the branch** — the work should not land
 
 ## 3. Delete the local docs
 
 Delete the completed local task directory from `plans/active/`.
 </the_process>
+
+<examples>
+<example>
+<scenario>Developer says "I'm done" but tasks.md still has Now items</scenario>
+
+<why_it_fails>
+- Unfinished items get silently dropped
+- Acceptance checks may lack evidence for those items
+- The branch lands incomplete work
+</why_it_fails>
+
+<correction>
+Re-read `tasks.md` first. If `Now` items remain, either complete them or explicitly move them to a follow-up before finishing.
+</correction>
+</example>
+
+<example>
+<scenario>Developer merges but leaves stale task directory behind</scenario>
+
+<why_it_fails>
+- Next session sees stale docs and tries to resume finished work
+- `plans/active/` becomes cluttered with dead directories
+- Context pollution on future task searches
+</why_it_fails>
+
+<correction>
+Always delete the `plans/active/<slug>/` directory after integration. Finished directories are not archived — they are removed.
+</correction>
+</example>
+</examples>
+
+<integration>
+Called after:
+- `review-implementation`
+- `verification-before-completion`
+</integration>

skills/testing-anti-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing-anti-patterns
-description: Use when writing or changing tests, adding mocks - prevents testing mock behavior, production pollution with test-only methods, and mocking without understanding dependencies
+description: "Use when writing tests, adding mocks, or when test setup is becoming complex - enforces three iron laws: never test mock behavior (test real components instead), never add test-only methods to production code (use test utilities), and never mock without understanding dependency side effects (mock at the lowest level needed)"
 ---
 
 <skill_overview>

skills/using-hyper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-hyper
-description: Use when starting any conversation - establishes skill selection and the local task-doc workflow
+description: "Use when starting a new task, initializing a workspace, or setting up a project - scans available skills, selects relevant ones, reads them from disk, and initializes a plans/active/ task directory to track progress through plan.md, context.md, and tasks.md"
 ---
 
 <skill_overview>
@@ -11,25 +11,18 @@ Skills are mandatory when they apply, and substantial work must stay grounded in
 HIGH FREEDOM - The meta-process is rigid: check for skills, read them from disk, announce usage, and keep work anchored in `plans/active/`.
 </rigidity_level>
 
-<quick_reference>
-1. Check if any skill applies.
-2. Read the relevant `SKILL.md` from disk.
-3. Announce which skill you are using.
-4. For substantial work, create or resume a local `plans/active/<slug>/`.
-5. Keep `plan.md`, `context.md`, and `tasks.md` current.
-</quick_reference>
-
 <when_to_use>
-- At the start of every conversation
-- Before starting any non-trivial task
+- Starting a new task or resuming an existing one
+- Before any non-trivial feature, refactor, or bug fix
 - Before editing skills, hooks, docs, or code
+- When unsure which workflow to follow
 </when_to_use>
 
 <the_process>
 ## 1. Check for skills first
 
-- If a skill matches, use it.
-- Never rely on memory; read the file from disk.
+- Scan available skills for a match to the current request.
+- Never rely on memory; read the matching `SKILL.md` from disk.
 - Announce the skill before acting.
 
 ## 2. Ground large work in task docs
@@ -39,20 +32,17 @@ For features, rewrites, and multi-step tasks:
 - `writing-plans` distills it into task docs
 - `executing-plans` implements the current `Now` slice
 
-Use:
-- `plans/active/<slug>/plan.md`
-- `plans/active/<slug>/context.md`
-- `plans/active/<slug>/tasks.md`
-
-These task directories are local working state. Delete the finished directory instead of archiving it.
+Create or resume a task directory at `plans/active/<slug>/` with three files:
 
-## 3. Treat the docs as distinct tools
+| File | Purpose |
+|------|---------|
+| `plan.md` | Approved intent and acceptance contract — stable once approved |
+| `context.md` | Living discovery log — key files, decisions, resume notes |
+| `tasks.md` | Rolling execution backlog — Now / Next / Later / Blocked / Done |
 
-- `plan.md` is the approved intent and acceptance contract
-- `context.md` is the living discovery log
-- `tasks.md` is the rolling execution backlog
+These task directories are local working state. Delete the finished directory instead of archiving it.
 
-## 4. Verify before claiming completion
+## 3. Verify before claiming completion
 
 Use `verification-before-completion` before any completion claim.
 </the_process>