Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,286 @@
|
||||
# Example: Clustering Analysis Output
|
||||
|
||||
This example shows what the clustering phase produces when analyzing a project's insights.
|
||||
|
||||
## Scenario
|
||||
|
||||
A project has been using the extract-explanatory-insights hook for 2 weeks, generating 12 insights across different categories.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Discovery Summary
|
||||
|
||||
**Total Insights Found**: 12
|
||||
**Date Range**: 2025-11-01 to 2025-11-14
|
||||
**Unique Sessions**: 8
|
||||
**Categories**:
|
||||
- testing: 5 insights
|
||||
- hooks-and-events: 3 insights
|
||||
- architecture: 2 insights
|
||||
- performance: 2 insights
|
||||
|
||||
**Preview**:
|
||||
1. "Modern Testing Strategy with Testing Trophy" (testing, 2025-11-01)
|
||||
2. "Hook Deduplication Session Management" (hooks-and-events, 2025-11-03)
|
||||
3. "CPU Usage Prevention in Vitest" (testing, 2025-11-03)
|
||||
4. "BSD awk Compatibility in Hook Scripts" (hooks-and-events, 2025-11-05)
|
||||
5. "Semantic Query Priorities in React Testing Library" (testing, 2025-11-06)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Clustering Analysis
|
||||
|
||||
### Cluster 1: Testing Strategy
|
||||
**Size**: 3 insights
|
||||
**Similarity Score**: 0.75 (high)
|
||||
**Recommended Complexity**: Standard
|
||||
**Recommended Pattern**: Validation
|
||||
|
||||
**Insights**:
|
||||
1. "Modern Testing Strategy with Testing Trophy"
|
||||
- Keywords: testing, integration, unit, e2e, trophy, kent-c-dodds
|
||||
- Category: testing
|
||||
- Date: 2025-11-01
|
||||
- Length: 156 lines
|
||||
- Has code examples: Yes
|
||||
|
||||
2. "Semantic Query Priorities in React Testing Library"
|
||||
- Keywords: testing, react, semantic, query, getByRole, accessibility
|
||||
- Category: testing
|
||||
- Date: 2025-11-06
|
||||
- Length: 89 lines
|
||||
- Has code examples: Yes
|
||||
|
||||
3. "What NOT to Test - Brittle Patterns"
|
||||
- Keywords: testing, avoid, brittle, implementation-details, user-behavior
|
||||
- Category: testing
|
||||
- Date: 2025-11-08
|
||||
- Length: 67 lines
|
||||
- Has code examples: No
|
||||
|
||||
**Shared Keywords**: testing (3), react (2), user (2), behavior (2), semantic (2)
|
||||
|
||||
**Cluster Characteristics**:
|
||||
- All in same category (testing)
|
||||
- Temporal span: 7 days
|
||||
- Common theme: User-focused testing approach
|
||||
- Total code examples: 5 blocks
|
||||
- Actionable items: 12
|
||||
|
||||
**Suggested Skill Name**: "user-focused-testing-guide"
|
||||
|
||||
**Suggested Description**: "Use PROACTIVELY when writing tests to ensure user-centric testing strategy following Testing Trophy methodology and React Testing Library best practices"
|
||||
|
||||
**Skill Structure Recommendation**:
|
||||
```
|
||||
SKILL.md sections:
|
||||
- Overview (Testing Trophy philosophy)
|
||||
- Phase 1: Query Selection (semantic queries)
|
||||
- Phase 2: Test Writing (user workflows)
|
||||
- Phase 3: Avoiding Brittle Tests
|
||||
- Important Reminders (what NOT to test)
|
||||
- Examples (from code blocks)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cluster 2: Hook Development
|
||||
**Size**: 2 insights
|
||||
**Similarity Score**: 0.68 (medium-high)
|
||||
**Recommended Complexity**: Minimal to Standard
|
||||
**Recommended Pattern**: Phase-based
|
||||
|
||||
**Insights**:
|
||||
1. "Hook Deduplication Session Management"
|
||||
- Keywords: hook, deduplication, session, hash, state
|
||||
- Category: hooks-and-events
|
||||
- Date: 2025-11-03
|
||||
- Length: 124 lines
|
||||
- Has code examples: Yes (bash)
|
||||
|
||||
2. "BSD awk Compatibility in Hook Scripts"
|
||||
- Keywords: hook, awk, bsd, macos, compatibility, portable
|
||||
- Category: hooks-and-events
|
||||
- Date: 2025-11-05
|
||||
- Length: 78 lines
|
||||
- Has code examples: Yes (bash)
|
||||
|
||||
**Shared Keywords**: hook (2), bash (2), script (2), compatibility (2)
|
||||
|
||||
**Cluster Characteristics**:
|
||||
- Same category (hooks-and-events)
|
||||
- Temporal span: 2 days (high proximity)
|
||||
- Common theme: Hook script development best practices
|
||||
- Total code examples: 4 blocks (all bash)
|
||||
- Actionable items: 8
|
||||
|
||||
**Suggested Skill Name**: "hook-script-development-guide"
|
||||
|
||||
**Suggested Description**: "Guides Claude Code hook script development with deduplication patterns and cross-platform compatibility best practices for macOS/Linux environments"
|
||||
|
||||
**Skill Structure Recommendation**:
|
||||
```
|
||||
SKILL.md sections:
|
||||
- Overview (Hook development challenges)
|
||||
- Phase 1: Deduplication Strategy (session vs content)
|
||||
- Phase 2: Cross-Platform Compatibility (BSD awk)
|
||||
- Phase 3: Testing and Validation
|
||||
- Examples (bash scripts)
|
||||
- Templates (hook-template.sh)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cluster 3: Performance Optimization
|
||||
**Size**: 2 insights
|
||||
**Similarity Score**: 0.62 (medium)
|
||||
**Recommended Complexity**: Minimal
|
||||
**Recommended Pattern**: Phase-based
|
||||
|
||||
**Insights**:
|
||||
1. "CPU Usage Prevention in Vitest"
|
||||
- Keywords: vitest, cpu, performance, threads, watch-mode
|
||||
- Category: testing
|
||||
- Date: 2025-11-03
|
||||
- Length: 45 lines
|
||||
- Has code examples: Yes (npm scripts)
|
||||
|
||||
2. "Bundle Size Optimization"
|
||||
- Keywords: bundle, size, webpack, optimization, tree-shaking
|
||||
- Category: performance
|
||||
- Date: 2025-11-09
|
||||
- Length: 92 lines
|
||||
- Has code examples: Yes (webpack config)
|
||||
|
||||
**Shared Keywords**: performance (2), optimization (2), build (2)
|
||||
|
||||
**Cluster Characteristics**:
|
||||
- Different categories (testing, performance)
|
||||
- Temporal span: 6 days
|
||||
- Common theme: Build/test performance
|
||||
- Total code examples: 3 blocks
|
||||
- Actionable items: 6
|
||||
|
||||
**Suggested Skill Name**: "build-performance-optimizer"
|
||||
|
||||
**Suggested Description**: "Analyzes build and test performance issues and generates optimization recommendations for Vitest test runs and webpack bundle sizes"
|
||||
|
||||
**Skill Structure Recommendation**:
|
||||
```
|
||||
SKILL.md sections:
|
||||
- Overview (Performance impact on DX)
|
||||
- Phase 1: Test Performance Analysis
|
||||
- Phase 2: Bundle Size Analysis
|
||||
- Phase 3: Optimization Implementation
|
||||
- Important Reminders (check before test, monitor bundle)
|
||||
- Examples (npm scripts, webpack config)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Standalone Insights
|
||||
|
||||
#### Standalone 1: "Hook State Management Patterns"
|
||||
**Quality Score**: 0.85 (high - qualifies for standalone skill)
|
||||
**Category**: hooks-and-events
|
||||
**Date**: 2025-11-07
|
||||
**Length**: 134 lines
|
||||
**Code Examples**: Yes (3 blocks)
|
||||
|
||||
**Why Standalone**:
|
||||
- Doesn't cluster with other hook insights (different focus)
|
||||
- High quality with comprehensive coverage
|
||||
- Self-contained topic (state management)
|
||||
- Multiple actionable patterns
|
||||
|
||||
**Suggested Skill Name**: "hook-state-manager"
|
||||
|
||||
**Suggested Description**: "Automates state management setup for Claude Code hooks with persistent storage, cleanup, and safe concurrency patterns"
|
||||
|
||||
---
|
||||
|
||||
#### Standalone 2: "Architecture Decision Records"
|
||||
**Quality Score**: 0.82 (high - qualifies for standalone skill)
|
||||
**Category**: architecture
|
||||
**Date**: 2025-11-12
|
||||
**Length**: 156 lines
|
||||
**Code Examples**: Yes (template)
|
||||
|
||||
**Why Standalone**:
|
||||
- Unique topic (no other architecture insights)
|
||||
- High quality with complete template
|
||||
- Valuable for documentation
|
||||
- Industry best practice
|
||||
|
||||
**Suggested Skill Name**: "adr-documentation-helper"
|
||||
|
||||
**Suggested Description**: "Guides creation of Architecture Decision Records (ADRs) following industry standards with templates and integration with project documentation"
|
||||
|
||||
---
|
||||
|
||||
### Low-Quality Insights (Not Recommended for Skills)
|
||||
|
||||
#### "Git Branch Naming Convention"
|
||||
**Quality Score**: 0.42 (low)
|
||||
**Category**: version-control
|
||||
**Reason for Exclusion**: Too simple, covered by existing conventions, no unique value
|
||||
|
||||
#### "TypeScript Strict Mode Benefits"
|
||||
**Quality Score**: 0.38 (low)
|
||||
**Category**: typescript
|
||||
**Reason for Exclusion**: Common knowledge, well-documented elsewhere, not actionable enough
|
||||
|
||||
---
|
||||
|
||||
## User Decision Points
|
||||
|
||||
At this stage, the skill would present the following options to the user:
|
||||
|
||||
**Option 1: Generate All Recommended Skills** (5 skills)
|
||||
- user-focused-testing-guide (Cluster 1)
|
||||
- hook-script-development-guide (Cluster 2)
|
||||
- build-performance-optimizer (Cluster 3)
|
||||
- hook-state-manager (Standalone 1)
|
||||
- adr-documentation-helper (Standalone 2)
|
||||
|
||||
**Option 2: Select Specific Skills**
|
||||
- User picks which clusters/standalones to convert
|
||||
|
||||
**Option 3: Modify Clusters**
|
||||
- Split large clusters
|
||||
- Merge small clusters
|
||||
- Recategorize insights
|
||||
- Adjust complexity levels
|
||||
|
||||
**Option 4: Tune Thresholds and Retry**
|
||||
- Increase cluster_minimum (0.6 → 0.7) for tighter clusters
|
||||
- Decrease standalone_quality (0.8 → 0.7) for more standalone skills
|
||||
|
||||
---
|
||||
|
||||
## Proceeding to Phase 3
|
||||
|
||||
If user selects "user-focused-testing-guide" to generate, the skill would proceed to Phase 3: Interactive Skill Design with the following proposal:
|
||||
|
||||
**Skill Design Proposal**:
|
||||
- Name: `user-focused-testing-guide`
|
||||
- Description: "Use PROACTIVELY when writing tests to ensure user-centric testing strategy following Testing Trophy methodology and React Testing Library best practices"
|
||||
- Complexity: Standard
|
||||
- Pattern: Validation
|
||||
- Structure:
|
||||
- SKILL.md with validation workflow
|
||||
- data/insights-reference.md with 3 source insights
|
||||
- examples/query-examples.md with semantic query patterns
|
||||
- templates/test-checklist.md with testing checklist
|
||||
|
||||
User can then customize before generation begins.
|
||||
|
||||
---
|
||||
|
||||
**This example demonstrates**:
|
||||
1. How clustering groups related insights
|
||||
2. What information is presented for each cluster
|
||||
3. How standalone insights are identified
|
||||
4. Why some insights are excluded
|
||||
5. What decisions users can make
|
||||
6. How the process flows into Phase 3
|
||||
Reference in New Issue
Block a user