devflow-kit 3.12.1 → 3.14.0

package/src/assets/skills/design-review/SKILL.md

@@ -7,8 +7,6 @@ allowed-tools: Read, Grep, Glob
 
 # Design Review
 
-Anti-pattern detection for implementation plans.
-
 ## Iron Law
 
 > **CATCH IT IN THE PLAN, NOT IN THE PR**
@@ -19,13 +17,13 @@ Anti-pattern detection for implementation plans.
 
 ## Anti-Pattern Detection Rules
 
+A concrete case is an external call in this change, a stated or measured hot path, or a repeated delivery.
+
 ### 1. N+1 Queries
 
 **What to look for in a plan:**
 - Steps that fetch a list, then loop to fetch related data per item
-- "For each X, get Y" language without mentioning batch operations
-- JOIN or batch-fetch never mentioned for related data
-- "Display X with Y" without specifying how Y is fetched
+- "For each X, get Y" or "Display X with Y" language, with no JOIN or batch fetch named
 
 **How to flag:**
 ```
@@ -41,7 +39,7 @@ Resolution: Replace loop with batch query: {proposed batch operation}.
 - Single step handling more than 3 distinct responsibilities
 - "Validate AND process AND notify AND log AND update" in one step
 - Steps described as "the main handler" that touch multiple subsystems
-- No clear single-sentence description of what the function does
+- No one-sentence description of what the function does
 
 **How to flag:**
 ```
