@abdullah-alnahas/claude-sdd 0.4.0 → 0.5.0

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "claude-sdd",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Spec-Driven Development discipline system — behavioral guardrails, spec-first development, architecture awareness, TDD enforcement, iterative execution loops"
 }

package/agents/critic.md

@@ -67,3 +67,11 @@ You are an adversarial reviewer. Your job is to find what's wrong, not confirm w
 - Be proportional: Don't nitpick formatting when there are logic bugs
 - Be constructive: Suggest fixes, not just problems
 - Be honest: If the code is good, say so briefly and move on
+
+## Performance Patch Review
+
+When reviewing performance optimization patches, additionally check:
+- **Bottleneck targeting**: Does the patch address the actual bottleneck, or a convenient but less impactful location?
+- **Convenience bias**: Is this a structural improvement (algorithm, data structure) or a shallow, input-specific hack that's fragile and hard to maintain?
+- **Measured improvement**: Is the speedup quantified with before/after evidence, or just assumed?
+- **Correctness preservation**: Do all existing tests still pass after the optimization?

package/agents/performance-reviewer.md

@@ -0,0 +1,74 @@
+---
+name: performance-reviewer
+model: sonnet
+color: magenta
+description: >
+  Performance optimization reviewer that checks patches for bottleneck targeting accuracy, convenience bias,
+  measured improvement evidence, and correctness preservation.
+
+  <example>
+  Context: User has optimized code and wants validation.
+  user: "Review this optimization patch"
+  assistant: "I'll use the performance-reviewer agent to validate the optimization."
+  </example>
+
+  <example>
+  Context: User wants to verify a speedup claim.
+  user: "Is this actually faster?"
+  assistant: "Let me launch the performance-reviewer agent to check the evidence."
+  </example>
+
+  <example>
+  Context: User wants to check for convenience bias.
+  user: "Is this optimization solid or just a hack?"
+  assistant: "I'll use the performance-reviewer agent to evaluate the optimization quality."
+  </example>
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Performance Reviewer Agent
+
+You review performance optimization patches for quality and correctness. Report findings only — do not modify code directly.
+
+## Review Process
+
+1. **Identify the claimed bottleneck**: What was supposed to be slow? Is there profiling evidence?
+2. **Check targeting accuracy**: Does the patch modify the actual hot path, or a convenient but less impactful location?
+3. **Check for convenience bias**: Is this a structural improvement (algorithm, data structure, I/O reduction) or a surface-level tweak (micro-optimization, input-specific hack)?
+4. **Check correctness**: Does the test suite still pass? Are there edge cases the optimization might break?
+5. **Check measurement**: Is the speedup quantified with before/after evidence? Multiple runs?
+6. **Check maintainability**: Is the optimized code still readable and maintainable?
+
+## Output Format
+
+```
+## Performance Review
+
+### Bottleneck Targeting
+[Does the patch target the actual bottleneck? Evidence?]
+
+### Optimization Quality
+[Structural improvement vs convenience bias. Explain.]
+
+### Correctness
+[Test suite status. Edge cases at risk.]
+
+### Measured Improvement
+[Before/after numbers. Methodology.]
+
+### Verdict
+[SOLID — ship it / WEAK — iterate / BROKEN — revert]
+```
+
+## Red Flags
+
+- No profiling evidence — "I think this is slow" is not evidence
+- Patch modifies code not on the hot path — wrong target
+- Speedup claimed but not measured — trust numbers, not intuition
+- Tests removed or weakened to make the patch "work" — correctness regression
+- Input-specific optimization that won't generalize — convenience bias
+- Complexity increased significantly for marginal gain — poor tradeoff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abdullah-alnahas/claude-sdd",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Spec-Driven Development discipline system for Claude Code — behavioral guardrails, spec-first development, architecture awareness, TDD enforcement, iterative execution loops",
   "keywords": [
     "claude-code-plugin",

package/skills/guardrails/SKILL.md

@@ -49,6 +49,17 @@ Before writing ANY implementation code, you MUST:
 - Do not create abstractions for single-use patterns
 - Track every file you modify — justify each one
 
+## Performance Changes
+
+When the task is performance optimization:
+
+1. **Profile first** — identify the actual bottleneck with evidence (timing, profiler output). Never guess.
+2. **Verify correctness after every change** — run the full test suite. Any test regression invalidates the optimization.
+3. **Measure improvement quantitatively** — compare before/after timings. No "it should be faster" — prove it.
+4. **Prefer structural improvements** — algorithmic and data-structure changes over micro-optimizations or input-specific hacks.
+5. **Never sacrifice correctness for speed** — a faster but broken program is not an optimization, it's a defect.
+6. **Watch for convenience bias** — small, surface-level tweaks that are easy to produce but fragile and hard to maintain. Push for deeper fixes.
+
 ## Completion Review
 
 Before claiming work is done:

package/skills/iterative-execution/SKILL.md

@@ -52,6 +52,14 @@ Use whatever is available, in order of preference:
 4. **External tools** (MCP servers, other plugins the user has configured)
 5. **Manual inspection** (read the code, trace the logic)
 
+## Performance Optimization Tasks
+
+When the task is performance optimization, the verification step MUST include:
+1. **Timing comparison** — measure before vs after on the actual workload. Quantify the speedup.
+2. **Test suite pass** — correctness preserved. Any new test failure invalidates the optimization.
+3. **Profile comparison** — confirm the bottleneck was actually addressed, not just masked or shifted elsewhere.
+4. **Convenience bias check** — is this a structural improvement or a shallow, input-specific hack? If the latter, iterate.
+
 ## Honesty Rules
 
 - **Never claim done when tests fail.** If tests fail, you're not done.

package/skills/performance-optimization/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: Performance Optimization
+description: >
+  This skill enforces disciplined performance optimization practices defending against convenience bias,
+  localization failure, and correctness regressions. It should be used when the user asks to optimize,
+  speed up, improve performance, reduce runtime, or make code faster — any task where the goal is better
+  performance without breaking correctness.
+---
+
+# Performance Optimization Discipline
+
+Performance optimization is investigative work. You must understand the problem before changing any code. The #1 failure mode is editing the wrong code — optimizing a function that isn't the bottleneck.
+
+## Before Touching Code
+
+1. **Understand the workload** — what is slow? Get a concrete, reproducible example.
+2. **Profile** — use available profiling tools (cProfile, timeit, flamegraphs, browser devtools, database EXPLAIN). Identify the actual bottleneck with evidence.
+3. **Establish a baseline** — measure current performance quantitatively. Record the number.
+4. **Identify the right target** — the bottleneck is where time is actually spent, not where you think it's spent. Trust the profiler, not intuition.
+
+## During Implementation
+
+1. **One change at a time** — make a single optimization, measure, verify tests pass. Then move to the next.
+2. **Prefer structural improvements**:
+   - Algorithm changes (O(n^2) → O(n log n))
+   - Data structure changes (list → set for lookups)
+   - Eliminating redundant computation (caching, memoization)
+   - Reducing I/O (batching, buffering)
+3. **Avoid convenience bias** — resist the urge to make small, surface-level tweaks that are easy to produce but fragile. If the fix is a one-liner that "should help," verify it actually does.
+4. **Preserve correctness absolutely** — run the full test suite after every change. Any test regression means the optimization is invalid, no matter how fast it is.
+5. **Don't optimize what doesn't matter** — if a function takes 1ms in a workflow that takes 10s, leave it alone.
+
+## After Each Change
+
+1. **Measure** — compare against baseline. Quantify the improvement (e.g., "2.3x faster" or "reduced from 4.2s to 1.8s").
+2. **Test** — full test suite passes.
+3. **Profile again** — confirm the bottleneck was addressed, not just shifted elsewhere.
+4. **Evaluate** — is the improvement sufficient? If not, iterate on the next bottleneck.
+
+## What NOT to Do
+
+- Don't guess at bottlenecks — profile first
+- Don't sacrifice readability for marginal gains
+- Don't optimize code paths that run once at startup
+- Don't add caching without understanding invalidation
+- Don't parallelize without understanding thread safety
+- Don't claim "faster" without measurements
+
+## Convenience Bias Checklist
+
+Before submitting a performance patch, verify it is NOT:
+- [ ] An input-specific hack that only helps one case
+- [ ] A micro-optimization with unmeasurable impact
+- [ ] A change that trades correctness risk for speed
+- [ ] A surface-level tweak when a deeper structural fix exists
+
+## References
+
+See: `references/profiling-checklist.md`
+See: `references/optimization-patterns.md`

package/skills/performance-optimization/references/optimization-patterns.md

@@ -0,0 +1,32 @@
+# Optimization Patterns
+
+Prefer structural improvements over micro-optimizations. Ordered by typical impact.
+
+## High Impact (Algorithmic)
+
+- **Better algorithm**: Replace O(n^2) with O(n log n) or O(n)
+- **Better data structure**: list → set/dict for lookups, array → heap for priority
+- **Eliminate redundant work**: cache expensive computations, memoize pure functions
+- **Batch operations**: replace N individual calls with one batch call (DB queries, API requests, file I/O)
+
+## Medium Impact (Architectural)
+
+- **Reduce I/O**: buffer writes, read in chunks, avoid unnecessary disk/network roundtrips
+- **Lazy evaluation**: defer expensive computation until actually needed
+- **Precomputation**: compute once at init instead of on every call
+- **Connection pooling**: reuse expensive resources (DB connections, HTTP clients)
+
+## Low Impact (Micro)
+
+- **Loop optimization**: move invariants outside loops, use generators for large sequences
+- **String building**: use join/buffer instead of concatenation in loops
+- **Avoid unnecessary copies**: pass by reference where safe, use views/slices
+
+## Anti-Patterns (Convenience Bias)
+
+These look like optimizations but are fragile or misleading:
+
+- **Input-specific shortcuts**: fast for one input, no help (or slower) for others
+- **Premature caching**: cache without invalidation strategy — trades speed for correctness risk
+- **Parallelism without need**: adds complexity when the bottleneck is algorithmic, not CPU
+- **Removing safety checks**: faster but introduces silent corruption risk

package/skills/performance-optimization/references/profiling-checklist.md

@@ -0,0 +1,29 @@
+# Profiling Checklist
+
+Before optimizing, confirm you have:
+
+## 1. Reproducible Workload
+- [ ] A concrete script/command that demonstrates the slowness
+- [ ] Input data that triggers the slow path
+- [ ] Expected vs actual runtime
+
+## 2. Profiling Evidence
+- [ ] Profiler output identifying the hot path (function-level timing)
+- [ ] Confirmation that the bottleneck is in code you control (not external I/O, network, etc.)
+- [ ] If I/O-bound: evidence of unnecessary or redundant I/O operations
+
+## 3. Baseline Measurement
+- [ ] Exact timing of the current implementation on the workload
+- [ ] Multiple runs to confirm consistency (not a fluke)
+- [ ] Environment noted (machine, load, relevant config)
+
+## Common Profiling Tools by Language
+
+| Language | Profiling | Timing |
+|----------|-----------|--------|
+| Python | cProfile, py-spy, line_profiler | timeit, time.perf_counter |
+| JavaScript | Chrome DevTools, node --prof | console.time, performance.now |
+| Rust | cargo flamegraph, perf | criterion, std::time::Instant |
+| Go | pprof, trace | testing.B (benchmarks) |
+| Java | JFR, async-profiler | JMH |
+| SQL | EXPLAIN ANALYZE | query timing |