@leeovery/claude-technical-workflows 2.1.16 → 2.1.17

package/agents/implementation-analysis-architecture.md

@@ -27,6 +27,8 @@ You receive via the orchestrator's prompt:
 - Integration test gaps — are cross-task workflows tested end-to-end?
 - Seam quality between task boundaries — do the pieces fit together cleanly?
 - Over/under-engineering — are abstractions justified by usage? Is raw code crying out for structure?
+- Missed composition opportunities — are new abstractions independently implemented when they could be derived from existing ones? If two queries are logical inverses, one should be defined in terms of the other.
+- Type safety at boundaries — are interfaces or function signatures using untyped parameters when the concrete types are known? Runtime type checks inside implementations signal the signature should be more specific.
 
 ## Your Process
 

package/agents/implementation-task-reviewer.md

@@ -42,10 +42,12 @@ Are all criteria genuinely met — not just self-reported?
 - Check for criteria that are technically met but miss the intent
 
 ### 3. Test Adequacy
-Do tests actually verify the criteria? Are edge cases covered?
+Do tests actually verify the criteria? Are assertions precise? Are edge cases covered?
 - Is there a test for each acceptance criterion?
 - Would the tests fail if the feature broke?
 - Are edge cases from the task's test cases covered?
+- **Assertion depth**: For mutation operations, do tests verify observable side effects — not just that the operation returned success? State changes should be asserted independently.
+- **Assertion precision**: When expected output is deterministic, do tests use exact comparison? Substring or partial matching masks formatting regressions and missing/extra content.
 - Flag both under-testing AND over-testing
 
 ### 4. Convention Adherence
@@ -61,6 +63,7 @@ Is this a sound design decision? Will it compose well with future tasks?
 - Are there coupling or abstraction concerns?
 - Will this cause problems for subsequent tasks in the phase?
 - Are there structural concerns that should be raised now rather than compounding?
+- Are concrete types used where data structures are known? Flag untyped escape hatches used where concrete types would be clearer and safer.
 
 ## Fix Recommendations (needs-changes only)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.1.16",
+  "version": "2.1.17",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/technical-implementation/references/code-quality.md

@@ -12,8 +12,11 @@ Apply standard quality principles. Defer to project-specific skills for framewor
 - Extract repeated logic after three instances (Rule of Three)
 - Avoid premature abstraction for code used once or twice
 
+### Compose, Don't Duplicate
+When new behavior is the logical inverse or subset of existing behavior, derive it from the existing abstraction rather than implementing independently. If you have a query for "ready items," the query for "blocked items" should be "open AND NOT ready" — not an independently authored query that could drift. Prefer mathematical relationships (derived = total - computed) over parallel computations that must be kept in sync.
+
 ### SOLID
-- **Single Responsibility**: Each class/function does one thing
+- **Single Responsibility**: Each class/function does one thing. Multi-step logic should decompose into named helper functions — each step a function, each name documents intent.
 - **Open/Closed**: Extend behavior without modifying existing code
 - **Liskov Substitution**: Subtypes must be substitutable for base types
 - **Interface Segregation**: Don't force classes to implement unused methods
@@ -25,6 +28,9 @@ Keep low. Fix with early returns and method extraction.
 ### YAGNI
 Only implement what's in the plan. Ask: "Is this in the plan?"
 
+### Concrete Over Abstract
+Prefer concrete types over language-level escape hatches that bypass the type system. Use specific types for data passing between layers, not untyped containers. If you need polymorphism, define a named interface/protocol with specific methods — don't pass untyped values. If you find yourself writing runtime type checks or casts inside a function, the signature is too abstract.
+
 ## Testability
 - Inject dependencies
 - Prefer pure functions
@@ -36,6 +42,8 @@ Only implement what's in the plan. Ask: "Is this in the plan?"
 - Deep nesting (3+)
 - Long parameter lists (4+)
 - Boolean parameters
+- Untyped parameters when concrete types are known at design time
+- Substring assertions in tests when exact output is deterministic
 
 ## Project Standards
 Check `.claude/skills/` for project-specific patterns.

package/skills/technical-implementation/references/tdd-workflow.md

@@ -42,7 +42,9 @@ But write **complete, functional implementations** - don't artificially minimize
 
 **Derive tests from plan**: Task's micro acceptance becomes your first test. Edge cases become additional tests.
 
-**Write test names first**: List all test names before writing bodies. Confirm coverage matches acceptance criteria.
+**Assert precisely**: For mutation operations (create, update, delete, state transitions), don't just assert the return value — verify observable side effects independently. A test that checks "operation succeeded" but ignores whether timestamps updated, related records changed, or output structure is correct will miss regressions that only affect side effects. Assert structured output by parsing and checking fields/values, not by string matching the serialized form.
+
+**Write test names first**: List all test names before writing bodies. Confirm coverage matches acceptance criteria. Then consider: invalid input types, boundary values, zero/nil/empty inputs, single vs multiple items, and success alongside failure paths — add tests for any that are relevant and non-trivial.
 
 **No implementation code exists yet.** If you're tempted to "just sketch out the class first" - don't. The test comes first. Always.