@@ -54,8 +52,7 @@ Resolution: Split into: {responsibility 1} → {responsibility 2} → {responsib
 ### 3. Missing Parallelism
 
 **What to look for in a plan:**
-- Sequential steps with no data dependency between them
-- "First do A, then do B, then do C" where B doesn't need A's output
+- Sequential steps with no data dependency between them ("First do A, then B, then C")
 - Multiple external API calls or DB queries listed sequentially
 - Fan-out operations (notify all users, update all records) without parallel mention
 
@@ -72,9 +69,9 @@ Resolution: Execute {step A} and {step B} in parallel: {proposed parallel patter
 **What to look for in a plan:**
 - Happy path fully described, failure paths absent or vague
 - "If error, return error" without specifying what the caller does with it
-- Partial operations (multi-step) without rollback plan
+- Partial operations (multi-step) that can lose data, without rollback plan
 - External calls (API, DB, queue) without failure mode specification
-- Retry logic absent for transient failures (network timeouts, rate limits)
+- Retry or compensation absent: a finding only with a concrete case. Error handling at a trust boundary or for data loss needs no case.
 
 **How to flag:**
 ```
@@ -82,12 +79,12 @@ Resolution: Execute {step A} and {step B} in parallel: {proposed parallel patter
 Resolution: Add: {on failure scenario} → {specific recovery action}.
 ```
 
-**Suggest:** for each external call, the action on timeout, 4xx and 5xx; a compensation step for each step of a multi-step operation; Result types or explicit error returns, never a silent failure.
+**Suggest:** for each external call, the action on timeout, 4xx and 5xx; a compensation step only for a partial write that loses data; Result types or explicit error returns, never a silent failure.
 
 ### 5. Missing Caching
 
 **What to look for in a plan:**
-- Expensive operations called on every request without cache mention
+Only with a concrete case; else no finding.
 - "Fetch configuration on each request", "call third-party API per user action"
 - Reference data (categories, settings, permissions) loaded repeatedly
 - Computed aggregates recalculated on every read

package/src/assets/skills/design-review/references/anti-patterns.md

@@ -101,6 +101,8 @@ Step 5: Build user dashboard
 
 ## 4. Error Handling Gaps
 
+A retry or compensation finding needs a concrete case. Here it is the S3 and database calls of this change.
+
 ### Before (Anti-Pattern)
 ```
 Step 7: Implement file upload
@@ -126,13 +128,14 @@ Step 7: Implement file upload
     - Queue cleanup job to delete orphaned S3 object
     - Return 500, log error with S3 key for manual cleanup if queue fails
 - Return 201 with file URL and metadata
-- Idempotency: if file with same hash already exists for user, return existing URL (no duplicate upload)
 ```
 
 ---
 
 ## 5. Missing Caching
 
+A caching finding needs a concrete case. Here it is three calls on every request, at 1000 req/s.
+
 ### Before (Anti-Pattern)
 ```
 Step 2: Load application configuration

package/src/assets/skills/gap-analysis/SKILL.md

@@ -59,7 +59,7 @@ Domain expertise for detecting gaps in design documents, specifications, and pla
 
 **Detection patterns:**
 - N+1 patterns implied — loop-based data fetching without batch operation specified
-- Missing caching strategy — repeated expensive operations (DB queries, API calls) without cache layer
+- Missing caching strategy — repeated expensive calls on a stated or measured hot path, without cache layer
 - Concurrency concerns — shared mutable state accessed without locking or isolation strategy
 - Query patterns — filtering/sorting on unindexed fields implied by the feature
 - Unbounded result sets — list operations without pagination or size limits
@@ -101,5 +101,5 @@ Domain expertise for detecting gaps in design documents, specifications, and pla
 |-------|----------|----------|
 | **CRITICAL** | Gap that will cause data loss, security breach, or system failure | Missing auth on sensitive endpoint, undefined error recovery for financial transaction |
 | **HIGH** | Gap that will cause incorrect behavior or significant technical debt | Missing pagination on unbounded list, undefined race condition in concurrent update |
-| **MEDIUM** | Gap that will require rework if unaddressed | Vague acceptance criteria, missing caching strategy for frequently-read data |
+| **MEDIUM** | Gap that will require rework if unaddressed | Vague acceptance criteria, missing caching on a stated hot path |
 | **LOW** | Gap that is an improvement opportunity | Naming inconsistency, minor UX ambiguity with obvious resolution |

package/src/assets/skills/git/references/patterns.md

@@ -233,6 +233,9 @@ git commit -m "refactor(utils): simplify string helper functions"
 ### Testing Gaps
 {Honest assessment}
 
+## Known Limits
+{Accepted risks and deferred items, one line each, or "None"}
+
 ## Related Issues
 Closes #{issue}
 

package/src/assets/skills/patterns/SKILL.md

@@ -7,8 +7,6 @@ allowed-tools: Read, Grep, Glob
 
 # Implementation Patterns
 
-Reference for common implementation patterns.
-
 ## Iron Law
 
 > **FOLLOW EXISTING PATTERNS**
@@ -35,7 +33,7 @@ A bad parameter returns 400 and a failed authentication 401 before any work runs
 
 **Core pattern**: Validate event -> Process -> Handle errors -> Acknowledge
 
-Make each handler idempotent, so a redelivered event does no harm. Log an invalid event as a warning and drop it; do not throw.
+Make a handler idempotent only when the change has a repeated delivery (a retry, a queue, a webhook). Log an invalid event as a warning and drop it; do not throw.
 
 ### Configuration
 
@@ -69,7 +67,7 @@ Before implementing, verify:
 - [ ] Handling all error cases explicitly
 - [ ] Using transactions for multi-step operations
 - [ ] No hardcoded values (use config)
-- [ ] Input validated at system boundaries; operations idempotent where possible
+- [ ] Input validated at system boundaries; idempotent only for a repeated delivery
 
 ## Extended References
 

package/src/assets/skills/quality-gates/SKILL.md

@@ -30,7 +30,7 @@ Does the implementation fit the architecture? Follows existing patterns, respect
 If `FEATURE_KNOWLEDGE` is provided (Rules bullets and the KB path, no heading index), verify implementation respects each bullet's anti-pattern, gotcha or invariant; Read a KB section from its path for the architecture. Flag deviations as P0-Design issues when the documented pattern is clearly intentional.
 
 ### P0 - Functionality
-Does the code work? Happy path, edge cases (null, empty, boundary), no race conditions.
+Does the code work? Each acceptance criterion (else each behaviour the diff adds) holds, each named edge case is handled, no race conditions.
 
 ### P0 - Security
 Any vulnerabilities? No injection, input validated, no hardcoded secrets, no secrets or tokens in logs or debug output, auth checked.
@@ -42,7 +42,7 @@ Understandable in 5 minutes? Functions < 50 lines, nesting < 4 levels, no magic
 Errors handled explicitly? No swallowed exceptions, helpful messages, resources cleaned up.
 
 ### P1 - Tests
-New code tested? Covers happy path, errors, edges. Tests behavior, not implementation.
+New code tested? A test for each acceptance-criterion behaviour (else each behaviour the diff adds) and for each trust-boundary, data-loss, security or fail-closed path; an edge-case test only for a named case. Tests behavior, not implementation.
 
 ### P2 - Documentation
 Will others understand? Complex logic commented, public APIs documented, no outdated comments.

package/src/assets/skills/quality-gates/references/patterns.md

@@ -11,7 +11,7 @@ For each pillar, ask:
 | Pillar | Key Questions |
 |--------|---------------|
 | Design | Does this follow existing patterns? Is it maintainable? |
-| Functionality | Does it meet requirements? Handle edge cases? |
+| Functionality | Does it meet requirements? Handle named edge cases? |
 | Security | Is input validated? Auth checked? Data protected? |
 | Complexity | Can someone understand this in 5 minutes? |
 | Error Handling | Are errors handled with Result types? Logged? |
@@ -191,7 +191,7 @@ try {
 
 ### 6. Tests - Correct Patterns
 
-**Fix Pattern**: Add tests for all new functions, test behavior not mocks, cover edge cases.
+**Fix Pattern**: Add a test for each acceptance-criterion behaviour, test behavior not mocks, cover named edge cases.
 
 ```typescript
 // GOOD: Testing behavior
@@ -213,7 +213,7 @@ describe('createUser', () => {
   });
 });
 
