From 6a3ed62be9ce171a825edf16a72c8cf9ab271bf0 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 6 Sep 2026 19:00:29 +0900 Subject: [PATCH 1/3] fix: resolve frontend type-safety guidance by guarantee, not fixed route frontend-ai-guide and quality-fixer-frontend prescribed `unknown` plus type guards as the single route for external data, while typescript-rules already permits bounded exceptions and a generated client that enforces its contract at runtime. The fixed route both duplicated and contradicted the owning policy. - frontend-ai-guide: state the anti-pattern and its avoidance as a guarantee criterion within this skill's own responsibility, without prescribing a route or depending on another progressively disclosed skill - quality-fixer-frontend: defer external API response types to the preloaded typescript-rules policy and drop the duplicate React-specific entry Co-Authored-By: Claude Opus 5 (1M context) --- agents/quality-fixer-frontend.md | 3 +-- dev-skills/skills/frontend-ai-guide/SKILL.md | 8 ++++---- dev-workflows-frontend/agents/quality-fixer-frontend.md | 3 +-- dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md | 8 ++++---- dev-workflows-fullstack/agents/quality-fixer-frontend.md | 3 +-- dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md | 8 ++++---- skills/frontend-ai-guide/SKILL.md | 8 ++++---- 7 files changed, 19 insertions(+), 22 deletions(-) diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index 101d6d8..d39ed8b 100644 --- a/agents/quality-fixer-frontend.md +++ b/agents/quality-fixer-frontend.md @@ -253,7 +253,7 @@ Between tool calls, briefly report: which phase is running, the command executed - Split components when independent rendering, state, data, or test responsibilities create material coupling or verification cost; retain a cohesive component when splitting would add avoidable prop/state synchronization - Refactor deeply nested conditionals - **Type Error Fixes** - - Handle external API responses with unknown type and type guards + - Resolve external API response types by the typescript-rules boundary validation policy - Add necessary Props type definitions - Flexibly handle with generics or union types @@ -261,7 +261,6 @@ Between tool calls, briefly report: which phase is running, the command executed ### TypeScript Errors - **Props type definition**: Add explicit type definitions for all component Props -- **Unknown API responses**: Use `unknown` type with type guards for external data - **Event handlers**: Use proper React event types (`React.ChangeEvent`, `React.MouseEvent`) - **Refs**: Use `React.RefObject` or `React.MutableRefObject` diff --git a/dev-skills/skills/frontend-ai-guide/SKILL.md b/dev-skills/skills/frontend-ai-guide/SKILL.md index 858ffc4..bb9944d 100644 --- a/dev-skills/skills/frontend-ai-guide/SKILL.md +++ b/dev-skills/skills/frontend-ai-guide/SKILL.md @@ -25,7 +25,7 @@ Pause the affected decision and review the design when detecting the following p 4. **Making changes without checking dependencies** - Potential for unexpected impacts 5. **Disabling code with comments** - Should use version control 6. **Error suppression** - Hiding problems creates technical debt -7. **Excessive use of type assertions (as)** - Abandoning type safety +7. **Type assertions standing in for a guarantee** - Declaring a type the code does not check or a contract does not establish 8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local 9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization @@ -79,10 +79,10 @@ Keep concrete implementations separate while their similarity is accidental or t **Cause**: Surface-level fixes without understanding root cause **Avoidance**: Identify root cause with 5 Whys before fixing -### Pattern 2: Abandoning Type Safety -**Symptom**: Excessive use of any type or as +### Pattern 2: Circumventing Type Guarantees +**Symptom**: `any` or `as` declares a type that no check or contract establishes **Cause**: Impulse to avoid type errors -**Avoidance**: Handle safely with unknown type and type guards +**Avoidance**: Back the declared type with a check or an existing contract that guarantees it, at the boundary where that guarantee holds ### Pattern 3: Implementation Without Sufficient Testing **Symptom**: Many bugs after implementation diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index 101d6d8..d39ed8b 100644 --- a/dev-workflows-frontend/agents/quality-fixer-frontend.md +++ b/dev-workflows-frontend/agents/quality-fixer-frontend.md @@ -253,7 +253,7 @@ Between tool calls, briefly report: which phase is running, the command executed - Split components when independent rendering, state, data, or test responsibilities create material coupling or verification cost; retain a cohesive component when splitting would add avoidable prop/state synchronization - Refactor deeply nested conditionals - **Type Error Fixes** - - Handle external API responses with unknown type and type guards + - Resolve external API response types by the typescript-rules boundary validation policy - Add necessary Props type definitions - Flexibly handle with generics or union types @@ -261,7 +261,6 @@ Between tool calls, briefly report: which phase is running, the command executed ### TypeScript Errors - **Props type definition**: Add explicit type definitions for all component Props -- **Unknown API responses**: Use `unknown` type with type guards for external data - **Event handlers**: Use proper React event types (`React.ChangeEvent`, `React.MouseEvent`) - **Refs**: Use `React.RefObject` or `React.MutableRefObject` diff --git a/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md b/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md index 858ffc4..bb9944d 100644 --- a/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md +++ b/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md @@ -25,7 +25,7 @@ Pause the affected decision and review the design when detecting the following p 4. **Making changes without checking dependencies** - Potential for unexpected impacts 5. **Disabling code with comments** - Should use version control 6. **Error suppression** - Hiding problems creates technical debt -7. **Excessive use of type assertions (as)** - Abandoning type safety +7. **Type assertions standing in for a guarantee** - Declaring a type the code does not check or a contract does not establish 8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local 9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization @@ -79,10 +79,10 @@ Keep concrete implementations separate while their similarity is accidental or t **Cause**: Surface-level fixes without understanding root cause **Avoidance**: Identify root cause with 5 Whys before fixing -### Pattern 2: Abandoning Type Safety -**Symptom**: Excessive use of any type or as +### Pattern 2: Circumventing Type Guarantees +**Symptom**: `any` or `as` declares a type that no check or contract establishes **Cause**: Impulse to avoid type errors -**Avoidance**: Handle safely with unknown type and type guards +**Avoidance**: Back the declared type with a check or an existing contract that guarantees it, at the boundary where that guarantee holds ### Pattern 3: Implementation Without Sufficient Testing **Symptom**: Many bugs after implementation diff --git a/dev-workflows-fullstack/agents/quality-fixer-frontend.md b/dev-workflows-fullstack/agents/quality-fixer-frontend.md index 101d6d8..d39ed8b 100644 --- a/dev-workflows-fullstack/agents/quality-fixer-frontend.md +++ b/dev-workflows-fullstack/agents/quality-fixer-frontend.md @@ -253,7 +253,7 @@ Between tool calls, briefly report: which phase is running, the command executed - Split components when independent rendering, state, data, or test responsibilities create material coupling or verification cost; retain a cohesive component when splitting would add avoidable prop/state synchronization - Refactor deeply nested conditionals - **Type Error Fixes** - - Handle external API responses with unknown type and type guards + - Resolve external API response types by the typescript-rules boundary validation policy - Add necessary Props type definitions - Flexibly handle with generics or union types @@ -261,7 +261,6 @@ Between tool calls, briefly report: which phase is running, the command executed ### TypeScript Errors - **Props type definition**: Add explicit type definitions for all component Props -- **Unknown API responses**: Use `unknown` type with type guards for external data - **Event handlers**: Use proper React event types (`React.ChangeEvent`, `React.MouseEvent`) - **Refs**: Use `React.RefObject` or `React.MutableRefObject` diff --git a/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md b/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md index 858ffc4..bb9944d 100644 --- a/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md @@ -25,7 +25,7 @@ Pause the affected decision and review the design when detecting the following p 4. **Making changes without checking dependencies** - Potential for unexpected impacts 5. **Disabling code with comments** - Should use version control 6. **Error suppression** - Hiding problems creates technical debt -7. **Excessive use of type assertions (as)** - Abandoning type safety +7. **Type assertions standing in for a guarantee** - Declaring a type the code does not check or a contract does not establish 8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local 9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization @@ -79,10 +79,10 @@ Keep concrete implementations separate while their similarity is accidental or t **Cause**: Surface-level fixes without understanding root cause **Avoidance**: Identify root cause with 5 Whys before fixing -### Pattern 2: Abandoning Type Safety -**Symptom**: Excessive use of any type or as +### Pattern 2: Circumventing Type Guarantees +**Symptom**: `any` or `as` declares a type that no check or contract establishes **Cause**: Impulse to avoid type errors -**Avoidance**: Handle safely with unknown type and type guards +**Avoidance**: Back the declared type with a check or an existing contract that guarantees it, at the boundary where that guarantee holds ### Pattern 3: Implementation Without Sufficient Testing **Symptom**: Many bugs after implementation diff --git a/skills/frontend-ai-guide/SKILL.md b/skills/frontend-ai-guide/SKILL.md index 858ffc4..bb9944d 100644 --- a/skills/frontend-ai-guide/SKILL.md +++ b/skills/frontend-ai-guide/SKILL.md @@ -25,7 +25,7 @@ Pause the affected decision and review the design when detecting the following p 4. **Making changes without checking dependencies** - Potential for unexpected impacts 5. **Disabling code with comments** - Should use version control 6. **Error suppression** - Hiding problems creates technical debt -7. **Excessive use of type assertions (as)** - Abandoning type safety +7. **Type assertions standing in for a guarantee** - Declaring a type the code does not check or a contract does not establish 8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local 9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization @@ -79,10 +79,10 @@ Keep concrete implementations separate while their similarity is accidental or t **Cause**: Surface-level fixes without understanding root cause **Avoidance**: Identify root cause with 5 Whys before fixing -### Pattern 2: Abandoning Type Safety -**Symptom**: Excessive use of any type or as +### Pattern 2: Circumventing Type Guarantees +**Symptom**: `any` or `as` declares a type that no check or contract establishes **Cause**: Impulse to avoid type errors -**Avoidance**: Handle safely with unknown type and type guards +**Avoidance**: Back the declared type with a check or an existing contract that guarantees it, at the boundary where that guarantee holds ### Pattern 3: Implementation Without Sufficient Testing **Symptom**: Many bugs after implementation From fbff90dd33cc1f589e253894bdc0007eae2586f1 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 6 Sep 2026 19:07:50 +0900 Subject: [PATCH 2/3] fix: flag a type assertion only when neither backing exists The anti-pattern read "a type the code does not check or a contract does not establish", which literally requires both backings and would flag an assertion that one of them already guarantees. Co-Authored-By: Claude Opus 5 (1M context) --- dev-skills/.claude-plugin/plugin.json | 2 +- dev-skills/skills/frontend-ai-guide/SKILL.md | 2 +- dev-workflows-frontend/.claude-plugin/plugin.json | 2 +- dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md | 2 +- dev-workflows-fullstack/.claude-plugin/plugin.json | 2 +- dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md | 2 +- dev-workflows/.claude-plugin/plugin.json | 2 +- skills/frontend-ai-guide/SKILL.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index fd01f99..33649b3 100644 --- a/dev-skills/.claude-plugin/plugin.json +++ b/dev-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-skills", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", - "version": "0.25.3", + "version": "0.25.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/frontend-ai-guide/SKILL.md b/dev-skills/skills/frontend-ai-guide/SKILL.md index bb9944d..e192715 100644 --- a/dev-skills/skills/frontend-ai-guide/SKILL.md +++ b/dev-skills/skills/frontend-ai-guide/SKILL.md @@ -25,7 +25,7 @@ Pause the affected decision and review the design when detecting the following p 4. **Making changes without checking dependencies** - Potential for unexpected impacts 5. **Disabling code with comments** - Should use version control 6. **Error suppression** - Hiding problems creates technical debt -7. **Type assertions standing in for a guarantee** - Declaring a type the code does not check or a contract does not establish +7. **Type assertions standing in for a guarantee** - Declaring a type established by neither a check nor an existing contract 8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local 9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 9f1e8b1..4fc8faf 100644 --- a/dev-workflows-frontend/.claude-plugin/plugin.json +++ b/dev-workflows-frontend/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-frontend", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.25.3", + "version": "0.25.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md b/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md index bb9944d..e192715 100644 --- a/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md +++ b/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md @@ -25,7 +25,7 @@ Pause the affected decision and review the design when detecting the following p 4. **Making changes without checking dependencies** - Potential for unexpected impacts 5. **Disabling code with comments** - Should use version control 6. **Error suppression** - Hiding problems creates technical debt -7. **Type assertions standing in for a guarantee** - Declaring a type the code does not check or a contract does not establish +7. **Type assertions standing in for a guarantee** - Declaring a type established by neither a check nor an existing contract 8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local 9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index e8f36f4..8ddf89f 100644 --- a/dev-workflows-fullstack/.claude-plugin/plugin.json +++ b/dev-workflows-fullstack/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-fullstack", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.25.3", + "version": "0.25.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md b/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md index bb9944d..e192715 100644 --- a/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md @@ -25,7 +25,7 @@ Pause the affected decision and review the design when detecting the following p 4. **Making changes without checking dependencies** - Potential for unexpected impacts 5. **Disabling code with comments** - Should use version control 6. **Error suppression** - Hiding problems creates technical debt -7. **Type assertions standing in for a guarantee** - Declaring a type the code does not check or a contract does not establish +7. **Type assertions standing in for a guarantee** - Declaring a type established by neither a check nor an existing contract 8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local 9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index 9683a9b..23fcf50 100644 --- a/dev-workflows/.claude-plugin/plugin.json +++ b/dev-workflows/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.25.3", + "version": "0.25.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/skills/frontend-ai-guide/SKILL.md b/skills/frontend-ai-guide/SKILL.md index bb9944d..e192715 100644 --- a/skills/frontend-ai-guide/SKILL.md +++ b/skills/frontend-ai-guide/SKILL.md @@ -25,7 +25,7 @@ Pause the affected decision and review the design when detecting the following p 4. **Making changes without checking dependencies** - Potential for unexpected impacts 5. **Disabling code with comments** - Should use version control 6. **Error suppression** - Hiding problems creates technical debt -7. **Type assertions standing in for a guarantee** - Declaring a type the code does not check or a contract does not establish +7. **Type assertions standing in for a guarantee** - Declaring a type established by neither a check nor an existing contract 8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local 9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization From 8125d91aa09759663a4d281db9a8e5f0fdfea8b3 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 6 Sep 2026 19:07:54 +0900 Subject: [PATCH 3/3] chore: bump plugin versions to 0.25.4 Co-Authored-By: Claude Opus 5 (1M context) --- .claude-plugin/marketplace.json | 8 ++++---- package.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index bff3521..dd9ea76 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "dev-workflows", "source": "./dev-workflows", "strict": true, - "version": "0.25.3", + "version": "0.25.4", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -83,7 +83,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.25.3", + "version": "0.25.4", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -157,7 +157,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.25.3", + "version": "0.25.4", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -247,7 +247,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.25.3", + "version": "0.25.4", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", "author": { "name": "Shinsuke Kagawa", diff --git a/package.json b/package.json index 842cc52..23072e2 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.25.3", + "version": "0.25.4", "private": true, "type": "module", "engines": {