diff --git a/skills/analyzing-test-effectiveness/SKILL.md b/skills/analyzing-test-effectiveness/SKILL.md index c0ef5afc..cace66e3 100644 --- a/skills/analyzing-test-effectiveness/SKILL.md +++ b/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" --- @@ -12,39 +12,69 @@ MEDIUM FREEDOM - Follow the audit flow strictly, but adapt the exact categories -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 | -- 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 ## 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//` 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. + + + +Test suite has 90% coverage but a critical bug shipped + + +- 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 + + + +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. + + + + + +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 + diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index 01816bbd..0ddfede8 100644 --- a/skills/executing-plans/SKILL.md +++ b/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" --- diff --git a/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.md index 5b634174..7a739a98 100644 --- a/skills/finishing-a-development-branch/SKILL.md +++ b/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" --- @@ -12,33 +12,72 @@ MEDIUM FREEDOM - Verify first, then present integration choices and execute the -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//` | Clean workspace | -- 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 ## 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/`. + + + +Developer says "I'm done" but tasks.md still has Now items + + +- Unfinished items get silently dropped +- Acceptance checks may lack evidence for those items +- The branch lands incomplete work + + + +Re-read `tasks.md` first. If `Now` items remain, either complete them or explicitly move them to a follow-up before finishing. + + + + +Developer merges but leaves stale task directory behind + + +- Next session sees stale docs and tries to resume finished work +- `plans/active/` becomes cluttered with dead directories +- Context pollution on future task searches + + + +Always delete the `plans/active//` directory after integration. Finished directories are not archived — they are removed. + + + + + +Called after: +- `review-implementation` +- `verification-before-completion` + diff --git a/skills/testing-anti-patterns/SKILL.md b/skills/testing-anti-patterns/SKILL.md index de670650..10652bce 100644 --- a/skills/testing-anti-patterns/SKILL.md +++ b/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)" --- diff --git a/skills/using-hyper/SKILL.md b/skills/using-hyper/SKILL.md index a570e43e..41139405 100644 --- a/skills/using-hyper/SKILL.md +++ b/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" --- @@ -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/`. - -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//`. -5. Keep `plan.md`, `context.md`, and `tasks.md` current. - - -- 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 ## 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//plan.md` -- `plans/active//context.md` -- `plans/active//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//` 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.