-// GOOD: Edge case coverage
+// GOOD: A test for the named edge case
 describe('divide', () => {
   it('divides positive numbers', () => {
     expect(divide(10, 2)).toBe(5);

package/src/assets/skills/quality-gates/references/report-template.md

@@ -90,7 +90,7 @@ Add user profile update endpoint
 | Pillar | Status | Notes |
 |--------|--------|-------|
 | Design | PASS | Follows existing route/service pattern |
-| Functionality | PASS | All edge cases handled |
+| Functionality | PASS | Named edge cases handled |
 | Security | PASS | Auth middleware in place, input validated |
 
 ---
@@ -101,7 +101,7 @@ Add user profile update endpoint
 |--------|--------|-------|
 | Complexity | PASS | Functions under 30 lines |
 | Error Handling | PASS | Uses Result types consistently |
-| Tests | PASS | Happy path, errors, and edges covered |
+| Tests | PASS | Each acceptance-criterion behaviour covered |
 
 ---
 

package/src/assets/skills/quality-gates/references/violations.md

@@ -79,7 +79,7 @@ for (let i = 0; i <= array.length; i++) {  // Should be < not <=
 
 **Checklist**:
 - [ ] Happy path works correctly
-- [ ] Edge cases handled (null, empty, boundary values)
+- [ ] Named edge cases handled (null, empty, boundary values)
 - [ ] Error cases handled gracefully
 - [ ] No race conditions in concurrent code
 - [ ] No infinite loops or recursion without base case
@@ -204,7 +204,7 @@ it('creates user', async () => {
   expect(mockDb.insert).toHaveBeenCalled();  // Only checks mock was called
 });
 
-// BAD: Missing edge case tests
+// BAD: No test for a named edge case (division by zero)
 describe('divide', () => {
   it('divides numbers', () => {
     expect(divide(10, 2)).toBe(5);
@@ -215,9 +215,9 @@ describe('divide', () => {
 
 **Checklist**:
 - [ ] New code has corresponding tests
-- [ ] Tests cover happy path
-- [ ] Tests cover error cases
-- [ ] Tests cover edge cases
+- [ ] Tests cover each acceptance-criterion behaviour
+- [ ] Tests cover each trust-boundary, data-loss, security and fail-closed path
+- [ ] Edge-case tests exist only for named cases
 - [ ] Tests are not brittle (test behavior, not implementation)
 - [ ] Tests would fail if code breaks
 

package/src/assets/skills/test-driven-development/SKILL.md

@@ -19,7 +19,7 @@ activation:
 
 # Test-Driven Development
 
-Use the RED-GREEN-REFACTOR cycle for all implementation work. Tests define the design. Code satisfies the tests. Refactoring improves the design without changing behavior.
+Use the RED-GREEN-REFACTOR cycle for all implementation work. Refactoring improves the design without changing behavior.
 
 ## Iron Law
 
@@ -43,7 +43,7 @@ Write a test that describes the behavior you want. Run it. Watch it fail. The fa
 
 Write the simplest production code that makes the failing test pass. Hardcode first if that is simplest; generalize when the next test forces it. No code for later, no optimizing, no cleanup.
 
-**Checkpoint:** All affected tests pass. If any test fails, fix it before moving on.
+**Checkpoint:** All affected tests pass.
 
 ### Step 3: REFACTOR — Improve Without Changing Behavior
 
@@ -78,12 +78,12 @@ An excuse to skip the test-first step is a rationalization: reject it. `referenc
 
 ## What to Test
 
-Follow the project's test layout and conventions, and import the module under test, not its internal helpers.
+Follow the project's test layout, and import the module under test, not its helpers.
 
 | Test | Don't Test |
 |------|------------|
 | Public API behavior | Private implementation details |
-| Error conditions and edge cases | Framework internals |
+| Trust-boundary, data-loss, security and fail-closed paths; named edge cases | Framework internals |
 | Integration points (boundaries) | Third-party library correctness |
 | State transitions | Getter/setter plumbing (unless non-trivial) |
 
@@ -98,7 +98,7 @@ When you skip TDD, state the reason from this list: "Skipping TDD because: [reas
 
 ## By Mode
 
-- **IMPLEMENT**: write the failing test before production code, one behavior at a time. The Code agent preloads this skill.
+- **IMPLEMENT**: write the failing test before production code, one behavior at a time.
 - **DEBUG**: write a test that reproduces the bug first, then fix.
 - **PLAN**: the plan has a test strategy and orders test files first.
 - **RESOLVE**: the Code agent (issue-fix mode) writes a failing-then-passing regression test for every fix.

package/src/assets/skills/test-driven-development/references/rationalization-prevention.md

@@ -7,7 +7,7 @@ The excuses table, the mid-work red flags, a test-first example, and detailed co
 | Excuse | Why It Feels Right | Why It's Wrong | Correct Action |
 |--------|-------------------|----------------|----------------|
 | "I'll write tests after" | Need to see the shape first | Tests ARE the shape — they define the interface before implementation exists | Write the test first |
-| "Too simple to test" | It's just a getter/setter | Getters break, defaults change, edge cases hide in "simple" code | Write it — takes 30 seconds |
+| "Too simple to test" | It's just a getter/setter | Getters break and defaults change; code with an acceptance-criterion behaviour always gets its test | Test that behaviour — takes 30 seconds |
 | "I'll refactor later" | Just get it working now | "Later" never comes; technical debt compounds silently | Refactor now in Step 3 |
 | "Test is too hard to write" or "the test setup is too complex" | Mocking is painful | Hard-to-test code = bad design, and complex setup = too much coupling; the test is telling you the interface is wrong | Simplify the interface first |
 | "Need to see the whole picture" or "the architecture first" | Can't test what I haven't designed or structured yet | TDD IS design; each test reveals the next piece of the interface, and tests DEFINE the architecture | Let the tests drive the design and structure |

package/src/assets/skills/testing/SKILL.md

@@ -30,7 +30,7 @@ activation:
 |-------|---------|
 | Pyramid | Many unit → fewer integration → fewest E2E |
 | Trophy | Integration tests give best ROI for UI-heavy code |
-| Google | 70% unit / 20% integration / 10% E2E; avoid E2E excess |
+| Google | 70% unit / 20% integration / 10% E2E |
 
 ## Test Doubles Taxonomy
 
@@ -89,8 +89,8 @@ Quarantine flaky tests immediately — a suite that sometimes passes is worse th
 | Severity | Criteria |
 |----------|----------|
 | **CRITICAL** | Tests don't verify behavior; critical paths untested; everything mocked |
-| **HIGH** | Missing error paths; flaky tests; slow (>10s); setup >10 lines |
-| **MEDIUM** | Missing edge cases; weak assertions; unclear AAA structure |
+| **HIGH** | Untested trust-boundary, data-loss, security or fail-closed path; flaky tests; slow (>10s); setup >10 lines |
+| **MEDIUM** | Named edge case with no test; weak assertions; unclear AAA structure |
 | **LOW** | Organization; naming clarity |
 
 ## Test Suite Safety
@@ -103,17 +103,17 @@ Quarantine flaky tests immediately — a suite that sometimes passes is worse th
 
 | Reference | Contents |
 |-----------|----------|
-| `references/sources.md` | Full bibliography (20 sources) |
-| `references/violations.md` | Extended violations with citations |
+| `references/sources.md` | Bibliography (20 sources) |
+| `references/violations.md` | Violations with citations |
 | `references/patterns.md` | Correct patterns with citations |
-| `references/detection.md` | Bash commands for automated detection |
-| `references/report-template.md` | Report format for documenting issues |
+| `references/detection.md` | Detection commands |
+| `references/report-template.md` | Report format |
 
 ## Quality Gates
 
-- [ ] Setup <10 lines; use fakes over mocks for complex dependencies
+- [ ] Setup <10 lines
 - [ ] Each new assertion would fail, not error, with the change reverted: its RED run counts, else a bad input or a temporary uncommitted revert of your own edit, never a stash
-- [ ] All branches covered: happy path + errors + edge cases
+- [ ] A test for each acceptance-criterion behaviour; an edge-case test only for a named case
 - [ ] Test names describe expected behavior
 - [ ] Tests follow Arrange-Act-Assert structure
 - [ ] No flaky patterns

package/src/assets/skills/testing/references/report-template.md

@@ -55,7 +55,7 @@ Use this template when reporting test design issues.
 |----------|---------|---------|
 | **CRITICAL** | Fundamental design flaws | Complex setup >10 lines, repetitive boilerplate >3 times, mock objects >5 methods, testing private methods |
 | **HIGH** | Maintenance complications | Difficult mocking >20 lines, implementation testing, environment manipulation, database seeding |
-| **MEDIUM** | Reduced clarity | Test helper abuse, inconsistent assertion patterns, missing edge case coverage |
+| **MEDIUM** | Reduced clarity | Test helper abuse, inconsistent assertion patterns, a named edge case with no test |
 | **LOW** | Minor improvements | Organization, naming clarity |
 
 ---

package/src/assets/skills/testing/references/violations.md

@@ -175,7 +175,7 @@ it('marks order as paid', async () => {
 
 ## Coverage Violations [4]
 
-### Missing Edge Cases [4]
+### Missing Named Edge Cases [4]
 
 Google SWE Book: happy-path-only tests provide false confidence [4]: